Design a Jackson 2/3 Compatibility Adapter Layer for Nacos to Support Spring 4.x and AI Ecosystem

[KomachiSion]

Is your feature request related to a problem? Please describe.

jackson发布了3.x版本,且和2.x版本有较大的不兼容问题。

spring 官方在4.x版本中将jackson升级到了3.x版本, 这可能导致spring cloud和spring ai在新版本中默认依赖了jackson3.x版本。

nacos-client在这种情况下,如果仅依赖2.x版本的jackson,能导致和spring-boot4 以及对应新版本的spring cloud和spring ai存在不兼容的问题。但Nacos有不能直接升级成3.x版本的jackson,因为还有用户留存在2.x版本的jackson以及spring-boot3及更老的版本中。

Describe the solution you'd like

因此这里需要抽象一个Jackson或者Json的适配层,自动识别当前的jackson版本,然后使用对应版本的api进行操作。

目前Nacos的Json序列化和反序列化操作基本都收敛在JsonUtil中,相对来说改造成本比较低。欢迎社区同学提供方案和PR。

设计方案和PR时,请注意以下几点要点:

1. 建议抽象出一个适配层API,供JsonUtil使用。
2. 可以通过判断特征类是否存在的方式,判断应该用Jackson3还是2。
3. 考虑到用户可能不是使用的spring框架,默认还是需要依赖jackson2作为默认选项。
4. 尽量降低对用户的升级的影响。

Describe alternatives you've considered

• 直接升级jackson到3.x,但对存量用户兼容性风险高,不建议。
• 维持当前实现,但不支持spring-boot4/AI生态新版本,也不利于后续演进。

Additional context

社区同学可在此issue发布设计方案或直接提交PR,欢迎补充、讨论。

---

jackson 3.x is released and has major incompatibilities with version 2.x.
Spring 4.x has upgraded to jackson 3.x, which may lead to new versions of spring cloud/ai defaulting to jackson 3.x.
Currently, nacos-client only depending on jackson 2.x would cause incompatibility with spring-boot 4.x and new versions of spring cloud/ai, but Nacos cannot simply upgrade to jackson 3.x because some users are still using jackson 2.x or spring-boot 3.x/older.

A json-adapter layer is suggested to detect the present jackson version dynamically and delegate to the appropriate api, with main serialization logic already converged in JsonUtil (making the refactor cost manageable).

When designing or submitting a PR, please consider:

1. Abstracting an adapter API for JsonUtil.
2. Identifying jackson version via feature class detection.
3. Defaulting to jackson2 for non-spring users as the safer option.
4. Minimizing user upgrade impact as much as possible.

Related design suggestions and PRs are welcome under this issue.

[cxhello]

Design Proposal: Jackson 2/3 Compatibility Adapter Layer

Current Status

I investigated the Jackson usage across the codebase:

• JSON operations are well-centralized in JacksonUtils (15 public APIs, single ObjectMapper), only 2 places create ObjectMapper directly.
• 250+ files import Jackson, but api module (Java 8 target) has 29 files and client has only 3 files with direct Jackson imports.
• 8 files use @JsonTypeInfo / @JsonSubTypes — this is the hardest part, since Jackson 3 changes the annotation package from com.fasterxml.jackson to tools.jackson.

Proposed Approach

1. Adapter Interface + Factory (in common module)

• Abstract a NacosJsonAdapter interface covering serialization, deserialization, JsonNode operations, and subtype registration.
• NacosJsonAdapterFactory detects Jackson version via Class.forName("tools.jackson.databind.ObjectMapper"), defaults to Jackson 2 if not found.
• JacksonUtils keeps its public API unchanged, internally delegates to the adapter — all existing callers require zero changes.

2. Jackson 3 as Separate Optional Module

• Jackson2Adapter lives in common module with compile-time Jackson 2 dependency (default).
• Jackson3Adapter lives in a new optional module (nacos-jackson3-adapter), compiled against Jackson 3, loaded via reflection at runtime.
• This avoids ClassNotFoundException in Jackson 2 environments.

3. Annotation Migration via MixIn

For @JsonTypeInfo / @JsonSubTypes / @JsonProperty in api module:

• Remove Jackson annotations from model classes (Selector, AbstractHealthChecker, MCP registry models, etc.).
• Register equivalent MixIn classes in each adapter during initialization.
• This decouples the api module from any specific Jackson version, maintaining Java 8 compatibility.

The api/ai/model/mcp/registry/ package has ~15 files using @JsonProperty — these should be migrated to MixIn as well.

4. Dependency Strategy

• Default: Jackson 2 (no user action needed).
• Spring Boot 4 users: Jackson 3 already on classpath → adapter auto-detects and switches.
• Explicit opt-in: add nacos-jackson3-adapter dependency.

Implementation Phases

Phase	Scope
1	Abstract NacosJsonAdapter + Jackson2Adapter, refactor JacksonUtils internals (zero external impact)
2	Migrate @JsonTypeInfo annotations to MixIn in api module (8 files)
3	Create nacos-jackson3-adapter module
4	Handle remaining direct ObjectMapper usages (ConfigExtInfoUtil, etc.)
5	Integration testing with both Jackson 2 and 3

Key Considerations

• api / client modules must stay Java 8 compatible; Jackson 3 requires Java 17+, hence the separate module.
• Adapter interface uses java.lang.reflect.Type instead of Jackson's TypeReference to avoid leaking version-specific types.
• Only 8 files need MixIn migration for polymorphic annotations, scope is manageable.

