Microservices Architecture Best Practices: 7 Rules for Service Boundaries

What Microservice Boundary Discipline Actually Protects

Ask five engineers why a service boundary got violated and four will describe a shortcut someone took under deadline pressure. That's usually wrong. The person who introduced it wasn't cutting a corner - they were doing the fastest, most defensible thing available to someone who could only see their own service. Querying another team's table directly is less code than calling their API and handling its failure modes.

None of the seven principles below are really about carelessness. They're about the fact that the correct decision from inside a single service and the correct decision for the system are different decisions, and the gap between them is invisible from any seat that only has visibility into one service.

1. Data Ownership Defines the Service Boundary

You've paid the operational cost of splitting into services and gotten none of the benefit: two teams still can't deploy independently, because a migration in one service's schema silently breaks a query running in another. The rule is specific on purpose: a service's persisted data is read and written only by code that service owns, and every other service reaches it through that service's API or the events it emits.

SELECT o.id, o.total, i.sku, i.quantity_available
FROM orders.order_items o
JOIN inventory.stock i ON o.sku = i.sku
WHERE o.order_id = $1;

order = order_repo.get(order_id)
stock = inventory_client.get_stock(order.sku)  # owned by Inventory

The honest tradeoff: the SQL join is faster to write and run. Going through an API means handling latency and partial availability a local join never had to think about — that cost is the price of the services actually being independently deployable.

2. Publish a Contract, Not Your Data Model

The failure shows up as a "breaking change" nobody remembers agreeing to expose. An internal column gets added for an unrelated reason, and because that entity is what the endpoint returns, it's now in the public response. The fix: every inter-service interface gets a distinct type, mapped explicitly at the boundary, generated from a schema artifact committed to the repo.

@app.get("/orders/{order_id}")
def get_order(order_id: int, db: Session = Depends(get_db)):
    return db.query(Order).filter(Order.id == order_id).first()

@app.get("/orders/{order_id}", response_model=OrderContractV1)
def get_order(order_id: int, db: Session = Depends(get_db)):
    order = db.query(Order).filter(Order.id == order_id).first()
    return OrderContractV1.from_orm(order)

This is the Bounded Context idea applied at the wire level: the model you use to think about your own data and the model you expose to someone else's don't have to be the same object.

3. Every Contract Change Must Be Additive

A field gets renamed because it was never used - as far as the producer can tell. Three deploys later, a consumer's integration test fails, and the review discovers a service that had been reading that field the whole time. Contracts only grow: never remove, rename, or repurpose a field on a published contract. Do it additively, in a new version, and let old and new coexist until every consumer has moved.

@JsonIgnoreProperties(ignoreUnknown = true)
public class OrderPlacedEventV2 {
    private String orderId;
    private String eventVersion;
    private String promotionCode; // added additively
}

The proto3 language guide's section on updating a message type and the reasoning behind Consumer-Driven Contracts both amount to the same instruction: design the contract for the consumers you don't know about yet.

Tradeoff worth naming: additive-only evolution means contracts accumulate deprecated fields nobody's allowed to clean up quickly. That's real. It's cheaper than a breaking change that fails at a time and place you don't control.

4. Design the Failure Path Before the Happy One

A payment succeeds. The inventory reservation that was supposed to happen right after it fails. Now there's a charged customer with no order, no automatic reversal, and an on-call engineer patching rows at 2 a.m. A write that spans services needs local transactions with explicit compensating actions, coordinated by a saga — and a state change and its event should never be split across a commit boundary.

BEGIN;
UPDATE orders SET status = 'CONFIRMED' WHERE id = $1;
INSERT INTO outbox (aggregate_id, event_type, payload, created_at)
VALUES ($1, 'OrderConfirmed', $2, now());
COMMIT;

The transactional outbox and saga patterns exist specifically because distributed writes lose the ACID guarantees a monolith took for granted, and pretending otherwise just moves the failure from architecture into an incident.

The tradeoff is eventual consistency and more infrastructure — a relay, a saga coordinator — in exchange for giving up the illusion that a synchronous call chain was ever atomic in the first place.

5. Every Inter-Service Call Carries a Price

An aggregation endpoint that lists a customer's orders looks fine with ten orders and falls over with two hundred, because it calls the customer service once per order. Batch instead of looping. Start independent calls concurrently instead of awaiting them one at a time. Bound every collection response with a server-enforced page size.

const orders = await orderRepo.list(customerId);
for (const order of orders) {
  order.customerName = await customerClient.get(order.customerId); // N calls
}

const orders = await orderRepo.list(customerId);
const customerIds = [...new Set(orders.map(o => o.customerId))];
const customers = await customerClient.getBatch(customerIds);

Diagnostic worth running: pick any endpoint that aggregates data from more than one service, and check whether its p99 latency is closer to the SUM of its dependencies' latencies or the MAX. Sum means someone's awaiting sequentially when they didn't need to.

6. Network Location Is Not Authentication

An internal endpoint has no auth check because it's assumed nothing outside the cluster can reach it. That assumption holds right up until a lower-privilege service in the same cluster calls it directly. Every inter-service call needs to authenticate against a verified workload identity - a signed token or mutual TLS certificate - never implicitly trusted because of where the request came from.

Diagnostic worth running: can any pod in your cluster reach a given internal endpoint and get a 200 response without presenting a token or certificate? If yes, that endpoint isn't private - it's public with an informal gate.

NIST SP 800-207, Zero Trust Architecture, is the standards-body version of this instruction: stop treating network position as a substitute for verified identity. It's genuinely expensive to operationalize — certificate rotation, identity issuance, usually a service mesh — which is exactly why it needs to be checked rather than assumed.

7. Code Reuse Is How Boundaries Dissolve

Two teams independently notice they're writing nearly identical discount logic and extract it into a shared library both services import. Six months later, a pricing bug fix requires coordinating a release across nine services, because core business logic now lives in an import statement instead of inside any service's boundary. Shared libraries should carry technical plumbing only - logging, tracing, generated clients - never a business rule.

Rule of thumb: if a bug fix in a shared library requires redeploying more than one service before it takes effect, the library isn't shared infrastructure. It's an unshipped extra service.

This is the principle that makes the rest of this guide's argument land, because nobody involved in creating that shared library did anything a code reviewer would have flagged. Sandi Metz has made the opposite case of DRY — that tolerating duplicate code is usually cheaper than living with the wrong shared abstraction — and it's counterintuitive precisely because a standard engineering education points the other way.

How Pandorian Enforces This Guide

Every principle above survives a design review. Few survive six months of independent team decisions, because the violations aren't visible from inside any one pull request - they're visible only in the aggregate. Pandorian enforces this guide across three surfaces:

Caught at PR level

Every pull request is checked against the guideline before merge. A new foreign key across a service boundary, a schema change that narrows a field's type, a call sitting inside a loop - these surface with the specific line, the rule, and a suggested fix.

Full scans

An on-demand scan across the whole codebase establishes the day-one baseline: where direct database access already exists, which services lack workload identity checks, where shared libraries already carry business logic.

Scheduled scans

The same full scan, run on a cadence, catches drift introduced outside any pull request - a mesh policy change that drops mTLS enforcement, a new service deployed without the identity checks the rest of the fleet has.

A Taste of the Guideline Package

Four of the checks that ship in this package - each runs at the PR level, on full or scheduled scans, or several at once.

FAQ