event-driven-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

当激活该Skill时，你的第一条回复请始终以🧢表情开头。

Event-Driven Architecture

A comprehensive guide to building systems where components communicate through events rather than direct calls. Event-driven architecture (EDA) decouples producers from consumers, enabling independent scaling, temporal decoupling, and resilience to downstream failures. This skill covers four core pillars: event sourcing (storing state as a sequence of events), CQRS (separating read and write models), message brokers (the transport layer), and eventual consistency (the consistency model that makes it all work). Agents use this skill to design, implement, and troubleshoot event-driven systems at any scale.

这是一份关于构建组件通过事件而非直接调用进行通信的系统的综合指南。Event-Driven Architecture（EDA）实现了生产者与消费者的解耦，支持独立扩展、时间解耦，并能抵御下游故障。该Skill涵盖四大核心支柱：Event Sourcing（将状态存储为事件序列）、CQRS（分离读写模型）、Message Broker（传输层）以及最终一致性（支撑整个架构的一致性模型）。Agent可使用该Skill来设计、实现和排查任意规模的事件驱动系统。

When to use this skill

何时使用该Skill

Trigger this skill when the user:

Wants to implement event sourcing for an aggregate or service
Needs to separate read and write models using CQRS
Is choosing between Kafka, RabbitMQ, NATS, or other message brokers
Asks about eventual consistency, compensation, or saga patterns
Wants to design an event schema or event versioning strategy
Needs to handle idempotency in event consumers
Is debugging issues with message ordering, duplicate delivery, or consumer lag
Asks about domain events, integration events, or event-carried state transfer

Do NOT trigger this skill for:

Synchronous REST API design without an event component (use api-design)
General system design questions about load balancers, caches, or CDNs (use system-design)

当用户有以下需求时，触发该Skill：

想要为聚合根或服务实现Event Sourcing
需要使用CQRS分离读写模型
正在Kafka、RabbitMQ、NATS或其他Message Broker之间做选型
询问关于最终一致性、补偿机制或Saga模式的问题
想要设计事件Schema或事件版本策略
需要处理事件消费者的幂等性问题
正在排查消息排序、重复投递或消费者延迟等问题
询问领域事件、集成事件或事件携带状态传输的相关内容

请勿在以下场景触发该Skill：

无事件组件的同步REST API设计（请使用api-design Skill）
关于负载均衡器、缓存或CDN的通用系统设计问题（请使用system-design Skill）

Key principles

核心原则

Events are facts, not requests - An event records something that already happened (OrderPlaced, PaymentReceived). It is immutable. Commands request something to happen (PlaceOrder). Never conflate the two. Events use past tense; commands use imperative.
Design for at-least-once delivery - No message broker guarantees exactly-once delivery in all failure scenarios. Design every consumer to be idempotent. Use deduplication keys (event ID + consumer ID) or make operations naturally idempotent (SET over INCREMENT).
Own your events, share your contracts - The producing service owns the event schema. Consumers must not dictate what goes in an event. Publish a versioned schema contract (Avro, Protobuf, or JSON Schema) so consumers can evolve independently.
Separate the write model from the read model - CQRS lets you optimize writes for consistency and reads for query performance independently. The write side validates business rules; the read side denormalizes for fast lookups. They connect through events.
Embrace eventual consistency, but bound it - Eventual consistency is not "maybe consistent." Define SLAs for propagation delay (e.g., "read model updated within 2 seconds of write"). Monitor consumer lag. Alert when the bound is breached.

事件是事实，而非请求 - 事件记录已发生的事情（如OrderPlaced、PaymentReceived），它是不可变的。命令则是请求执行某操作（如PlaceOrder）。切勿将两者混淆。事件使用过去式；命令使用祈使语气。
按至少一次投递设计 - 没有任何Message Broker能在所有故障场景下保证精确一次投递。请为每个消费者设计幂等性处理。使用去重键（事件ID + 消费者ID），或采用天然具备幂等性的操作（如使用SET而非INCREMENT）。
拥有你的事件，共享契约 - 生产服务拥有事件Schema的所有权，消费者不得决定事件中包含的内容。发布带版本的Schema契约（如Avro、Protobuf或JSON Schema），以便消费者能够独立演进。
分离读写模型 - CQRS允许你独立优化写模型的一致性和读模型的查询性能。写侧验证业务规则并发布事件；读侧将数据反规范化以实现快速查询。两者通过事件进行关联。
接纳最终一致性，但设定边界 - 最终一致性并非“可能一致”，而是指写入操作完成后，所有读副本和投影最终会收敛到同一状态，但不会立即完成。写入与收敛之间的时间差即为传播延迟。请为传播延迟定义SLA（例如：“写入后2秒内更新读模型”），监控消费者延迟，并在超出边界时触发告警。

