event-driven-architect

事件驱动架构师

设计以持久化事件、明确契约和运维安全的消费者为核心构建的异步系统。

范围： 事件驱动的应用架构和可靠性模式。不适用于同步 API 设计（api-designer）或批处理 ETL 管道设计（data-pipeline-architect）。

规范术语

术语	定义
event	对已发生事项的不可变记录
command	执行某项操作的请求，而非事实
topic	携带相关事件的命名流或通道
partition key	用于保留一部分事件顺序的值
consumer group	处理同一 topic 的独立工作者集合
idempotency key	用于确保重复处理安全的稳定标识
dead-letter queue	存放超过常规重试次数的消息的区域
outbox	用于从数据库变更发布事件的事务模式
saga	通过事件和补偿操作协调的多步骤工作流
contract version	用于事件架构演进的兼容性标记

分派

$ARGUMENTS	模式
design <domain or workflow>	设计事件驱动架构
review <architecture or code path>	审查现有事件流
contract <event>	定义或演进事件契约
reliability <flow>	设计重试、顺序和恢复机制
migration <change>	规划事件流的采用或替换
关于队列、代理或异步工作流的自然语言描述	自动检测最匹配的模式
空	显示带示例的模式菜单

模式菜单

#	模式	示例
1	设计	design order fulfillment across payments, inventory, and shipping
2	审查	review event flow for user-created -> email sync
3	契约	contract invoice.paid
4	可靠性	reliability retry strategy for webhook ingestion
5	迁移	migration move monolith side effects to events

适用场景

• 设计跨服务或限界上下文的异步工作流
• 选择事件契约、分区键或消费者职责
• 引入 outbox、重试、重放或死信处理
• 审查事件系统是否具备韧性，或是否存在过度耦合
• 规划从同步副作用迁移到持久化事件

分类逻辑

分类关卡

1. 如果任务涉及同步 API 设计、请求-响应契约或 CRUD 端点形态，请使用 api-designer。
2. 如果任务涉及批处理 ETL、数据仓库迁移或面向分析的转换，请使用 data-pipeline-architect。
3. 如果任务涉及代理安装、特定供应商的配置或平台运维，请使用相关的平台或 devops 技能。
4. 如果工作流含义不明确，请先判断系统是否以持久化事实、异步协调和支持安全重放的消费者为核心。只有答案为是时，才使用此技能。

渐进式披露

• 让 SKILL.md 聚焦于路由、操作步骤和不可妥协的约束。
• 按指示阅读参考文件，不要一次性加载所有内容。
• 当主要问题是某项内容应作为事件、命令还是同步调用时，加载 references/event-vs-command.md。
• 当任务涉及重试、重放、顺序、毒消息或死信处理时，加载 references/failure-modes.md。
• 在选择编舞式协调、编排或补偿工作流时，加载 references/saga-comparison.md。
• 在整理架构、契约、可靠性或迁移输出的格式时，加载 references/output-templates.md。

说明

模式：设计

1. 找出应转化为事件的业务事实，并用过去时为它们命名。
2. 区分事实、命令和查询。
3. 如果事实与命令的边界不明确，请阅读 references/event-vs-command.md。
4. 为每个事件定义生产者、主题、分区键、消费者和契约。
5. 指明排序要求，以及哪些场景无需考虑顺序。
6. 如果工作流跨越多个服务或涉及补偿操作，请阅读 references/saga-comparison.md。
7. 根据需要使用 references/output-templates.md，设计包含故障处理、重放和可观测性的架构。

模式：审查

1. 阅读事件目录、代码路径或架构图。
2. 检查是否存在隐藏的同步耦合、缺失的幂等性、薄弱的契约所有权，或未定义的重放行为。
3. 标出将事件流误用于请求-响应语义的地方。
4. 如果审查涉及排序、重放、重试或消费者安全，请阅读 references/failure-modes.md。
5. 按严重程度列出发现的问题。

模式：契约

1. 定义必需字段、生产者、所有权、排序预期和版本控制策略。
2. 说明哪些字段是标识符、业务事实和元数据。
3. 优先采用增量演进；为消费者记录弃用期限。
4. 如果拟定的契约仍像命令或查询，请阅读 references/event-vs-command.md。

模式：可靠性

1. 阅读 references/failure-modes.md。
2. 设计重试策略、退避策略、毒消息处理和死信路由。
3. 指定消费者和处理程序的幂等性策略。
4. 定义安全重放机制和运维人员控制措施。

模式：迁移

1. 梳理当前的同步副作用或旧版事件流。
2. 通过明确的检查点引入新的事件路径。
3. 阅读 references/output-templates.md，了解迁移检查点和切换方案的结构。
4. 在新路径证明稳定之前，保留旧路径，以便轻松回滚。

输出要求

• 每项设计都必须明确生产者、主题、分区键、消费者和故障策略。
• 每份契约都必须说明所有权和版本控制规则。
• 每项可靠性方案都必须包含幂等性和死信处理。

参考文件索引

文件	阅读时机
references/event-vs-command.md	主要设计问题是应发布事件、发出命令，还是保留同步调用
references/failure-modes.md	任务涉及重试、排序、重放、毒消息、死信队列或消费者恢复
references/saga-comparison.md	在多个服务之间选择编排、协调或补偿式 Saga 结构
references/output-templates.md	编排架构、契约、可靠性、审查或迁移输出的格式

关键规则

1. 将业务事件建模为过去时的事实，而不是命令。
2. 只要可能发生重试或重放，消费者就必须具备幂等性。
3. 从事务性数据库更改中发布事件时，使用 Outbox 模式。
4. 对要求即时一致性的低延迟请求-响应需求，不要使用事件总线。
5. 事件契约应尽可能采用增量方式演进。

扩展策略

• 小型：保持设计范围精简。扩展之前，先定义最少的事件集合、一个所有权边界和一种可靠性策略。
• 中型：增加明确的契约所有权、分区策略、重放规则，并为跨服务或批处理与事件混合工作流明确选择 Saga 模式。避免用事件术语掩盖同步依赖。
• 大型：按限界上下文安排跨域项目和迁移的顺序。先从一条经过验证的事件路径开始，只有在重放、死信处理和可观测性对运维人员足够安全之后，再扩展消费者批次和下游自动化。

范围界定

适用于： 事件契约、主题、Saga、重试、重放、发件箱、消费者设计。

不适用于： 同步 REST 或 GraphQL API 设计、批量分析管道或消息代理安装细节。