Java Jackson 多态反序列化如何限制允许的子类型

Jackson 的多态反序列化不是“JSON 里写一个类名就自动创建对象”这么简单。只要输入来自请求体、消息队列或文件，就应把类型入口限制在业务基类和登记过的子类型内。更稳妥的做法是：使用短类型名表达协议，使用 PolymorphicTypeValidator 做白名单判断，并为合法、未知、不兼容三种输入分别写回归测试。

先把多态入口收窄到业务基类

例如支付方式只允许银行卡和企业账户两类。JSON 可以保留一个 type 字段，但反序列化目标应是 PaymentMethod，而不是 Object。Jackson 官方文档将 PolymorphicTypeValidator 定位为基于类名的多态类型验证器；它既适用于默认类型，也适用于使用 @JsonTypeInfo 的显式多态配置。

做Java开发对接Jackson多态反序列化场景时，最容易踩的坑就是反序列化漏洞，很多人默认开启多态支持后没做子类型范围限制，很容易被恶意传入危险类触发安全问题。常规的安全实现思路，就是通过@JsonTypeInfo搭配@JsonSubTypes显式声明允许的子类范围，也可以借助自定义TypeResolverBuilder、配置mapper的PolymorphicTypeValidator来全局收拢允许的白名单类型，直接拦截不在名单内的任意非法子类型。

只要把多态反序列化的子类型完全收拢到你业务实际用到的类白名单里，不开放动态传入全类名实例化任意类的权限，就能彻底规避这类场景下的反序列化风险。

下面的模型把协议类型固定在接口层。注解里的 property 只是类型字段名，visible = false 表示类型元数据参与选择类，但不会再作为普通属性重复交给 Bean。

// 多态协议只从业务基类开始，不从 Object 开始
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = CardPayment.class, name = "card"),
    @JsonSubTypes.Type(value = BankPayment.class, name = "bank")
})
public sealed interface PaymentMethod permits CardPayment, BankPayment {
    String channel();
}

用短类型名映射业务子类

对外协议应使用稳定的业务词，而不是 com.example.payment.CardPayment 这样的实现类全名。这样可以在不改变 JSON 的情况下重构包名，也能避免把类加载路径暴露给调用方。短名并不等于安全白名单，真正的限制仍要落在验证器和业务层级上。

配置 PolymorphicTypeValidator 白名单

需要启用类名型多态时，给 ObjectMapper 配置一个尽量窄的验证器。示例按业务包前缀放行，并明确拒绝其他基类；如果项目能枚举全部子类，优先把规则收窄到这些具体类型。

// 白名单只覆盖支付模型所在包，其他类型默认不放行
var validator = BasicPolymorphicTypeValidator.builder()
        .allowIfBaseType(PaymentMethod.class)
        .allowIfSubType("com.example.payment.model.")
        .build();

var mapper = JsonMapper.builder()
        // 给注解型多态配置验证器；不要恢复 enableDefaultTyping()
        .polymorphicTypeValidator(validator)
        .build();

PaymentMethod value = mapper.readValue(json, PaymentMethod.class);
// 未知 type 或不兼容子类应抛出 InvalidTypeIdException，而不是静默创建对象

这里的包前缀只是示例，不能把整个公司公共包、插件目录或第三方依赖加入白名单。BasicPolymorphicTypeValidator.Builder 的规则按添加顺序判断，生产配置应先写拒绝范围，再写最小的允许范围，并通过测试确认容器类型、嵌套对象没有意外扩大入口。

做拒绝路径与迁移回归

迁移时至少保留三组 JSON：合法的 card，不存在的 script，以及虽能加载但不是 PaymentMethod 子类的类型。第一组应得到预期对象，后两组应得到可记录的异常。不要为了兼容旧调用方捕获异常后返回一个默认支付方式，否则调用方会把“未识别类型”误当成合法业务。

Jackson 官方说明特别提醒：全局默认类型与不可信内容组合会扩大类名选择面。检查旧项目时，先搜索 enableDefaultTyping、activateDefaultTyping 和 @JsonTypeInfo(use = Id.CLASS)，再逐个确认输入是否可信、基类是否具体、验证器是否存在。对于外部 API，显式子类型加短类型名通常比恢复旧的全局默认类型更容易审计。

相关问题

只写了 @JsonSubTypes，还需要验证器吗？ 如果类型入口是显式且闭合的，注解本身已经限制了映射；但仍应测试未知值和嵌套场景，不能因此对全局 Object 开启默认类型。

白名单写包名还是写具体类？ 能列出固定业务子类时优先具体类；包前缀只适合边界稳定、可由代码评审持续维护的模型包。

反序列化失败应该怎么处理？ 记录请求关联信息和类型值，返回统一的参数错误；不要把异常吞掉后构造一个权限更高或含糊的默认对象。

参考：PolymorphicTypeValidator API、Jackson 多态反序列化说明。