WildFly 26 中 Jackson 自定义序列化失效的根源与解决方案

WildFly 26 升级后，@JsonValue 和 @JsonSerialize 等 Jackson 注解失效，导致 JSON 输出不符合预期（如包装类返回对象而非数组、日期格式化丢失），根本原因在于类路径冲突：自定义安全模块引入了高版本 Jackson JAR，覆盖了 WildFly 内置的 Jackson 2.x 提供器。

不少团队在将应用升级到 WildFly 26 后，都遇到了一个看似诡异的问题：那些用得好好的 Jackson 注解，比如 @JsonValue 和 @JsonSerialize，突然就“罢工”了。表现就是，本该返回数组的包装类输出了一个对象，精心设置的日期格式也消失不见。这背后的罪魁祸首，往往不是代码逻辑错误，而是升级后环境里隐藏的“类路径战争”。

简单来说，WildFly 26 基于 Jakarta EE 9+ 和 RESTEasy 4.7+，其 JSON 序列化的默认引擎是 RESTEasy 的 Jackson 2 集成模块。这套机制深度依赖于 WildFly 的模块化系统。问题就出在，如果你的应用或者某个自定义模块（比如一个独立的认证模块）自己打包了 Jackson 的 JAR 包，就会打破这个平衡，引发一系列连锁反应：

• 类加载优先级被碘伏：WildFly 的模块类加载器会按照依赖声明的顺序来加载类。一旦你的自定义模块里包含了 Jackson 的 JAR，那么 com.fasterxml.jackson.* 这些类就会优先于 WildFly 官方 resteasy-jackson2-provider 模块中的同名类被加载。
• 注解处理器“失联”：@JsonValue、@JsonSerialize 这些注解的解析，全靠 Jackson 的 ObjectMapper 来执行。如果这个 ObjectMapper 实例来自你引入的外部 JAR，而不是由 RESTEasy 托管的那一个，那么它的所有配置（比如模块注册、序列化器查找逻辑）就脱离了 WildFly 容器的管控。结果就是，你写的自定义序列化器（例如 JacksonListSerializer）根本不会被调用。
• 日期格式化配置被无视：@JsonFormat 注解依赖 SimpleDateFormat 的注册以及 Ja vaTimeModule 等模块的支持。外部的 Jackson 版本很可能没有启用这些模块，或者其与 RESTEasy 的 MessageBodyWriter 集成是断裂的，导致格式化指令形同虚设。

正确解决方案：统一使用 WildFly 内置 Jackson 提供器

解决这个问题的核心思路就一条：让整个应用都统一使用 WildFly 容器管理的那套 Jackson，放弃“自带干粮”的做法。

1. 移除冗余 Jackson JAR

首先，彻底检查所有自定义模块，特别是它们的 module.xml 文件。把在 标签下手动引入的 Jackson JAR 声明全部删除。

2. 声明标准 RESTEasy Jackson 依赖

接着，在对应模块的 module.xml 中，只声明 WildFly 官方提供的标准依赖模块。

3. 强制 RESTEasy 优先使用 Jackson（可选但推荐）

为了确保万无一失，可以在 WildFly 的启动参数里加上一个开关。编辑 standalone.conf（Linux）或 standalone.conf.bat（Windows），添加以下 JVM 参数：

-D"resteasy.preferJacksonOverJsonB"="true"

这个参数的作用是，当存在多个 JSON 提供器（比如还有 JSON-B 的提供器）时，明确告诉 RESTEasy 优先选择 Jackson 2 作为默认的序列化引擎。

4. Ma ven 依赖调整（关键）

应用层面的 pom.xml 也需要相应调整。关键点在于，将 Jackson 依赖的 设置为 provided，并确保排除掉其他依赖传递进来的旧版本 Jackson，避免在打包时引入冲突。

    com.fasterxml.jackson.core
    jackson-databind
    2.13.4.2
    provided 



    
        com.fasterxml.jackson.core
        jackson-databind
    

⚠️ 注意：WildFly 26 本身已经内置了 Jackson 2.13.x 系列。因此，你的应用 WAR 包里完全不需要再打包 Jackson 的 JAR。使用 provided 是正确的做法，但前提是必须确保没有其他模块重复提供——这正是本例冲突的根本矛盾点。

5. 验证与调试技巧

调整之后，如何验证是否成功了呢？这里有两个实用的技巧：

• 启动时，可以添加参数 -Djboss.modules.system.pkgs=org.jboss.resteasy,com.fasterxml.jackson，这有助于在日志中更清晰地追踪相关类的加载来源。

• 在资源类里写一个简单的调试端点，注入 Providers 并获取 ObjectMapper，打印其哈希值和类加载器信息：

  @Context
  private Providers providers;
  
  @GET
  public Response debug() {
      ObjectMapper mapper = providers.getProvider(JsonMapper.class).get();
      System.out.println("Mapper CL: " + mapper.getClass().getClassLoader());
      System.out.println("Mapper hash: " + mapper);
      return Response.ok().build();
  }

  如果输出的类加载器显示包含 “resteasy-jackson2-provider” 字样，那么恭喜你，集成成功了。

总结

说到底，WildFly 26 里 Jackson 行为的这种变化，并不是一个 Bug，而是其模块化设计理念下的必然结果：容器要求所有生态组件统一受其管理，拒绝“自带轮子”式的依赖嵌入。

解决这类问题的核心原则可以归纳为三点：
信任容器：优先且唯一地使用 org.jboss.resteasy.resteasy-jackson2-provider 这个官方模块。
清理污染：彻底检查并移除任何手动引入的、多余的 Jackson JAR。
明确契约：通过 resteasy.preferJacksonOverJsonB 参数或 jboss-deployment-structure.xml 文件，清晰地声明你的应用意图。

按照上述步骤操作后，你会发现 @JsonValue 注解又能正确触发包装类返回数组了，@JsonFormat 指定的日期格式也如期呈现，所有自定义的序列化逻辑都将回归预期的轨道。