Feedback and alternative ideas are welcome!

[herodotus-ecosystem]

个人的观点：Jackson2 和 Jackson 3 的兼容处理并不容易，核心问题主要有：

1. 包路径的变更：Jackson3 除了的 annotation 模块的包路径没有变化外，其它的代码包路径由 com.fasterxml.jackson 变为 tools.jackson。（这一点还可以考虑兼容）
2. ObjectMapper 创建以及 Exception 的变化：Jackson3 推荐使用 JsonMapper 来创建 ObjectMapper ；所有异常统一变更为 JacksonException。（这一点还可以考虑兼容）
3. JDK 版本：Jackson3 默认使用 JDK 17 编译。这种兼容适配的考虑就非常多，还和用户当前所使用 JDK 以及 Spring Boot 版本有关。
   如果用户还在用 JDK 8 和 Spring Boot 2，那么编译就是个问题。单纯编译可能还好说，JDK 8 到 17 中间还有个鸿沟就是 Java 的模块化
4. 动态判断版本问题：因为 Spring Boot 4 中默认是使用 Jackson3，但是为了支持一部分用户，依赖里面还包含有 Jackson2 的依赖。这样不管使用 SPI 还是类似 Spring Boot @ConditionalOnClass 的方式，不太好明确区分当前用户用的什么版本 Jackson。

我个人使用的很多涉及 Jackson 第三方，例如 jsonschema-generator 、json-schema-validator 、swagger 等等，原本也都尝试考虑兼容，最后采用的都是升级大版本号。

很理解 Nacos 不能盲目升级的问题。个人的小建议是：目前看影响较大的点，应该出在 Nacos Client 。那么对 Nacos Client 做单独处理，单独复制出一个模块叫 client-jackson3 或者 client-jdk17 之类模块，适配 Jackson3。然后控制好编译的 JDK 版本即可。

这样的好处是：

1. 变更简单快速，复制出一个模块修改一下 Jackson3 的包路径、ObjectMapper 创建方式和 Exception 即可。
2. 控制好编译JDK 版本（新版本 Nacos已经改成了 JDK 17， Nacos Client 还是用 JDK 8 ，逻辑上已经处理好了不需要再整啥）。

这样的好处就是原来基于 JDK 8 的 Nacos Client，可以继续为还在使用 Jackson2 和 Spring Boot 2 / 3 的用户提供服务。已经开始使用 Spring Boot 4 的用户可以选择使用 JDK 17 编译的支持 Jackson 3 的 Nacos Client，互不冲突。

[KomachiSion]

@herodotus-ecosystem 这是一个不错的建议， 但是出一个client-jdk17或者client-jackson3 其实和当前的设计逻辑并不冲突。

因为nacos之前经历过 fastjson， gson 和jackson的数次变更，因此对于JSON的序列化和反序列化操作，都统一收敛到了JSONUtil里。

因此实际上这个nacos-client对接的都是JSONUtil，实际上不感知是jacks2还是jack3还是其他的json序列化组件。

即使我们采用client-jackson3的方式， 本质也是client-basic+nacos-client+nacos-client-jackson3-adapter（类似）的方案。本质应该没有区别。

@cxhello 设计方案的时候可以一起考虑进去。

[KomachiSion]

其实类似的问题在logback也出现过， nacos-client用8编译， adapter用17编译， 组合使用并没有问题。

不过拆分成client 和client-upper-jdk17 可以单开一个issue来进行讨论

[KomachiSion]

@cxhello

8 files use @JsonTypeInfo / @JsonSubTypes — this is the hardest part, since Jackson 3 changes the annotation package from com.fasterxml.jackson to tools.jackson.

It look like need more thinking, I see it included two parts:

1. naming module health check, I think it can be refactor, use cusomt jackson deserializer or serializer to releaced.
2. ai module mcp defination, I'm not sure whether it is easy to replace.

[herodotus-ecosystem]

@herodotus-ecosystem 这是一个不错的建议， 但是出一个client-jdk17或者client-jackson3 其实和当前的设计逻辑并不冲突。

因为nacos之前经历过 fastjson， gson 和jackson的数次变更，因此对于JSON的序列化和反序列化操作，都统一收敛到了JSONUtil里。

因此实际上这个nacos-client对接的都是JSONUtil，实际上不感知是jacks2还是jack3还是其他的json序列化组件。

即使我们采用client-jackson3的方式， 本质也是client-basic+nacos-client+nacos-client-jackson3-adapter（类似）的方案。本质应该没有区别。

@cxhello 设计方案的时候可以一起考虑进去。

对 Nacos 的代码不熟，我先看看代码了解一下。

[herodotus-ecosystem]

@cxhello

8 files use @JsonTypeInfo / @JsonSubTypes — this is the hardest part, since Jackson 3 changes the annotation package from com.fasterxml.jackson to tools.jackson.

It look like need more thinking, I see it included two parts:

1. naming module health check, I think it can be refactor, use cusomt jackson deserializer or serializer to releaced.
2. ai module mcp defination, I'm not sure whether it is easy to replace.

Jackson 3 注解部分的包路径没有变，还是使用的 jackson-annotaions。

@KomachiSion @cxhello

[KomachiSion]

如果注解的包路径没有变化，

@JsonTypeInfo / @JsonSubTypes / @JsonProperty 这几个也不太需要进行重构，改造成本会进一步降低