如何使用 Jackson 动态为泛型包装类生成带类型名称的 JSON 结构

本文介绍如何通过 jackson 的 `@jsontypeinfo` 与 `@jsontypename` 注解，结合泛型 wrapper 类，实现将不同子类型（如 payloadfoo、payloadbar）序列化为以类型名（如 `"foo"`、`"bar"`）为字段名的顶层 json 对象。

Jackson 原生不支持直接将泛型类型参数（如 Wrapper）自动映射为以类名小写为键的 JSON 字段（如 "foo": { ... }），但可通过 多态序列化机制 巧妙达成目标：将 Wrapper 设计为抽象基类或启用类型信息注入，并借助 @JsonTypeInfo 指定“属性式”类型标识（use = JsonTypeInfo.Id.NAME）和包含位置（include = JsonTypeInfo.As.WRAPPER_OBJECT），使 Jackson 在序列化时自动将整个对象包裹在以子类型名称为键的外层对象中。

关键实现步骤如下：

1. 为 Wrapper 类添加多态元数据
   使用 @JsonTypeInfo 启用类型识别，并设置 include = JsonTypeInfo.As.WRAPPER_OBJECT —— 这是实现 "foo": { ... } 结构的核心。同时配合 @JsonSubTypes 显式注册所有可能的子类型及其对应名称：

   @JsonTypeInfo(
       use = JsonTypeInfo.Id.NAME,
       include = JsonTypeInfo.As.WRAPPER_OBJECT, // ✅ 关键：生成外层命名包装对象
       property = "" // 空字符串表示不额外添加类型字段，仅用键名体现类型
   )
   @JsonSubTypes({
       @JsonSubTypes.Type(value = PayloadFoo.class, name = "foo"),
       @JsonSubTypes.Type(value = PayloadBar.class, name = "bar")
   })
   @Data
   @NoArgsConstructor
   @AllArgsConstructor
   public static class Wrapper {
       private SoaHeader soaHeader;
       private T payload;
   }

2. 为具体载荷类标注 @JsonTypeName
   PayloadFoo 和 PayloadBar 需分别标注 @JsonTypeName("foo") 和 @JsonTypeName("bar")，确保 Jackson 能正确关联类型名与实现类：

   @JsonTypeName("foo")
   @Data
   public static class PayloadFoo {
       private String foo;
   }
   
   @JsonTypeName("bar")
   @Data
   public static class PayloadBar {
       private String bar;
   }

3. 注意泛型擦除限制与最佳实践

   

   Creatie

   Creatie AI是一款专为UI/UX设计师打造的AI增强设计工具，致力于通过AI优化设计流程

   下载
   • Jackson 在运行时无法获取泛型 T 的真实类型（类型擦除），因此 Wrapper 必须作为多态基类参与序列化，不能仅靠泛型推断；必须显式注册所有子类型。
   • @JsonTypeInfo.As.WRAPPER_OBJECT 要求被序列化的对象必须是 @JsonSubTypes 中声明的具体子类实例（如 new Wrapper(...)），且需确保 payload 字段值非 null，否则可能触发空 Bean 异常（建议配置 configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false)）。
   • 若需更高灵活性（如动态注册类型），可考虑自定义 Serializer 或使用 ObjectWriter.withType() 显式指定类型，但会牺牲简洁性。

最终，调用 ObjectMapper 序列化时即可获得预期结构：

Wrapper fooWrapper = new Wrapper<>(new SoaHeader(), new PayloadFoo("test"));
String json = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(fooWrapper);
// 输出：
// {
//   "foo": {
//     "soaHeader": {},
//     "payload": {
//       "foo": "test"
//     }
//   }
// }

✅ 总结：该方案无需反射或手动构造 Map，完全基于 Jackson 标准注解，语义清晰、可维护性强，适用于 SOA 场景中统一响应包装器（如含 header + typed payload）的标准化 JSON 输出。