Core concepts

核心概念

Events are immutable records of state changes. A domain event captures a meaningful business occurrence within a bounded context (OrderPlaced). An integration event crosses context boundaries and should carry only the data consumers need - not the entire aggregate state. Event-carried state transfer includes enough data in the event so consumers never need to call back to the producer.

Event sourcing stores the current state of an entity as a sequence of events rather than a single mutable row. To get current state, replay all events for that aggregate from the event store. Snapshots periodically checkpoint state to avoid replaying the full history. The event store is append-only - never update or delete events. This gives a complete audit trail and enables temporal queries ("what was the order state at 3pm yesterday?").

CQRS (Command Query Responsibility Segregation) splits a service into a command side that handles writes and a query side that handles reads. The command side validates invariants and emits events. The query side subscribes to those events and builds denormalized read models (projections) optimized for specific queries. CQRS does not require event sourcing, and event sourcing does not require CQRS - but they pair naturally because the event log is the bridge between the two sides.

Message brokers are the transport layer. They sit between producers and consumers and handle routing, delivery guarantees, and backpressure. Key broker categories: log-based (Kafka, Redpanda) retain ordered, replayable event logs; queue-based (RabbitMQ, SQS) deliver messages to consumers and remove them after acknowledgment. Choose log-based when you need replay, ordering, and multiple consumer groups. Choose queue-based for simple task distribution and routing flexibility.

Eventual consistency means that after a write, all read replicas and projections will converge to the same state - but not instantly. The gap between write and convergence is the propagation delay. Sagas coordinate multi-service transactions: each step emits an event, and failure triggers compensating events that undo prior steps (e.g., PaymentFailed triggers OrderCancelled). Prefer choreography (services react to events) over orchestration (a central coordinator sends commands) for loosely coupled systems.

Event（事件） 是状态变更的不可变记录。领域事件捕获限界上下文内有意义的业务发生（如OrderPlaced）。集成事件跨越上下文边界，应仅携带消费者所需的数据——而非整个聚合根状态。事件携带状态传输指在事件中包含足够的数据，使消费者无需回调生产者。

Event Sourcing（事件溯源） 将实体的当前状态存储为一系列事件，而非单个可变行。要获取当前状态，需从事件存储中重放该聚合根的所有事件。定期生成快照以checkpoint状态，避免重放完整历史记录。事件存储是仅追加的——切勿更新或删除事件。这提供了完整的审计轨迹，并支持时间查询（例如：“昨天下午3点时订单的状态是什么？”）。

CQRS（命令查询职责分离） 将服务拆分为处理写入的命令侧和处理读取的查询侧。命令侧验证不变量并发布事件；查询侧订阅这些事件，并构建针对特定查询优化的反规范化读模型（投影）。CQRS不依赖Event Sourcing，Event Sourcing也不依赖CQRS——但它们天然适配，因为事件日志是连接两侧的桥梁。

Message Broker（消息中间件） 是传输层，位于生产者和消费者之间，负责路由、投递保障和背压处理。主要的中间件类别：基于日志的（Kafka、Redpanda）保留有序、可重放的事件日志；基于队列的（RabbitMQ、SQS）将消息投递到消费者，并在确认后删除它们。当你需要重放、排序和多个消费者组时，选择基于日志的中间件；当需要简单任务分发和路由灵活性时，选择基于队列的中间件。

最终一致性 指写入操作完成后，所有读副本和投影将收敛到同一状态——但并非即时完成。写入与收敛之间的间隔即为传播延迟。Saga协调多服务事务：每个步骤发布一个事件，失败时触发补偿事件以撤销之前的步骤（例如：PaymentFailed触发OrderCancelled）。对于松耦合系统，优先选择choreography（服务响应事件）而非orchestration（中央协调器发送命令）。

Common tasks

常见任务

Implement event sourcing for an aggregate

为聚合根实现Event Sourcing

Store all state changes as events. Rebuild current state by replaying them.

Event store schema (PostgreSQL example):

sql

CREATE TABLE events (
  event_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  aggregate_id UUID NOT NULL,
  aggregate_type VARCHAR(100) NOT NULL,
  event_type   VARCHAR(100) NOT NULL,
  event_data   JSONB NOT NULL,
  metadata     JSONB DEFAULT '{}',
  version      INTEGER NOT NULL,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (aggregate_id, version)
);

