Versions & Compatibility
Current version: 17.0.1.
The latest version is whatever the Maven repository shows. The version numbers on this page are filled in at build time and may lag the repository slightly. Check the repository page for com.hibuka.soda:soda-core-base, or the release notes.
Dependency coordinates
soda has two modules:
| Module | groupId | artifactId | Purpose |
|---|---|---|---|
| Core | com.hibuka.soda | soda-core-base | Command bus, query bus, event bus, CQRS aspects, domain events, context propagation |
| Redis extension | com.hibuka.soda | soda-event-redis | Redis Streams event bus, consumer groups, idempotency, dead-letter stream |
Core dependency
<dependency>
<groupId>com.hibuka.soda</groupId>
<artifactId>soda-core-base</artifactId>
<version>17.0.1</version>
</dependency>Gradle:
implementation 'com.hibuka.soda:soda-core-base:17.0.1'Redis extension (optional)
<dependency>
<groupId>com.hibuka.soda</groupId>
<artifactId>soda-event-redis</artifactId>
<version>17.0.1</version>
</dependency>soda-event-redis is optional. A project using only the in-process event bus doesn't need this dependency — the artifact is much smaller and pulls in no Redis dependency.
Managing the version through a Maven property is more convenient:
<properties>
<soda.version>17.0.1</soda.version>
</properties>
<dependencies>
<dependency>
<groupId>com.hibuka.soda</groupId>
<artifactId>soda-core-base</artifactId>
<version>${soda.version}</version>
</dependency>
</dependencies>Environment requirements
| Item | Requirement |
|---|---|
| JDK | 17 or newer (21 recommended) |
| Spring Boot | 3.2.x ~ 4.1.x — one jar covers both |
| Build tool | Maven or Gradle |
| Database | Not bound by the framework — implement the repository layer yourself |
| Redis | Only needed with soda-event-redis |
soda-core is developed and tested internally on Spring Boot 4.1.0, but its compile target is Java 17 (maven.compiler.release=17), and it achieves Jackson 2 / Jackson 3 dual compatibility through the EventSerializer abstraction. So a Spring Boot 3.2.x project can use the very same coordinates — no jar swap needed.
Spring Boot version mapping
| Spring Boot | Jackson | Jackson packages | soda's starter |
|---|---|---|---|
| 3.2.x | Jackson 2 | com.fasterxml.jackson.* | spring-boot-starter-web / spring-boot-starter-aop |
| 4.x | Jackson 3 | tools.jackson.* | spring-boot-starter-webmvc / spring-boot-starter-aspectj |
Spring Boot 4 renamed the starters. soda-core depends on spring-boot-starter-aspectj (the aspects need it), so if your project still uses the old spring-boot-starter-aop, make sure aspectjweaver is on the classpath — otherwise the aspects never engage, and the symptom is "events never go out", with no error at all.
soda itself uses spring-boot-dependencies for BOM management:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>As long as your project also imports Spring Boot's dependency management, versions align automatically — soda needs no separate Spring Boot version.
soda's transitive dependencies
soda-core-base depends directly on:
| Dependency | Purpose |
|---|---|
spring-boot-autoconfigure | Annotations and conditions for auto-configuration |
spring-boot-starter-aspectj | @Aspect / @Around support |
spring-boot-starter-validation | jakarta.validation constraint annotations |
fastjson 1.2.83 | Used to serialize logs in CqrsAroundHandler |
lombok 1.18.46 | compile-only |
knife4j-openapi3-spring-boot-starter 4.3.0 | Swagger / OpenAPI annotations |
soda-event-redis depends directly on:
| Dependency | Purpose |
|---|---|
soda-core-base | The core |
spring-boot-starter-data-redis | Redis Stream client |
fastjson 1.2.83 is a compile-time dependency and it transitive into your project. The 1.x line has known historical CVEs. If your security scanning flags it, you can exclude it in your project — soda uses it internally only for log serialization in CqrsAroundHandler, and that web-layer usage could be swapped for Jackson entirely.
<dependency>
<groupId>com.hibuka.soda</groupId>
<artifactId>soda-core-base</artifactId>
<version>17.0.1</version>
<exclusions>
<exclusion>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
</exclusion>
</exclusions>
</dependency>Once fastjson is excluded, CqrsAroundHandler's log serialization breaks (it throws NoClassDefFoundError). If you exclude it, you must also define your own CqrsAroundHandler bean overriding the framework's — and the framework's pointcut expression is hard-coded inside the CqrsAroundHandler class, so overriding it means copying the entire class. The more practical options: swap fastjson for a safe version, or just accept it.
Version numbering scheme
soda uses the Java-baseline versioning scheme:
<Java-major>.<feature>.<patch>| Segment | Meaning | Example (17.0.1) |
|---|---|---|
| First | Minimum Java version | 17 |
| Second | Feature number | 0 |
| Third | Patch number | 1 |
So 17.0.1 reads as "minimum Java = first segment, feature = second, patch = third". Taking 17.0.1 as the example: minimum Java 17, feature 0, patch 1.
The advantage of this scheme: the minimum Java requirement is visible in the version number itself. Old numbers like 2.1.0-boot32 don't follow the rule — they are historical leftovers.
Historical version mapping
| soda-core version | Supported Spring Boot | Java | Status |
|---|---|---|---|
17.x (current) | 3.2.x ~ 4.1.x (one jar) | 17+ (21 recommended) | Active |
17.0.0 | 4.x | 21 | Do not use |
4.0.0 | 4.x | 21 | Ended (historical) |
2.1.1-boot32 | 3.2.x | 8 | Ended (POM-only on Central, no jar; use 2.1.0-boot32) |
2.1.0-boot32 | 3.2.x | 8 | Ended |
2.0.0 / 2.1.0 | 2.x | 8 | Ended |
Do not use 17.0.0. It is a mis-release from the version-scheme migration — the build artifacts are stale, missing the EventSerializer decoupling, and it was never published to Maven Central, only mistakenly pushed to the Aliyun repository. Use 17.0.1 directly.
Upgrade path from older versions
| From | To | Watch out for |
|---|---|---|
4.0.0 | 17.0.1 | Java 17+; Spring Boot 3.2.x now supported too; PageResult.success parameter order is already the new order |
2.x | 17.0.1 | Java 8 → 17; Spring Boot 2.x → 3.2.x+; starter names changed; PageResult.success parameter order changed |
For the full cross-major-version checklist see Upgrade from v16.
A few concrete Spring Boot 3 differences
To support Spring Boot 3 and 4 at once, soda contains a few adaptations. The known differences:
| Item | Spring Boot 3 | Spring Boot 4 |
|---|---|---|
| Web starter | spring-boot-starter-web | spring-boot-starter-webmvc |
| AOP starter | spring-boot-starter-aop | spring-boot-starter-aspectj |
| JSON starter | spring-boot-starter-json | spring-boot-starter-jackson |
| Jackson | 2.x | 3.x (packages renamed) |
| Redis auto-configuration class | org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration | org.springframework.boot.data.redis.autoconfigure.DataRedisAutoConfiguration |
The Redis auto-configuration class name differs between the two versions, so RedisEventBusAutoConfiguration lists both in @AutoConfigureAfter(name = {...}):
@AutoConfigureAfter(name = {
"org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration",
"org.springframework.boot.data.redis.autoconfigure.DataRedisAutoConfiguration"
})RepositoryEventAutoConfiguration also lists two auto-configuration class names:
@AutoConfigureAfter(name = {
"com.hibuka.soda.event.spring.SpringEventBusAutoConfiguration",
"com.hibuka.soda.event.redis.RedisEventBusAutoConfiguration"
})The first name, com.hibuka.soda.event.spring.SpringEventBusAutoConfiguration, points to a class that no longer exists (the soda-event-spring module was removed after 4.0.0). @AutoConfigureAfter(name = ...) does not fail on a missing class name — that one ordering constraint simply has no effect. Since the other name, RedisEventBusAutoConfiguration, is still there, the ordering still works.
Verify the installation
Start Spring Boot; these lines should appear in the log:
[SimpleCommandBus] Constructor called, handlers size: 1
[SimpleCommandBus] Registered handler for command: com.example.demo.CreateProducerCommand
[SimpleEventBus] Constructor called, handlers size: 1
[SimpleEventBus] Registered 1 event handler types
[CqrsAroundHandler] Bean created!If the counts don't match, your Handler components weren't scanned — check @Component and the package paths.
Next steps
- What to change during an upgrade: Upgrade from v16
- The full configuration options: Configuration Reference
- Extension points and compatibility: Extension Points