WildFly 26 Jackson自定义序列化失效问题排查与修复指南

许多开发者在将应用从 WildFly 23 迁移到 WildFly 26 时，都遇到了一个棘手的难题：原本正常工作的 Jackson 自定义序列化功能突然失效了。无论是 @JsonValue 注解被忽略，还是自定义的 JsonSerializer 未被调用，甚至是 @JsonFormat 日期格式化不起作用，这些问题的根源都指向同一个核心矛盾——Jackson 依赖版本冲突。这不仅仅是配置问题，更是 WildFly 模块化类加载机制与项目依赖管理之间的一场深度博弈。

具体而言，当你的应用程序或其依赖的自定义模块（例如 Elytron 安全登录模块）显式地打包了独立的 Jackson JAR 文件（如 jackson-databind-2.13.4.2.jar）时，JVM 的类加载器会优先加载这些“外来”版本。这直接导致 WildFly 26 服务器默认集成的、经过官方严格测试与适配的 RESTEasy-Jackson2 提供器被完全绕过。其后果是，Jackson 的核心注解处理器和序列化链无法正常初始化和注册，所有自定义序列化逻辑自然也就失效了。

问题根源深度剖析

WildFly 26 默认集成了 RESTEasy 6.x 与 Jackson 2.13+ 的组合，并通过其模块系统（org.jboss.resteasy.resteasy-jackson2-provider）提供标准化的 JSON 序列化与反序列化支持。然而，一旦应用或其模块在 module.xml 中直接引入了 Jackson 的 JAR 资源，就会引发复杂的类加载冲突：

• WildFly 内置的、经过预配置的 ObjectMapper 单例实例被应用自带的版本覆盖；
• 在 RESTEasy 处理 HTTP 响应消息体写入时，关键的 Jackson 注解如 @JsonValue、@JsonSerialize(using = ...) 会被直接跳过，不予处理；
• 典型的表现是，一个使用了 @JsonValue 的包装类 ResponseListWrapper，其 API 返回的可能是嵌套的 { "objects": [...] } 结构，而非预期的扁平化数组 [...]，并且自定义的 JacksonListSerializer.serialize() 方法永远不会被触发执行。

这里有一个至关重要的细节需要澄清：在 Maven 项目中声明为 provided 的 Jackson 依赖（例如 jackson-databind-2.12.7.1）通常不会对运行时环境造成影响。因为 WildFly 在部署 WAR 包时会忽略标记为 provided 的依赖库，实际生效的 Jackson 版本完全由服务器自身的模块系统决定。

完整解决方案与步骤

要一劳永逸地解决 WildFly 26 中 Jackson 序列化失效的问题，需要从依赖管理、服务器配置和部署描述符等多个层面进行系统性的调整。

1. 彻底清理冲突的 Jackson 模块依赖

首先，全面检查所有自定义模块（特别是安全认证模块和第三方库模块）的 module.xml 配置文件，必须移除所有显式声明的 jackson-core、jackson-databind、jackson-annotations 等 JAR 资源引用。以下是典型的错误配置示例：

正确的做法是，完全委托给 WildFly 内置的 Jackson 提供器模块，通过依赖声明来引用：

2. 强制 RESTEasy 优先使用 Jackson（而非默认的 Json-B）

WildFly 26 及更高版本默认将 Jakarta JSON Binding（Json-B）作为首选的 JSON 处理引擎。为了确保系统明确使用 Jackson 进行序列化，必须在 JVM 启动参数中显式设置优先级：

# 在启动 WildFly 服务器时添加以下 JVM 参数
-D"resteasy.preferJacksonOverJsonB"="true"

此参数可以永久性地添加到 standalone.conf（Linux/macOS）或 standalone.conf.bat（Windows）文件中，也可以通过 WildFly 管理控制台（Web Console）或 CLI 进行动态配置。

3. 核查并修正 jboss-deployment-structure.xml 配置

确保你的 Web 应用程序在 WEB-INF/jboss-deployment-structure.xml 部署描述符文件中，没有通过 屏蔽掉 Jackson 提供器，并且正确定义了模块依赖关系：

4. （可选）显式注册 Jackson 提供器以增强兼容性

如果执行以上步骤后问题依旧存在，或者你希望获得最高的配置确定性和兼容性，可以在应用的 web.xml 文件中显式声明 RESTEasy 的 Jackson 提供器：

    resteasy.providers
    org.jboss.resteasy.plugins.providers.jackson.ResteasyJackson2Provider

验证解决方案是否生效

完成上述所有配置修改并重启 WildFly 服务器后，原本出现问题的 REST API 接口（例如 /api/json）应当能够返回正确的、经过自定义序列化处理的 JSON 数据格式：

[
  { "fieldA": "valueA1", "fieldB": "valueB1" },
  { "fieldA": "valueA2", "fieldC": "valueC2" }
]

同时，以下功能应全部恢复正常： - @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") 注解对日期时间字段的格式化生效。 - 被 @JsonValue 注解标注的方法会被准确调用，用于生成最终的 JSON 值。 - 自定义的 JacksonListSerializer.serialize() 方法会在序列化列表对象时如期执行。

总结与最佳实践指南

遵循以上这套完整的解决方案与最佳实践，不仅能彻底解决 WildFly 26 中 @JsonValue、@JsonSerialize 等注解失效的难题，还能有效规避因 Json-B 与 Jackson 混合使用可能引发的其他复杂问题，例如序列化行为不一致、@JsonInclude 策略不生效、泛型类型信息丢失导致的序列化异常等，从而保障企业级 Java 应用 JSON 处理的稳定性和可维护性。