cqrs-patterns

用途

CQRS（Command Query Responsibility Segregation，命令查询职责分离）模式用于将读与写关注点分离，从而优化数据访问。该技能适合以下场景：读多写少且查询复杂的工作负载；读与写的扩展需求不同；事件溯源实现；同一数据需要多种读模型表示；领域模型复杂但读取需求简单。

不适合的场景：简单 CRUD 应用；处处要求强一致性；数据集小且查询简单。

架构概览

架构分为写侧与读侧。写侧包含命令（Commands）、聚合（Aggregate）与事件（Events）；读侧包含查询（Queries）与读模型（Read Model）。写侧发布事件，读侧通过投影（Project）消费事件更新读模型。

主要能力

命令侧（写模型）

提供命令与处理器的基础结构：Command 基类携带 command_id、timestamp、user_id 等元数据；CreateOrder 等具体命令；CommandHandler 抽象基类；CreateOrderHandler 实现库存校验、创建订单、保存并返回待发布事件；CommandBus 负责注册处理器并分发命令，分发后发布事件。

写模型（聚合）以 Order 为例，包含 id、customer_id、items、status 等字段，提供 create 工厂方法、cancel 方法，并通过 _raise_event 收集待发布事件，pending_events 属性返回并清空事件列表。

查询侧（读模型）

提供 Query 基类、GetOrderById、GetOrdersByCustomer 等查询；GetOrderByIdHandler 从读库查询 order_summary 表并返回 OrderView；OrderView 是反规范化的读模型，包含 customer_name、total_amount、item_count 等字段。

投影

OrderProjection 将事件投影到读模型，处理 OrderCreated、OrderItemAdded、OrderCancelled 等事件，分别执行插入、更新金额与数量、更新状态等操作，并使用 UPSERT 保证幂等。

FastAPI 集成

提供 POST /api/v1/orders 创建订单与 GET /api/v1/orders/{order_id} 查询订单的示例，展示命令总线与查询总线的依赖注入及异常处理。

关键决策

一致性：写模型与读模型之间采用最终一致性。事件存储：写侧使用事件存储，读侧使用反规范化表。投影延迟：监控并对投影延迟告警。读模型数量：从单个开始，按特定查询需求增加。重建策略：具备从事件重建投影的能力。

反模式（禁止）

禁止用写模型做读取查询，应使用读模型；禁止直接修改读模型，应分发命令由投影更新；禁止跳过投影幂等性，应使用 UPSERT。

技能介绍

用途