Aggregate reconstruction:

python

def load_aggregate(aggregate_id: str) -> Order:
    events = event_store.get_events(aggregate_id)
    order = Order()
    for event in events:
        order.apply(event)
    return order

Use the UNIQUE constraint on (aggregate_id, version) for optimistic concurrency. If two commands try to append at the same version, one fails - retry it.

将所有状态变更存储为事件，通过重放这些事件来重建当前状态。

事件存储Schema（PostgreSQL示例）：

sql

CREATE TABLE events (
  event_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  aggregate_id UUID NOT NULL,
  aggregate_type VARCHAR(100) NOT NULL,
  event_type   VARCHAR(100) NOT NULL,
  event_data   JSONB NOT NULL,
  metadata     JSONB DEFAULT '{}',
  version      INTEGER NOT NULL,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (aggregate_id, version)
);

聚合根重建：

python

def load_aggregate(aggregate_id: str) -> Order:
    events = event_store.get_events(aggregate_id)
    order = Order()
    for event in events:
        order.apply(event)
    return order

使用(aggregate_id, version)上的UNIQUE约束实现乐观并发控制。如果两个命令尝试在同一版本追加事件，其中一个会失败——请重试该命令。

Set up CQRS with separate read/write models

搭建分离读写模型的CQRS

The command side validates and persists events. The query side projects events into denormalized views.

Command side: Receives commands, loads aggregate from event store, validates business rules, appends new events.

Query side: Subscribes to event stream, updates read-optimized projections (e.g., a materialized view in PostgreSQL, an Elasticsearch index, or a Redis hash).

Projection example:

python

class OrderSummaryProjection:
    def handle(self, event):
        if event.type == "OrderPlaced":
            db.upsert("order_summaries", {
                "order_id": event.data["order_id"],
                "customer": event.data["customer_name"],
                "total": event.data["total"],
                "status": "placed"
            })
        elif event.type == "OrderShipped":
            db.update("order_summaries",
                where={"order_id": event.data["order_id"]},
                set={"status": "shipped"})

Keep projections rebuildable. If a projection is corrupted, delete it and replay all events from the store to reconstruct it from scratch.

命令侧验证并持久化事件，查询侧将事件投影到反规范化视图中。

命令侧： 接收命令，从事件存储加载聚合根，验证业务规则，追加新事件。

查询侧： 订阅事件流，更新针对读取优化的投影（例如PostgreSQL中的物化视图、Elasticsearch索引或Redis哈希）。

投影示例：

python

class OrderSummaryProjection:
    def handle(self, event):
        if event.type == "OrderPlaced":
            db.upsert("order_summaries", {
                "order_id": event.data["order_id"],
                "customer": event.data["customer_name"],
                "total": event.data["total"],
                "status": "placed"
            })
        elif event.type == "OrderShipped":
            db.update("order_summaries",
                where={"order_id": event.data["order_id"]},
                set={"status": "shipped"})

确保投影可重建。如果投影损坏，删除它并从事件存储重放所有事件，从头开始重建。

Choose a message broker

选择Message Broker

Requirement	Recommended broker
Ordered event log with replay	Kafka or Redpanda
Simple task queue with routing	RabbitMQ
Serverless / managed queue	AWS SQS + SNS
Low-latency pub/sub	NATS
Multi-protocol flexibility	RabbitMQ (AMQP, MQTT, STOMP)

Kafka specifics: Topics are partitioned. Order is guaranteed only within a partition. Use the aggregate ID as the partition key to ensure all events for one entity land on the same partition in order. Consumer groups enable parallel consumption - each partition is read by exactly one consumer in a group.

RabbitMQ specifics: Supports direct, fanout, topic, and header exchanges. Use dead-letter exchanges for failed messages. Prefetch count controls how many unacked messages a consumer holds - set it to prevent memory exhaustion.

需求	推荐中间件
有序事件日志且支持重放	Kafka或Redpanda
带路由的简单任务队列	RabbitMQ
无服务器/托管队列	AWS SQS + SNS
低延迟发布订阅	NATS
多协议灵活性	RabbitMQ（支持AMQP、MQTT、STOMP）

Kafka细节： Topic是分区的，仅在分区内保证顺序。使用聚合根ID作为分区键，确保同一实体的所有事件按顺序落在同一个分区中。消费者组支持并行消费——每个分区由组内的恰好一个消费者读取。

