You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Design a Jackson 2/3 Compatibility Adapter Layer for Nacos to Support Spring 4.x and AI Ecosystem #14466
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:
Abstracting an adapter API for JsonUtil.
Identifying jackson version via feature class detection.
Defaulting to jackson2 for non-spring users as the safer option.
Minimizing user upgrade impact as much as possible.
Related design suggestions and PRs are welcome under this issue.
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.
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:
naming module health check, I think it can be refactor, use cusomt jackson deserializer or serializer to releaced.
ai module mcp defination, I'm not sure whether it is easy to replace.
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:
naming module health check, I think it can be refactor, use cusomt jackson deserializer or serializer to releaced.
ai module mcp defination, I'm not sure whether it is easy to replace.
Pipeline maintainer API 后续改为类型化返回:
将 PipelineExecution / PipelineExecutionResult / PipelineExecutionStatus / PipelineNodeResult 及其 Checkpoint 依赖下沉到 api 或提供 API DTO,新增 typed 方法,旧 JsonNode 方法保留 deprecated 兼容入口。
补充验证矩阵:仅 Jackson 2、仅 Jackson 3、Jackson 2+3 共存 auto 优先
Jackson 3、显式选择 Jackson 2/3、缺失 adapter 诊断、subtype 注册、 Result<Page<T>> / List<T> / Map<String,Object> 泛型反序列化,以及最小
Spring Boot 4 + nacos-client 样例。
整体目标是让现有 Jackson 2 用户无感,同时 Spring Boot 4 / Jackson 3 用户在满足运行
环境时自动切到 Jackson 3,并逐步清理 Nacos public API 对 Jackson 2 core/databind
类型的绑定。
Activity
cxhello commentedon Feb 10, 2026
Design Proposal: Jackson 2/3 Compatibility Adapter Layer
Current Status
I investigated the Jackson usage across the codebase:
JacksonUtils(15 public APIs, singleObjectMapper), only 2 places createObjectMapperdirectly.apimodule (Java 8 target) has 29 files andclienthas only 3 files with direct Jackson imports.@JsonTypeInfo/@JsonSubTypes— this is the hardest part, since Jackson 3 changes the annotation package fromcom.fasterxml.jacksontotools.jackson.Proposed Approach
1. Adapter Interface + Factory (in
commonmodule)NacosJsonAdapterinterface covering serialization, deserialization, JsonNode operations, and subtype registration.NacosJsonAdapterFactorydetects Jackson version viaClass.forName("tools.jackson.databind.ObjectMapper"), defaults to Jackson 2 if not found.JacksonUtilskeeps its public API unchanged, internally delegates to the adapter — all existing callers require zero changes.2. Jackson 3 as Separate Optional Module
Jackson2Adapterlives incommonmodule with compile-time Jackson 2 dependency (default).Jackson3Adapterlives in a new optional module (nacos-jackson3-adapter), compiled against Jackson 3, loaded via reflection at runtime.ClassNotFoundExceptionin Jackson 2 environments.3. Annotation Migration via MixIn
For
@JsonTypeInfo/@JsonSubTypes/@JsonPropertyinapimodule:Selector,AbstractHealthChecker, MCP registry models, etc.).apimodule 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
nacos-jackson3-adapterdependency.Implementation Phases
NacosJsonAdapter+Jackson2Adapter, refactorJacksonUtilsinternals (zero external impact)@JsonTypeInfoannotations to MixIn inapimodule (8 files)nacos-jackson3-adaptermoduleObjectMapperusages (ConfigExtInfoUtil, etc.)Key Considerations
api/clientmodules must stay Java 8 compatible; Jackson 3 requires Java 17+, hence the separate module.java.lang.reflect.Typeinstead of Jackson'sTypeReferenceto avoid leaking version-specific types.Feedback and alternative ideas are welcome!
herodotus-ecosystem commentedon Feb 10, 2026
个人的观点:Jackson2 和 Jackson 3 的兼容处理并不容易,核心问题主要有:
com.fasterxml.jackson变为tools.jackson。(这一点还可以考虑兼容)JacksonException。(这一点还可以考虑兼容)如果用户还在用 JDK 8 和 Spring Boot 2,那么编译就是个问题。单纯编译可能还好说,JDK 8 到 17 中间还有个鸿沟就是 Java 的模块化
我个人使用的很多涉及 Jackson 第三方,例如
jsonschema-generator、json-schema-validator、swagger等等,原本也都尝试考虑兼容,最后采用的都是升级大版本号。很理解 Nacos 不能盲目升级的问题。个人的小建议是:目前看影响较大的点,应该出在 Nacos Client 。那么对 Nacos Client 做单独处理,单独复制出一个模块叫 client-jackson3 或者 client-jdk17 之类模块,适配 Jackson3。然后控制好编译的 JDK 版本即可。
这样的好处是:
这样的好处就是原来基于 JDK 8 的 Nacos Client,可以继续为还在使用 Jackson2 和 Spring Boot 2 / 3 的用户提供服务。已经开始使用 Spring Boot 4 的用户可以选择使用 JDK 17 编译的支持 Jackson 3 的 Nacos Client,互不冲突。
KomachiSion commentedon Feb 11, 2026
@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 commentedon Feb 11, 2026
其实类似的问题在logback也出现过, nacos-client用8编译, adapter用17编译, 组合使用并没有问题。
不过拆分成client 和client-upper-jdk17 可以单开一个issue来进行讨论
KomachiSion commentedon Feb 11, 2026
@cxhello
It look like need more thinking, I see it included two parts:
herodotus-ecosystem commentedon Feb 11, 2026
对 Nacos 的代码不熟,我先看看代码了解一下。
herodotus-ecosystem commentedon Feb 11, 2026
Jackson 3 注解部分的包路径没有变,还是使用的 jackson-annotaions。
@KomachiSion @cxhello
KomachiSion commentedon Feb 25, 2026
如果注解的包路径没有变化,
@JsonTypeInfo / @JsonSubTypes / @JsonProperty 这几个也不太需要进行重构,改造成本会进一步降低
KomachiSion commentedon Jun 15, 2026
经过检查最新
develop(当前已升级到 Spring Boot 4.x),我认为 Nacos client 的 Jackson 2/3 适配可以按以下方向推进:增加一层 Nacos 自己的 JSON 适配门面
可以在
nacos-api中提供中立的JsonUtils、NacosJsonAdapter、NacosTypeReference<T>等接口/工具。业务代码后续只依赖这层中立 API,不再直接依赖 Jackson 2/3 的ObjectMapper、TypeReference、JsonNode、JavaType。现有
JacksonUtils可以先保留为兼容门面,避免影响存量用户。Jackson 2/3 adapter 放在
nacos-common建议默认提供两个 adapter:
isAvailable()判断当前运行环境是否真的存在 Jackson 3。JsonUtils通过ServiceLoader加载 adapter,并调用isAvailable()判断可用性。auto 模式下:nacos.client.json.adapter=auto|jackson2|jackson3,方便用户兜底。Jackson 2 和 Jackson 3 共存风险整体可控
Jackson 3 的 core/databind 包名已经迁到
tools.jackson.*,Jackson 2 是com.fasterxml.jackson.*,通常不会有传统同名类冲突。需要重点防的是 Nacos public API 继续暴露 Jackson 2 类型。jackson-annotations仍然保留com.fasterxml.jackson.annotation.*,因此现有 model 上的@JsonProperty、@JsonInclude、@JsonTypeInfo等注解可以先保留,不必优先迁到 MixIn。需要收敛的主要代码点
经过扫描,改造重点主要是:
api模块不应继续直接依赖jackson-core/jackson-databind,可以保留 annotation 依赖。ConfigBasicInfo等类中使用@JsonSerialize(using = ToStringSerializer.class)的地方,应替换为 annotation 层能力,例如@JsonFormat(shape = STRING),避免 databind serializer 泄露到公共模型。HealthCheckerFactory可以改用新的JsonUtils,其 subtype 注册能力也由 JSON adapter 承接。TypeReference可以改为NacosTypeReference<T>,adapter 内部再用Type构造 Jackson 2/3 自己的类型模型。JsonNode读取场景可以改为强类型对象或Map<String, Object>。GrpcUtils中的ByteBufferBackedInputStream可以替换为 Nacos 自己的轻量ByteBufferInputStream。ObjectMapper/JsonMapper的地方应收敛到 adapter,例如 canonical JSON 对比可以由JsonUtils.toCanonicalJson()提供。Pipeline maintainer API 建议强类型化
PipelineAdminClient/PipelineMaintainerService后续不建议继续返回JsonNode。可以将PipelineExecution、PipelineExecutionResult、PipelineExecutionStatus、PipelineNodeResult等公共 DTO 提取到nacos-api,然后将 maintainer API 调整为:旧的
JsonNode方法可以保留为 deprecated 兼容入口。验证建议
建议至少覆盖以下场景:
NacosTypeReference<Result<Page<T>>>、List<T>、Map<String, Object>等泛型反序列化。整体上,这个方案可以保持现有 Jackson 2 用户默认无感,同时让 Spring Boot 4 / Jackson 3 用户在满足运行环境时自动切到 Jackson 3,并逐步清理 Nacos public API 对 Jackson 2 core/databind 类型的绑定。
[ISSUE #14466] Add Java SDK JSON adapter spec (#15360)
KomachiSion commentedon Jun 15, 2026
经过 spec 合入和当前代码检查,建议后续按小的原子 PR 推进 Jackson 2 / Jackson 3
适配,避免一次性大改影响现有 client 用户:
nacos-api增加中立 JSON API:JsonUtils、NacosJsonAdapter、NacosTypeReference<T>和 subtype 注册模型。nacos-common增加默认 adapter:Jackson 2 adapter 保持 compile兼容;Jackson 3 adapter 使用 provided/optional 风格依赖并延迟初始化,确保 Java 8
运行时安全。
JacksonUtils作为 Jackson 2 兼容门面,新代码迁移到JsonUtils。nacos-api对 Jackson core/databind 的主依赖:HealthCheckerFactory改用中立 JSON;ConfigBasicInfo避免 databindserializer 注解。
TypeReference -> NacosTypeReference、JavaType内部化、ByteBufferBackedInputStream改为 Nacos 自有实现,MCP cache 使用中立canonical JSON。
将
PipelineExecution/PipelineExecutionResult/PipelineExecutionStatus/PipelineNodeResult及其Checkpoint依赖下沉到api或提供 API DTO,新增 typed 方法,旧JsonNode方法保留 deprecated 兼容入口。Jackson 3、显式选择 Jackson 2/3、缺失 adapter 诊断、subtype 注册、
Result<Page<T>>/List<T>/Map<String,Object>泛型反序列化,以及最小Spring Boot 4 + nacos-client 样例。
整体目标是让现有 Jackson 2 用户无感,同时 Spring Boot 4 / Jackson 3 用户在满足运行
环境时自动切到 Jackson 3,并逐步清理 Nacos public API 对 Jackson 2 core/databind
类型的绑定。
[ISSUE alibaba#14466] Stabilize GlobalExecutorTest environment setup
19 remaining items
[ISSUE alibaba#14466] Fix console pipeline DTO imports
[ISSUE #14466] Move pipeline execution DTOs to api (#15422)
[ISSUE alibaba#14466] Stabilize AI cache event tests
[ISSUE #14466] Add typed pipeline maintainer APIs (#15424)
[ISSUE #14466] Finalize Jackson adapter dependency checks (#15426)
[ISSUE alibaba#14466] Add Jackson 3 SDK IT profiles
[ISSUE alibaba#14466] Fix Jackson 3 final field deserialization
[ISSUE #14466] Add Jackson 3 SDK IT profiles (#15427)
[ISSUE #14466] Add JSON adapter selection diagnostics (#15434)
[ISSUE #14466] Clarify selected JSON adapter log (#15438)