从旧版本升级#

17.0.1 是第一个采用 Java 基线版本号（<Java 大版本>.<特性>.<补丁>）的发布。当前版本同时支持 Spring Boot 3.2.x ~ 4.1.x，一个 jar 通吃。

从 2.1.0-boot32 或 4.0.0 升上来，大部分代码不用改。这一页列出所有会咬人的地方。

先看版本对应#

第一步：改坐标#

Maven：

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

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

Gradle：

implementation 'com.hibuka.soda:soda-core-base:17.0.1'
implementation 'com.hibuka.soda:soda-event-redis:17.0.1'   // 可选

groupId / artifactId 跟老版本一致，只改版本号。但 2.1.0-boot32 用的是 2.x 的坐标体系，如果你的工程里引了父 POM，父 POM 的 spring-boot.version 也要跟着对齐。

第二步：确认 Java 基线#

Java 8 的工程（老的 2.1.0-boot32 用户）必须先升 JDK，没有兼容路径。

第三步：检查四处会编译不过的改动#

1. PageResult.success() 参数顺序变了#

这是唯一一处会静默产生错误结果的 API 变更 —— 参数类型不同，编译器拦不住。

// 旧： (data, pageNo, pageSize, total)
PageResult.success(list, pageNo, pageSize, total);

// 新： (data, total, pageNo, pageSize)
PageResult.success(list, total, pageNo, pageSize);

total 是 Long，pageNo / pageSize 是 Integer。改成新顺序后，如果原来的 total 传的是 Integer，编译能过但分页数据全错。

搜一遍工程里所有 PageResult.success( 的调用点。

2. bus-type: spring 不再是合法值#

soda-event-spring 模块已删除。配成 spring 的后果是一个 EventBus Bean 都不创建，领域事件静默失效。

soda:
  event:
    bus-type: simple     # 或 redis

详见 配置项。

3. 循环引用修饰器被移除#

17.0.1 删掉了这个类，循环引用的处理交给 EventSerializer 实现自己负责。

如果你的代码里直接引用了它（少见，一般是复制了框架的序列化配置），删掉相关配置即可。保留的 soda.event.serialization.circular-reference-handler 键位还在，但已经没有任何代码读取它。

4. Spring Boot 4 用户：Redis 序列化器换类#

这是 Spring Data Redis 在 SB4 里的变更，跟 soda 无关，但升级时一定会撞上：

// SB3
new GenericJackson2JsonRedisSerializer()

// SB4
new GenericJacksonJsonRedisSerializer(objectMapper)

同时 jackson-datatype-jsr310 不再需要单独引入 —— Jackson 3 内置了 JavaTime 支持。

第四步：依赖层面的变化#

EventSerializer 是 17.0.1 最主要的技术变化。原理见 扩展点。

升级检查清单#

• [ ] JDK ≥ 17
• [ ] groupId:artifactId 不变，版本改 17.0.1
• [ ] 父 POM 的 spring-boot.version 对齐（3.2.x ~ 4.1.x）
• [ ] 搜 PageResult.success(，确认参数顺序是 (data, total, pageNo, pageSize)
• [ ] soda.event.bus-type 是 simple 或 redis，不是 spring
• [ ] 删掉对 SmartCircularReferenceSerializerModifier 的引用
• [ ] SB4 工程：GenericJackson2JsonRedisSerializer → GenericJacksonJsonRedisSerializer
• [ ] Redis 多实例部署：consumer-name 每个实例唯一
• [ ] 启动后看日志，确认 EventBus 的实现类符合预期

验证升级成功#

启动后确认三件事：

// 1. 总线实现类对了吗
@Autowired
private EventBus eventBus;   // simple → SimpleEventBus；redis → RedisStreamEventBus

// 2. 自动装配注册了吗
// 日志里应有 SpringBusAutoConfiguration / RepositoryEventAutoConfiguration

// 3. 分页数据对吗（最容易错的一项）
// 调一个分页接口，核对 total / pageNo / pageSize 三个值

兼容性风险#

下一步#

• 版本线的完整说明：版本与兼容
• 每个配置键的含义：配置参考
• 从零接入：安装