五分钟跑通#

不手写代码。 先去生成器生成一个能直接跑的工程 —— H2 内存库、建表脚本、完整的 DDD 示例代码全都带好。你只负责 mvn spring-boot:run，然后在浏览器里看到它工作。

跑通之后再回头看 核心概念 和 写一个命令，会快得多。

第一步：生成工程#

打开 https://start.soda.hibuka.com，选模板，填三项，下载 zip。

模板选 SODA Simple（单体架构）。需要多模块拆分的选 scoda-cloud。

生成的工程里已经包含：

• 一套完整的 DDD 分层目录（adapter / application / domain / infrastructure）
• 一个「厂商（Producer）」聚合根的完整 CRUD：命令、查询、事件、仓储
• H2 内存库配置 + 建表脚本 schema-h2.sql
• MyBatis-Plus、Knife4j（Swagger）、统一异常处理

第二步：直接跑#

unzip my-soda-project.zip
cd my-soda-project
mvn spring-boot:run

不需要装 MySQL，不需要装 Redis。 启动完成看这行：

Tomcat started on port 8080

生成的工程默认就是「开箱能跑」的姿态：

第三步：调四个接口#

示例给了一组能覆盖四条链路的接口，全部是 POST：

创建一条：

curl -X POST http://localhost:8080/api/creatProducer \
  -H 'Content-Type: application/json' \
  -d '{"name": "华东电子"}'

返回：

{
  "code": 200,
  "message": "",
  "data": {
    "uid": "a1b2c3d4-...",
    "name": "华东电子"
  },
  "success": true
}

再查一次，确认真的存进去了：

curl -X POST http://localhost:8080/api/listProducers \
  -H 'Content-Type: application/json' \
  -d '{"pageNumber": 1, "pageSize": 10}'

data 里应该能看到刚才那条记录。这一步是关键：命令走通了、写进了库、查询读出来了 —— 一条完整的 CQRS 闭环。

第四步：看数据库里到底有什么#

H2 自带 Web 控制台，打开 http://localhost:8080/h2-console：

点 Connect，左侧就能看到 scoda_producer 和 scoda_consumer 两张表。执行：

SELECT uid, name, gmt_create FROM scoda_producer;

第五步：把代码读一遍 —— 一条命令怎么走完全程#

这是这一页真正的重点。工程里的示例代码不是摆设，它把 soda 的每条链路都演了一遍。按下面这张表从上往下读，就能看懂一条命令的完整生命周期。

三个值得停下来看的地方#

1. 事件是聚合根挂的，不是 Service 发的

Producer.create() 里这一行：

addPendingEvent(new ProducerEvent(ProducerEventTypeEnum.CREATE_PRODUCER.getDesc(), this));

addPendingEvent 是 protected 的 —— 只有聚合根自己能调。Service 层想绕过聚合根直接发个事件，编译都过不了。这是「事件必须源于领域状态变化」的强制保证。

事件此时只是挂起，还没发布。什么时候发？仓储 save() 之后。切面 RepositoryEventAspect 会在保存成功（有事务则在提交后）把挂起的事件取出来派发。

2. 领域层不知道 MyBatis-Plus 存在

domain/producer/repository/ProducerWriteRepository.java 是个纯接口，继承 WriteRepository<Producer>：

public interface ProducerWriteRepository extends WriteRepository<Producer> {
}

WriteRepository 固定四个方法：save / update / delete / operate。CommandHandler 注入的是这个接口，不是 ProducerWriteRepositoryImpl。

实现类在 infrastructure 层，用 MyBatis-Plus 落库。换成 JPA、换成 Redis、换成内存 Map，领域层都不用改。

3. Handler 不需要注册

ProducerEventHandler 上有 @Component，然后就没了 —— 没有 subscribe，没有注册表，没有 XML。框架启动时扫描所有 EventHandler，按泛型解析出它处理的事件类型并建索引。ProducerEvent 一发布，它自动被调用。

分层目录长什么样#

src/main/java/com/example/soda/
├── adapter/inbound/web/         # 入口：Controller、DTO、组装器、异常处理
├── application/                 # 应用层：Command / Query / Handler / 应用服务
│   ├── cqrs/command/
│   ├── cqrs/query/
│   ├── cqrs/handler/command/
│   ├── cqrs/handler/query/
│   └── cqrs/handler/evnet/      # 事件消费者（模板里就是这个拼写）
├── domain/                      # 领域层：聚合根、事件、仓储接口
│   ├── producer/
│   ├── consumer/
│   └── enums/
└── infrastructure/              # 基础设施：DO、Mapper、仓储实现、外部客户端
    ├── acl/mysql/
    ├── acl/redis/
    ├── repositoryImpl/
    └── assembler/

依赖方向只有一个：adapter → application → domain，infrastructure 反过来实现 domain 的接口。domain 包里不出现任何 Spring / MyBatis / Redis 的 import。

第六步：改一行，看它动#

在 ProducerEventHandler.handle() 里加一行日志：

@Override
public void handle(ProducerEvent event) throws BaseException {
    log.info("收到厂商事件：{}，厂商：{}", event.getEventType(), event.getProducer().getName());
    eventValidate(event);
}

重启，再调一次 /api/creatProducer。控制台会打印这条 —— 说明事件从聚合根出发，穿过仓储，穿过总线，到了消费者手里。

第七步：换成生产形态#

示例跑在 H2 + 进程内总线上。上生产要换两件事：

soda:
  event:
    bus-type: redis
    redis:
      host: ${SODA_REDIS_HOST}
      password: ${SODA_REDIS_PASSWORD}
      stream:
        idempotency:
          enabled: true

你已经跑通了什么#

到这为止，一个完整的 soda 应用已经有了：

• 聚合根保护状态变更，事件由它产生
• 命令走写链路（同步 + 异步），查询走读链路（单体 + 分页）
• 保存时事件自动发布，消费者自动收到
• 统一返回结构 Result / PageResult
• 领域层对基础设施零依赖

下一步：

• 想理解每个环节为什么这么设计 → 请求是怎么跑完的
• 想自己从零写一个聚合根 → 写一个命令
• 想接入登录用户、租户、requestId → 接入 Web 层
• 想让事件跨服务投递 → 事件总线与切面