本文详解如何在 Jackson 中使用 @JsonTypeInfo 和 @JsonSubTypes 实现基于字段（如 "method"）的多态反序列化，尤其解决泛型 List 在外部类型标识（As.EXTERNAL_PROPERTY）下无法正确绑定的典型问题。
本文详解如何在 jackson 中使用 `@jsontypeinfo` 和 `@jsonsubtypes` 实现基于字段（如 `"method"`）的多态反序列化，尤其解决泛型 `list
在使用 Jackson 进行多态反序列化时，一个常见误区是试图直接将 @JsonTypeInfo 注解应用于泛型集合字段（如 List
错误示例中的核心问题在于：
@JsonProperty("data")
@JsonTypeInfo(
use = JsonTypeInfo.Id.NAME,
include = JsonTypeInfo.As.EXTERNAL_PROPERTY,
property = "method")
@JsonSubTypes({
@JsonSubTypes.Type(value = AccountLedgerResponse.class, name = "AccountLedger")
})
List<T> data; // ❌ Jackson 无法为 List<T> 创建具体子类型实例AccountLedgerResponse.class 是单个对象类型，而 JSON 中 "data" 是数组（START_ARRAY），Jackson 期望的是一个能容纳该数组的容器类（wrapper class），而非数组元素类型本身。
✅ 正确做法是：定义明确的、与 JSON 结构严格匹配的封装类，并将 @JsonTypeInfo 应用于该容器类。
步骤一：定义具体响应容器类
为每种 method 值创建对应的顶层响应包装类，例如：
// 对应 method="AccountLedger" 的完整数据结构
public record AccountLedgerResult(
String signature,
UUID uuid,
String method, // 可选，若需复用
List<AccountLedgerResponse> data
) {
// 构造器或 Builder 可按需添加
}注意：此处 AccountLedgerResult 是一个具体类，其 data 字段是已知类型的 List
步骤二：在顶层 ResultList 中使用容器类作为多态目标
修改原 ResultList 定义，使其 data 字段类型为 Object 或统一基类（如 ResponseContainer），并把 @JsonTypeInfo 移至该字段上，指向具体的容器类：
public abstract class ResponseContainer { }
public record AccountLedgerResult(
String signature,
UUID uuid,
List<AccountLedgerResponse> data
) extends ResponseContainer { }
// 其他 method 对应的 Result 类（如 TradeHistoryResult）同理...然后定义主响应类：
public record ApiResponse(
String version,
@JsonProperty("result")
@JsonTypeInfo(
use = JsonTypeInfo.Id.NAME,
include = JsonTypeInfo.As.EXTERNAL_PROPERTY,
property = "method"
)
@JsonSubTypes({
@JsonSubTypes.Type(value = AccountLedgerResult.class, name = "AccountLedger"),
// @JsonSubTypes.Type(value = TradeHistoryResult.class, name = "TradeHistory"),
// ...
})
ResponseContainer result
) { }步骤三：确保 JSON 结构与 Java 类完全对齐
Jackson 要求 @JsonSubTypes.Type 指向的类必须能直接反序列化整个对应 JSON 子树。以 "method": "AccountLedger" 为例，AccountLedgerResult 必须能接收如下 JSON 片段：
{
"signature": "...",
"uuid": "9e4345db-6093-bb35-07d3-e335f1e28793",
"data": [ { /* first AccountLedgerResponse */ }, { /* second */ } ]
}因此，AccountLedgerResult 的字段名和 @JsonProperty 映射必须与 JSON 键精确一致（大小写敏感）。
✅ 完整可运行示例（关键片段）
// 1. 基础数据类
public record AccountLedgerResponse(
String userid,
String datestamp,
String orderid,
String accountname,
String messageid,
String transactiontype,
String currency,
String amount,
String gluepayid
) {}
// 2. 方法专属容器类
public record AccountLedgerResult(
String signature,
UUID uuid,
List<AccountLedgerResponse> data
) implements ResponseContainer {}
// 3. 多态基类与主响应
public interface ResponseContainer {}
public record ApiResponse(
String version,
@JsonProperty("result")
@JsonTypeInfo(
use = JsonTypeInfo.Id.NAME,
include = JsonTypeInfo.As.EXTERNAL_PROPERTY,
property = "method"
)
@JsonSubTypes({
@JsonSubTypes.Type(value = AccountLedgerResult.class, name = "AccountLedger")
})
ResponseContainer result
) {}
// 4. 使用
ObjectMapper mapper = new ObjectMapper();
ApiResponse response = mapper.readValue(jsonString, ApiResponse.class);
if (response.result() instanceof AccountLedgerResult ledger) {
System.out.println("Parsed " + ledger.data().size() + " ledger entries.");
}⚠️ 注意事项与最佳实践
- 避免在泛型字段上使用 @JsonTypeInfo：Jackson 的多态机制作用于具体类层级，而非类型参数。
- As.EXTERNAL_PROPERTY 要求 JSON 中存在对应字段：确保 "method" 字段始终存在且值与 @JsonSubTypes.Type.name 严格匹配（区分大小写）。
- 容器类应保持扁平结构：不要嵌套额外无关字段；JSON 中 "result" 下的字段应直接映射到容器类属性。
- 启用 DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES = false（可选）：防止因未来 API 新增字段导致反序列化失败。
- 测试覆盖所有 method 分支：为每个子类型编写独立单元测试，验证反序列化准确性。
通过将多态逻辑下沉到语义明确的容器类，而非悬置在泛型集合上，即可彻底规避 MismatchedInputException: Unexpected token (START_OBJECT), expected START_ARRAY 等典型错误，构建健壮、可维护的 JSON 多态处理体系。
