// RULES
Microservice rules
Best practices for microservices, one rule per page: why it matters, how to apply it and an example. They are grouped into checklists you can apply to a service.
12 rules of 70 · Clear filters
Events
- Consumed events have a schema
For every event it consumes, the service records the payload it relies on, so a publisher change that breaks it can be seen in advance.
HighChecked automatically
- Event consumers handle duplicates
Every consumed event can arrive more than once; processing it twice must not change the outcome.
HighChecked by hand
- Event schemas evolve compatibly
A change to a published event never breaks a consumer already reading it: fields are added, not renamed or removed.
HighChecked by hand
- Events are published through an outbox
A state change and the event that announces it are saved together, so one never happens without the other.
HighChecked by hand
- Messages that keep failing go to a dead-letter queue
A message the consumer cannot process is set aside after a few attempts, with an alert, so it neither blocks the queue nor disappears.
HighChecked by hand
- Published events have a schema
Every event the service publishes has a declared payload, so consumers code against a contract and not against samples.
HighChecked automatically
- Consumed events name their publisher
Each consumed event says which service publishes it, so the dependency shows up in the catalog and in impact analysis.
MediumChecked automatically
- Events are named as facts, in the past tense
An event name says what happened (OrderPlaced), not what someone should do (CreateOrder).
MediumChecked automatically
- Events carry an id, a time and a version
Every published event has a unique id, the time it happened, its type and its schema version, in the same place on every event.
MediumChecked by hand
- Ordering needs are explicit
The service states which events must be processed in order and how that is guaranteed, and copes with the rest arriving out of order.
MediumChecked by hand
- Published events name their broker and topic
Each published event says where it is published, so a consumer knows where to subscribe.
MediumChecked automatically
- Stale data is expected and handled
Where the service acts on data copied from events, it says how stale that data can be and what happens when it is.
MediumChecked by hand