Spring Boot启动报错：ObjectMapper与JsonSerializer如何适配Page泛型接口

应用启动时创建ObjectMapper Bean抛出如下异常：

Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [com.fasterxml.jackson.databind.ObjectMapper]: Factory method 'objectMapper' threw exception; nested exception is java.lang.IllegalArgumentException: JsonSerializer of type com.somepackage.PageJsonSerializer does not define valid handledType() -- must either register with method that takes type argument or make serializer extend 'com.fasterxml.jackson.databind.ser.std.StdSerializer'

核心需求是为Jackson配置自定义序列化器，适配org.springframework.data.domain.Page这类泛型接口的序列化逻辑。

Jackson对序列化器的校验规则要求：如果自定义序列化器没有通过显式构造方法传参、泛型推导明确声明可处理的目标类型，就不能直接无类型参数调用addSerializer方法完成注册，否则会因为无法确认handledType()抛出校验错误。
之前尝试的带类型注册方案触发编译错误，本质是Java泛型的编译期类型校验限制：addSerializer方法的泛型签名要求传入的目标类型，必须和序列化器绑定的泛型参数完全兼容，而原始类型Page.class因为泛型擦除的校验规则，无法直接匹配Class<? extends Page<?>>的签名要求。

方案1：改造序列化器继承结构，自动推导处理类型 #

将自定义序列化器改为继承StdSerializer，并在构造方法中显式传入Page的类型引用，不需要额外处理泛型接口的实例化问题，Jackson会自动识别该序列化器的适配范围：

public class PageJsonSerializer extends StdSerializer<Page<?>> {
    // 显式调用父类构造器传入目标类型，避开泛型擦除导致的类型推导失败
    protected PageJsonSerializer() {
        super(Page.class);
    }

    @Override
    public void serialize(Page<?> value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        // 保留原有的自定义序列化逻辑
    }
}

改造后直接无参数调用addSerializer注册即可，不会再触发handledType()的校验错误：

@Bean
public ObjectMapper objectMapper() {
    SimpleModule pageModule = new SimpleModule();
    pageModule.addSerializer(new PageJsonSerializer());
    ObjectMapper objectMapper = new ObjectMapper();
    objectMapper.registerModules(pageModule);
    return objectMapper;
}

方案2：保留原序列化器结构，绕过泛型编译校验 #

如果不想修改序列化器的父类继承关系，可以在注册时通过两次类型强制转换，绕过编译期的泛型检查，完成带目标类型的注册：

@Bean
public ObjectMapper objectMapper() {
    SimpleModule pageModule = new SimpleModule();
    // 先转成原始类型，再强转为方法签名要求的泛型类型，规避编译报错
    pageModule.addSerializer((Class<Page<?>>) (Class<?>) Page.class, new PageJsonSerializer());
    ObjectMapper objectMapper = new ObjectMapper();
    objectMapper.registerModules(pageModule);
    return objectMapper;
}

• 只要序列化器绑定的是Page接口，Jackson会自动对所有实现了Page接口的类型（如默认实现PageImpl）应用该序列化逻辑，不需要为每个实现类单独注册。
• 在Spring Boot环境中，更推荐通过Jackson2ObjectMapperBuilderCustomizer注册自定义序列化规则，而非手动创建全新的ObjectMapper Bean，避免覆盖Spring Boot内置的Jackson序列化配置，减少框架兼容问题。

内容的提问来源于stack exchange，提问作者christopher.online