RabbitMQ细节： 支持direct、fanout、topic和header交换器。为失败消息配置死信队列（DLQ）。预取计数控制消费者持有的未确认消息数量——设置该值以防止内存耗尽。

Design a saga for distributed transactions

为分布式事务设计Saga

A saga is a sequence of local transactions coordinated through events. Each step has a compensating action that undoes it on failure.

Choreography-based saga (preferred for loose coupling):

OrderService  --OrderPlaced-->  PaymentService
PaymentService --PaymentSucceeded-->  InventoryService
InventoryService --InventoryReserved-->  ShippingService

On failure:
PaymentService --PaymentFailed-->  OrderService (compensate: cancel order)
InventoryService --InsufficientStock-->  PaymentService (compensate: refund)

Orchestration-based saga (use when coordination logic is complex): A central OrderSaga orchestrator sends commands to each service and tracks state. Easier to reason about, but the orchestrator is a single point of coupling.

Always define the compensating action for every step before implementing the happy path. If you cannot compensate a step, it must be the last step in the saga.

Saga是通过事件协调的一系列本地事务。每个步骤都有对应的补偿操作，在失败时撤销该步骤的影响。

基于choreography的Saga（松耦合系统首选）：

OrderService  --OrderPlaced-->  PaymentService
PaymentService --PaymentSucceeded-->  InventoryService
InventoryService --InventoryReserved-->  ShippingService

失败时：
PaymentService --PaymentFailed-->  OrderService（补偿：取消订单）
InventoryService --InsufficientStock-->  PaymentService（补偿：退款）

基于orchestration的Saga（协调逻辑复杂时使用）： 中央OrderSaga编排器向每个服务发送命令并跟踪状态。这种方式更易于理解，但编排器是单点耦合点。

在实现正常流程之前，务必为每个步骤定义补偿操作。如果某个步骤无法补偿，它必须是Saga中的最后一个步骤。

Handle idempotency in consumers

处理消费者的幂等性

Duplicate messages are inevitable. Every consumer must handle them safely.

Strategy 1 - Deduplication table:

sql

CREATE TABLE processed_events (
  event_id UUID PRIMARY KEY,
  processed_at TIMESTAMPTZ DEFAULT now()
);

Before processing, check if event_id exists. Use a transaction to atomically insert into processed_events and execute the business logic.

Strategy 2 - Natural idempotency: Use operations that produce the same result regardless of how many times they run.

SET status = 'shipped'

is idempotent.

INCREMENT counter

is not. Prefer SET-style operations where possible.

重复消息是不可避免的，每个消费者都必须能安全处理重复消息。

策略1 - 去重表：

sql

CREATE TABLE processed_events (
  event_id UUID PRIMARY KEY,
  processed_at TIMESTAMPTZ DEFAULT now()
);

处理前，检查event_id是否已存在。使用事务原子性地将event_id插入processed_events并执行业务逻辑。

策略2 - 天然幂等性： 使用无论执行多少次结果都相同的操作。

SET status = 'shipped'

是幂等的，

INCREMENT counter

则不是。尽可能优先选择SET类操作。

Design event schema and versioning

设计事件Schema与版本策略

Schema structure:

json

{
  "event_id": "uuid",
  "event_type": "OrderPlaced",
  "aggregate_id": "uuid",
  "version": 1,
  "timestamp": "2026-03-14T10:00:00Z",
  "data": {
    "order_id": "uuid",
    "customer_id": "uuid",
    "items": [],
    "total": 4999
  },
  "metadata": {
    "correlation_id": "uuid",
    "causation_id": "uuid",
    "user_id": "uuid"
  }
}

Versioning strategies:

Upcasting: Transform old events to the new schema at read time. The event store keeps the original; the reader converts on the fly.
Schema registry: Use Confluent Schema Registry (Avro/Protobuf) or a custom registry for JSON Schema. Enforce backward compatibility on every schema change.
Weak schema: Add new fields as optional with defaults. Never remove or rename fields in a non-breaking way.

Always include correlation_id and causation_id in metadata. Correlation ID traces the full business flow; causation ID links to the specific event that caused this one.

Schema结构：

json

{
  "event_id": "uuid",
  "event_type": "OrderPlaced",
  "aggregate_id": "uuid",
  "version": 1,
  "timestamp": "2026-03-14T10:00:00Z",
  "data": {
    "order_id": "uuid",
    "customer_id": "uuid",
    "items": [],
    "total": 4999
  },
  "metadata": {
    "correlation_id": "uuid",
    "causation_id": "uuid",
    "user_id": "uuid"
  }
}

