WildFly 26 Jackson自定义序列化失效原因与解决方法

从 WildFly 23 升级到 WildFly 26 后，许多开发者遇到了一个典型问题：原本运行正常的 Jackson 自定义序列化功能突然失效。无论是 @JsonValue 注解被忽略，还是自定义的 JsonSerializer 未被调用，甚至是 @JsonFormat 日期格式化失效，这些问题的根源往往指向同一个原因——依赖版本冲突。这并非简单的配置失误，而是 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 处理消息体写入时，@JsonValue、@JsonSerialize(using = ...) 这类注解会被跳过；
• 典型症状是，一个包装类 ResponseListWrapper 返回的可能是 { "objects": [...] } 这样的结构，而不是预期的 [...]，并且自定义的 JacksonListSerializer.serialize() 方法永远不会被执行。

关键点：在 Maven 中声明为 provided 的 Jackson 依赖（例如 jackson-databind-2.12.7.1）不会影响运行时。因为 WildFly 会忽略 WAR 包内标记为 provided 的依赖，实际使用的 Jackson 版本完全由服务器模块决定。

正确解决方案

要彻底解决此问题，需要从依赖源头和运行时配置两方面入手。

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

首先，检查所有自定义模块（尤其是安全相关模块）的 module.xml 文件，务必移除所有显式声明的 jackson-core、jackson-databind、jackson-annotations 等 JAR 资源。错误的做法是手动引入：

正确的做法是，委托给 WildFly 内置的模块：

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

WildFly 26 默认将 Jakarta JSON Binding（Json-B）作为首选的 JSON 处理器。为了让系统明确使用 Jackson，需要在启动参数中显式启用 Jackson 优先策略：

# 启动 WildFly 时添加 JVM 参数
-D"resteasy.preferJacksonOverJsonB"="true"

此参数可以添加到 standalone.conf（Linux）或 standalone.conf.bat（Windows）中，也可以通过管理控制台进行配置。

3. 验证 jboss-deployment-structure.xml 配置

确保你的应用在 WEB-INF/jboss-deployment-structure.xml 文件中，没有屏蔽 Jackson 提供器，并且正确声明了依赖：

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

如果经过以上步骤后问题仍然存在，或者你想确保万无一失，可以在 web.xml 中显式声明 RESTEasy 的 Jackson 提供器：

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

效果验证

完成上述所有修改并重启 WildFly 服务器后，原本出问题的接口（例如 /json）应该能返回正确的 JSON 数组格式：

[
  { "a": "a1", "b": "b1" },
  { "a": "a2", "c": "c2" }
]

与此同时，@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") 这类日期格式注解会生效，@JsonValue 标注的方法会被准确调用，自定义的 JacksonListSerializer.serialize() 方法也会在响应生成时如期执行。

总结与最佳实践

事项	推荐做法
Jackson 版本管理	完全交由 WildFly 模块控制，禁止在 module.xml 或 WAR 中打包 Jackson JAR
依赖声明方式	使用 替代 JAR 资源
JSON 处理器选择	生产环境必须设置 -Dresteasy.preferJacksonOverJsonB=true
Maven 依赖作用域	jackson-* 依赖保持 provided，仅用于编译期类型检查
调试技巧	启用 RESTEasy 日志：logging.category."org.jboss.resteasy".level=DEBUG，观察 MessageBodyWriter 选择过程

遵循这套方案，不仅能一劳永逸地解决 @JsonValue 和 @JsonSerialize 失效的困扰，还能有效避免在 WildFly 26 及以上版本中，因 Json-B 与 Jackson 混用而可能引发的序列化歧义、@JsonInclude 不生效、泛型类型擦除异常等一系列连锁问题。