AI 指南（可复制）#

你在为一个使用 soda-core（com.hibuka.soda:soda-core-base）的 Spring Boot 工程写代码。这是一个 DDD + CQRS 框架。按下面的约定写，不要自己发明写法。

架构#

请求 → Controller(适配器) → AppService(应用) → BusFacade(CQRS总线)
                                                    ↓
                                        QueryHandler / CommandHandler
                                                    ↓
                                        Repository(仓储) → DB / SLS

核心类#

文件命名#

两个硬约束#

1. 泛型三处必须一致

ListXxxQuery extends BasePageQuery<PageVO<XxxVO>>
  ⇒ QueryHandler<ListXxxQuery, PageVO<XxxVO>>
  ⇒ XxxAppService.listXxx(...) 返回 PageVO<XxxVO>

三处的 R 必须是同一个类型。差一个泛型参数、把 XxxVO 写成 XxxData，都会出问题。

2. CommandHandler 必须返回聚合根

CommandHandler.handle(C) 的返回值是领域事件的载体。返回 void 或返回 VO，CqrsAroundHandler 就没东西可发，领域事件静默不发。

// ✅ 对
public class CreatXxxCommandHandler implements CommandHandler<CreatXxxCommand, Xxx> {
    public Xxx handle(CreatXxxCommand cmd) {
        Xxx agg = Xxx.create(cmd);          // 内部 addPendingEvent(...)
        writeRepository.save(agg);           // RepositoryEventAspect 发事件
        return agg;                          // ← 必须返回
    }
}

// ❌ 错：事件永远发不出去
public Void handle(CreatXxxCommand cmd) { writeRepository.save(...); return null; }

领域事件什么时候发#

只有两条路径，缺一条就不发：

1. CommandHandler 返回聚合根 / DomainEvents / DomainEvent —— CqrsAroundHandler 发。
2. Repository 的 save / update / delete / operate 作用在 AbstractAggregateRoot 上 —— RepositoryEventAspect 在事务提交后发。

只改聚合根、返回 void、又不走 *Repository 持久化 → 事件不发。聚合根必须通过 *Repository 的方法落库。

配置项#

soda:
  event:
    bus-type: simple          # simple | redis，默认 simple
    redis:                    # bus-type=redis 时才生效
      stream:
        group-name: my-group
        consumer-name: my-consumer
        idempotency:
          enabled: true

# 注意前缀是 scoda. 不是 soda.
scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 8
        max-pool-size: 16

构建与测试#

mvn clean verify          # 构建 + 测试（发版走这个）
mvn test                  # 只跑测试
mvn clean install         # 本地装库

Java 17 起，推荐 21。不要用 cp pom-3.2.xml pom.xml 那套多 POM 工作流 —— 已废弃，根目录的 pom-2.3.xml / pom-2.7.xml / pom-3.2.xml 是历史残留。

常见陷阱#

• Handler 按精确类匹配。SimpleCommandBus / SimpleQueryBus 用 handlers.get(command.getClass()) 查表，不走继承。给父类写的 Handler 不会接住子类命令。同一个命令类型只能有一个 CommandHandler，后注册的会覆盖前面的。
• EventHandler 反而走继承。SimpleEventBus.publish 会沿父类和接口找，所以 EventHandler<DomainEvent> 能接住所有事件。
• sendMqCommand 是桩，永远抛 UnsupportedOperationException。别调。
• AbstractAggregateRoot extends AbstractDomainEvent —— 聚合根本身是个事件，身上有 eventId / requestId 这些字段。这是历史设计，业务上用不到，别去赋值。
• @AutoConfigureAfter 用的是字符串类名，不是 Class 引用（为了兼容 Spring Boot 3 和 4）。加自动配置照这个写法。
• PreChecker 已废弃，用 ParamChecker。
• EventSerializer 是 Jackson 2/3 兼容的关键。要加 Jackson 相关注解，用 Jackson 2 的坐标 com.fasterxml.jackson.annotation.*，不要引 Jackson 3 的（Spring Boot 4 上会失效）。
• knife4j-openapi3-spring-boot-starter 是 optional。子类化 BaseCommand / BaseQuery / AbstractDomainEvent 时，工程自己要带 io.swagger.core.v3:swagger-annotations，否则编译不过。

你不要做的事#

• 不要发明 @Command / @Query / @Handler 注解 —— soda 里没有任何自定义注解，全靠实现 CommandHandler / QueryHandler / EventHandler 接口 + @Component。
• 不要在应用层直接注入 Repository 的实现类，只注入接口（否则应用层依赖了基础设施层）。
• 不要绕过 BusFacade 直接调 Handler。
• 不要在 Command 里写业务规则 —— 那是聚合根的职责。Command 只放业务参数，上下文字段由框架填充。