soda docs v17.0.1
/

环境要求

项要求
JDK17 或更高
Spring Boot3.2.x ~ 4.1.x（同一个 jar 通吃）
构建工具Maven / Gradle 均可
数据库框架不绑定，仓储层自己实现
技巧

不想手动搭工程？ 去 https://start.soda.hibuka.com 生成一个 —— 内置 H2 内存库，解压就能 mvn spring-boot:run，不用装 MySQL 和 Redis。见 五分钟跑通，那一页会带你把示例代码读一遍。

技巧

soda 用 spring-boot-dependencies 做 BOM 管理版本，你自己的工程只要也引了 Spring Boot 的依赖管理，版本就自动对齐 —— soda 不需要单独指定 Spring Boot 版本。

引入核心依赖

soda-core-base 是核心包，包含命令总线、查询总线、事件总线、CQRS 切面、领域事件与上下文传递。

xml
<dependency>
  <groupId>com.hibuka.soda</groupId>
  <artifactId>soda-core-base</artifactId>
  <version>17.0.1</version>
</dependency>

Gradle：

groovy
implementation 'com.hibuka.soda:soda-core-base:17.0.1'
重要

上面坐标里的版本号是文档构建时自动填入的。最新版本以 Maven 仓库为准 —— 查 com.hibuka.soda:soda-core-base 的仓库页，或看 版本与兼容。

可选：Redis 事件总线

默认用的是进程内事件总线 —— 事件只在同一个 JVM 里投递。要让事件跨服务投递（服务 A 写库，触发服务 B 的逻辑），加上 soda-event-redis：

xml
<dependency>
  <groupId>com.hibuka.soda</groupId>
  <artifactId>soda-event-redis</artifactId>
  <version>17.0.1</version>
</dependency>

它基于 Redis Streams，带消费组、幂等键和死信流。

提示

soda-event-redis 是可选依赖。不想跨服务投递就别加，包体小很多，也没有 Redis 依赖。

自动装配做了什么

加上依赖之后不需要写任何 @Configuration，Spring Boot 的自动装配会注册这些 Bean：

自动配置类作用
SpringBusAutoConfiguration始终生效：注册 CommandBus、QueryBus、cqrsAsyncExecutor、BusFacade。名字有误导性 —— 它跟 Spring 事件无关，是所有模式下的 CQRS 骨架
SimpleEventBusAutoConfigurationbus-type=simple 或没配时生效：注册 SimpleEventBus（matchIfMissing = true）
RepositoryEventAutoConfiguration容器里有 EventBus 时生效：注册 RepositoryEventAspect —— 保存聚合根时自动发布挂起的领域事件
RedisEventBusAutoConfigurationbus-type=redis 时生效（需要 soda-event-redis）：注册 Redis Streams 事件总线

BusFacade 始终可用，它是你在业务代码里发命令、发查询的入口。

切换事件总线类型

在 application.yaml 里：

yaml
soda:
  event:
    bus-type: simple      # simple | redis
值效果
不配置SimpleEventBus —— 进程内，无外部依赖
simple同上，显式写出来意图更清楚。推荐
redisRedis Streams，需要 soda-event-redis 依赖 + Redis 配置，可跨服务投递
spring⚠️ 当前版本没有这个实现。会一个 EventBus 都不创建，领域事件静默失效
注意

EventProperties 的字段默认值还是 "spring"，但 soda-event-spring 模块在 17.0.1 已经删除。别写 spring —— 不报错，但事件永远发不出去。不配置反而安全（回落到 Simple）。

完整配置项见 配置参考，实用配置姿势见 配置项。

验证装好了

新建一个空工程，启动 Spring Boot，能看到 soda 的自动装配日志就说明依赖没问题：

java
@SpringBootApplication
public class SodaApplication {
    public static void main(String[] args) {
        SpringApplication.run(SodaApplication.class, args);
    }
}

下一步：五分钟跑通。