Skip to content

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

Closed

Description

@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.

Activity

  1. cxhello commented on Feb 10, 2026

    @cxhello
    Contributor

    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!

  2. herodotus-ecosystem commented on Feb 10, 2026

    @herodotus-ecosystem
    Contributor

    个人的观点: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,互不冲突。

  3. KomachiSion commented on Feb 11, 2026

    @KomachiSion
    CollaboratorAuthor

    @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 设计方案的时候可以一起考虑进去。

  4. KomachiSion commented on Feb 11, 2026

    @KomachiSion
    CollaboratorAuthor

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

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

  5. KomachiSion commented on Feb 11, 2026

    @KomachiSion
    CollaboratorAuthor

    @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.
  6. herodotus-ecosystem commented on Feb 11, 2026

    @herodotus-ecosystem
    Contributor

    @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 的代码不熟,我先看看代码了解一下。

  7. herodotus-ecosystem commented on Feb 11, 2026

    @herodotus-ecosystem
    Contributor

    @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。

    Image

    @KomachiSion @cxhello

  8. KomachiSion commented on Feb 25, 2026

    @KomachiSion
    CollaboratorAuthor

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

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

  9. KomachiSion commented on Jun 15, 2026

    @KomachiSion
    CollaboratorAuthor

    经过检查最新 develop(当前已升级到 Spring Boot 4.x),我认为 Nacos client 的 Jackson 2/3 适配可以按以下方向推进:

    1. 增加一层 Nacos 自己的 JSON 适配门面

      可以在 nacos-api 中提供中立的 JsonUtils、NacosJsonAdapter、NacosTypeReference<T> 等接口/工具。业务代码后续只依赖这层中立 API,不再直接依赖 Jackson 2/3 的 ObjectMapper、TypeReference、JsonNode、JavaType。

      现有 JacksonUtils 可以先保留为兼容门面,避免影响存量用户。

    2. Jackson 2/3 adapter 放在 nacos-common

      建议默认提供两个 adapter:

      • Jackson 2 adapter:继续作为默认兼容能力,依赖 Jackson 2 使用 compile。
      • Jackson 3 adapter:依赖 Jackson 3 使用 provided/optional,通过 isAvailable() 判断当前运行环境是否真的存在 Jackson 3。

      JsonUtils 通过 ServiceLoader 加载 adapter,并调用 isAvailable() 判断可用性。auto 模式下:

      • 只有一个 adapter 可用时,直接使用该 adapter。
      • 两个都可用时,优先使用 Jackson 3。
      • 都不可用时,给出清晰错误提示。
      • 保留显式配置,例如 nacos.client.json.adapter=auto|jackson2|jackson3,方便用户兜底。
    3. 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。

    4. 需要收敛的主要代码点

      经过扫描,改造重点主要是:

      • api 模块不应继续直接依赖 jackson-core / jackson-databind,可以保留 annotation 依赖。
      • ConfigBasicInfo 等类中使用 @JsonSerialize(using = ToStringSerializer.class) 的地方,应替换为 annotation 层能力,例如 @JsonFormat(shape = STRING),避免 databind serializer 泄露到公共模型。
      • HealthCheckerFactory 可以改用新的 JsonUtils,其 subtype 注册能力也由 JSON adapter 承接。
      • 内部使用的 Jackson TypeReference 可以改为 NacosTypeReference<T>,adapter 内部再用 Type 构造 Jackson 2/3 自己的类型模型。
      • 内部简单 JsonNode 读取场景可以改为强类型对象或 Map<String, Object>。
      • GrpcUtils 中的 ByteBufferBackedInputStream 可以替换为 Nacos 自己的轻量 ByteBufferInputStream。
      • 直接创建 ObjectMapper / JsonMapper 的地方应收敛到 adapter,例如 canonical JSON 对比可以由 JsonUtils.toCanonicalJson() 提供。
    5. Pipeline maintainer API 建议强类型化

      PipelineAdminClient / PipelineMaintainerService 后续不建议继续返回 JsonNode。可以将 PipelineExecution、PipelineExecutionResult、PipelineExecutionStatus、PipelineNodeResult 等公共 DTO 提取到 nacos-api,然后将 maintainer API 调整为:

      Result<PipelineExecution> getPipelineDetail(...);
      Result<Page<PipelineExecution>> listPipelineExecutions(...);

      旧的 JsonNode 方法可以保留为 deprecated 兼容入口。

    6. 验证建议

      建议至少覆盖以下场景:

      • 只有 Jackson 2:保持当前行为。
      • 只有 Jackson 3:Java 17 / Spring Boot 4 环境下可用。
      • Jackson 2 和 Jackson 3 同时存在:auto 模式优先 Jackson 3。
      • 显式指定 Jackson 2 / Jackson 3。
      • HealthChecker subtype 注册和反序列化。
      • NacosTypeReference<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 类型的绑定。

  10. added a commit that references this issue on Jun 15, 2026
  11. KomachiSion commented on Jun 15, 2026

    @KomachiSion
    CollaboratorAuthor

    经过 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 避免 databind
      serializer 注解。
    • 替换 client/common 运行时使用点:
      TypeReference -> NacosTypeReference、JavaType 内部化、
      ByteBufferBackedInputStream 改为 Nacos 自有实现,MCP cache 使用中立
      canonical JSON。
    • 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
    类型的绑定。

  12. added a commit that references this issue on Jun 15, 2026
  13. 19 remaining items

  14. added 2 commits that reference this issue on Jun 25, 2026
  15. added 8 commits that reference this issue on Jun 25, 2026
  16. added this to the 3.3.0 milestone on Jun 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    kind/enhancementCategory issues or prs related to enhancement.kind/featuretype/feature

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions