soda docs v17.0.1
/

Upgrade Guide

17.0.1 is the first release to use Java-baseline version numbers (<Java major>.<feature>.<patch>). The current version supports Spring Boot 3.2.x ~ 4.1.x alike — one jar covers both.

Upgrading from 2.1.0-boot32 or 4.0.0, most of your code needs no changes. This page lists every spot that can bite you.

First, the version mapping

You are onUpgrade toNotes
2.1.0-boot32{VERSION}Spring Boot 3.2.x line; your code barely changes
4.0.0{VERSION}Spring Boot 4.x line; the proper release after the coordinate rename
17.0.0{VERSION}Must upgrade, see below
2.1.1-boot32{VERSION}Only the POM is in Central; don't use it
Caution

Do not use 17.0.0. It is an internal build uploaded by mistake during the version-number migration, and it lacks the EventSerializer decoupling. It can be pulled from the Aliyun repository but not from Maven Central. If you are already on it, switch straight to 17.0.1.

Step 1: update the coordinates

Maven:

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

Gradle:

groovy
implementation 'com.hibuka.soda:soda-core-base:17.0.1'
implementation 'com.hibuka.soda:soda-event-redis:17.0.1'   // optional

groupId / artifactId are the same as in older versions — only the version number changes. But 2.1.0-boot32 used the 2.x coordinate system; if your project imports a parent POM, the parent's spring-boot.version must be aligned too.

Step 2: confirm the Java baseline

ItemRequirement
Minimum Java17
Recommended21
Spring Boot3.2.x ~ 4.1.x

Java 8 projects (old 2.1.0-boot32 users) must upgrade the JDK first — there is no compatibility path.

Step 3: check the four breaking changes

1. PageResult.success() parameter order changed

This is the one API change that silently produces wrong results — the parameter types differ, so the compiler can't catch it.

java
// Old: (data, pageNo, pageSize, total)
PageResult.success(list, pageNo, pageSize, total);

// New: (data, total, pageNo, pageSize)
PageResult.success(list, total, pageNo, pageSize);

total is Long, pageNo / pageSize are Integer. After switching to the new order, if the old total was passed as an Integer, it still compiles but every paged result is wrong.

Search your project for every PageResult.success( call site.

The soda-event-spring module has been removed. Configuring spring means not a single EventBus bean gets created, and domain events silently stop working.

yaml
soda:
  event:
    bus-type: simple     # or redis

Details: Configuration.

3. The circular-reference modifier was removed

17.0.1 deleted this class; handling circular references is now the responsibility of each EventSerializer implementation.

If your code references it directly (rare — usually from copying the framework's serialization config), just delete the related configuration. The soda.event.serialization.circular-reference-handler key is still tolerated, but no code reads it anymore.

4. Spring Boot 4 users: swap the Redis serializer class

This is a Spring Data Redis change in SB4, unrelated to soda, but you will definitely hit it during the upgrade:

java
// SB3
new GenericJackson2JsonRedisSerializer()

// SB4
new GenericJacksonJsonRedisSerializer(objectMapper)

Also, jackson-datatype-jsr310 no longer needs a separate dependency — Jackson 3 has JavaTime support built in.

Step 4: dependency-level changes

ChangeNotes
spring-boot-starter-aop → spring-boot-starter-aspectjSwapped inside the framework; your business code doesn't change. But if you explicitly depend on the aop starter and rely on the aspect capabilities it transitively brings, double-check
soda-event-redis no longer depends on Jackson directlySerialization goes through the EventSerializer abstraction. A project using only the in-process bus starts fine without Jackson on the classpath
New EventSerializer abstractioncom.hibuka.soda.event.EventSerializer, with default implementation JacksonEventSerializer calling ObjectMapper through reflection, so one jar runs on both Jackson 2 / 3

EventSerializer is the biggest technical change in 17.0.1. How it works: Extension Points.

Upgrade checklist

  • [ ] JDK ≥ 17
  • [ ] groupId:artifactId unchanged, version set to 17.0.1
  • [ ] Parent POM's spring-boot.version aligned (3.2.x ~ 4.1.x)
  • [ ] Search PageResult.success(, confirm the parameter order is (data, total, pageNo, pageSize)
  • [ ] soda.event.bus-type is simple or redis, not spring
  • [ ] Remove references to SmartCircularReferenceSerializerModifier
  • [ ] SB4 projects: GenericJackson2JsonRedisSerializer → GenericJacksonJsonRedisSerializer
  • [ ] Redis multi-instance deployments: consumer-name unique per instance
  • [ ] After startup, check the logs and confirm the EventBus implementation class is the one you expect

Verify the upgrade

Confirm three things after startup:

java
// 1. Is the bus implementation class right?
@Autowired
private EventBus eventBus;   // simple → SimpleEventBus; redis → RedisStreamEventBus

// 2. Did auto-configuration register?
// The log should show SpringBusAutoConfiguration / RepositoryEventAutoConfiguration

// 3. Is the paging data right? (the easiest one to get wrong)
// Call a paged endpoint and check all three: total / pageNo / pageSize
Tip

After upgrading, run one existing event chain: send a command → check that the events hung on the aggregate root were really published → check that the consumer received them. A wrong bus-type and the wrong PageResult parameter order are the two most common failures in this upgrade.

Compatibility risks

ComponentStatus
Knife4j 4.3.0Untested under SB4. Works fine under SB3
Spring Cloud / NacosUnder SB4 needs the matching Spring Cloud Alibaba version
MyBatis-PlusSB4 needs the boot4-starter version line

Next steps