版本策略：

Upcasting（向上转换）： 在读取时将旧事件转换为新Schema。事件存储保留原始事件，读取器实时转换。
Schema注册表： 使用Confluent Schema Registry（Avro/Protobuf）或自定义JSON Schema注册表。每次Schema变更都要保证向后兼容性。
弱Schema： 新增字段设为可选并提供默认值。切勿以非兼容方式删除或重命名字段。

务必在metadata中包含correlation_id和causation_id。Correlation ID跟踪完整业务流程；Causation ID链接到触发当前事件的特定事件。

Anti-patterns / common mistakes

反模式/常见错误

Mistake	Why it's wrong	What to do instead
Using events as remote procedure calls	Tight coupling disguised as events; consumers depend on producer behavior	Events describe what happened, not what should happen next
Giant events with full aggregate state	Consumers couple to the producer's internal model; any schema change breaks everyone	Include only the data consumers need; use event-carried state transfer selectively
No dead-letter queue	Poison messages block the entire consumer; one bad event stops all processing	Configure a DLQ on every queue; alert on DLQ depth; review and reprocess manually
Ordering across partitions	Kafka only guarantees order within a partition; assuming global order causes race conditions	Partition by aggregate ID; accept that cross-aggregate ordering requires explicit coordination
Skipping idempotency because "the broker handles it"	At-least-once is the realistic guarantee; exactly-once has caveats and performance costs	Build idempotency into every consumer with dedup tables or natural idempotency
Unbounded event store without snapshots	Aggregate reconstruction slows to a crawl as event count grows	Snapshot every N events (e.g., every 100); load from latest snapshot then replay remaining events

错误做法	错误原因	正确做法
将事件用作远程过程调用	这是伪装成事件的紧耦合，消费者依赖生产者的行为	事件应描述已发生的事情，而非下一步应该做什么
包含完整聚合根状态的巨型事件	消费者与生产者的内部模型耦合，任何Schema变更都会影响所有消费者	仅包含消费者所需的数据；选择性使用事件携带状态传输
未配置死信队列（DLQ）	有毒消息会阻塞整个消费者，一条坏事件会停止所有处理	为每个队列配置DLQ；监控DLQ深度；手动审核并重处理消息
跨分区排序	Kafka仅在分区内保证顺序，假设全局顺序会导致竞态条件	按聚合根ID分区；接受跨聚合根的排序需要显式协调
因为“中间件会处理”而跳过幂等性	实际能保证的是至少一次投递，精确一次投递有局限性且性能成本高	为每个消费者实现幂等性，可使用去重表或天然幂等操作
无快照的无界事件存储	随着事件数量增长，聚合根重建速度会变得极慢	每N个事件生成一次快照（例如每100个）；从最新快照加载，然后重放剩余事件

References

参考资料

For detailed content on specific sub-topics, read the relevant file from the

references/

folder:

```
references/event-sourcing-patterns.md
```
- Advanced event sourcing patterns including snapshots, projections, temporal queries, and event store implementation details
```
references/broker-comparison.md
```
- Deep comparison of Kafka, RabbitMQ, NATS, SQS/SNS, and Pulsar with configuration examples and operational guidance

Only load a references file if the current task requires it - they are long and will consume context.

如需特定子主题的详细内容，请阅读

references/

文件夹中的相关文件：

```
references/event-sourcing-patterns.md
```
- 高级Event Sourcing模式，包括快照、投影、时间查询和事件存储实现细节
```
references/broker-comparison.md
```
- Kafka、RabbitMQ、NATS、SQS/SNS和Pulsar的深度对比，包含配置示例和运维指南

仅在当前任务需要时加载参考文件——这些文件内容较长，会占用上下文空间。

event-driven-architecture

Original

Translation

Event-Driven Architecture

Event-Driven Architecture

When to use this skill

何时使用该Skill

Key principles

核心原则

Core concepts

核心概念

Common tasks

常见任务

Implement event sourcing for an aggregate

为聚合根实现Event Sourcing

Set up CQRS with separate read/write models

搭建分离读写模型的CQRS

Choose a message broker

选择Message Broker

Design a saga for distributed transactions

为分布式事务设计Saga

Handle idempotency in consumers

处理消费者的幂等性

Design event schema and versioning

设计事件Schema与版本策略

Anti-patterns / common mistakes

反模式/常见错误

References

参考资料

Related skills

相关Skill