Spring MVC 自定义消息转换器

前言

在 Spring MVC 中，HttpMessageConverter 是处理请求和响应中 body 内容转换的重要组件。通过配置自定义的消息转换器，我们可以控制数据在序列化和反序列化时的格式。例如，将日期格式化为指定的字符串格式，或将 Long 类型转换为字符串以适应前端需求。

1. 配置自定义消息转换器

通过重写 configureMessageConverters 方法，可以覆盖默认的消息转换器，并使用自定义的转换器。

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    // 创建 Jackson 的消息转换器实例
    MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
    
    // 创建 ObjectMapper 并配置自定义序列化规则
    ObjectMapper objectMapper = new ObjectMapper();

    // 配置 Long 类型转换为字符串，解决 JS 无法处理大数值的问题
    SimpleModule simpleModule = new SimpleModule();
    simpleModule.addSerializer(Long.class, ToStringSerializer.instance);
    simpleModule.addSerializer(Long.TYPE, ToStringSerializer.instance);
    objectMapper.registerModule(simpleModule);

    // 配置 Date 类型格式化为指定的日期字符串格式
    objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

    // 将配置好的 ObjectMapper 设置到消息转换器中
    jackson2HttpMessageConverter.setObjectMapper(objectMapper);

    // 将自定义转换器添加到转换器列表的第一个位置，优先级最高
    converters.add(0, jackson2HttpMessageConverter);
}

• configureMessageConverters 方法：用于添加自定义的消息转换器。此方法会覆盖 Spring 默认的消息转换器配置。
• MappingJackson2HttpMessageConverter：这是一个常用的 JSON 转换器，基于 Jackson 实现。可以通过配置 ObjectMapper 自定义 JSON 序列化和反序列化规则。
• ToStringSerializer：将 Long 类型转换为字符串，防止前端在处理大数值时出现精度丢失问题。
• DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES：配置反序列化时忽略未知属性，防止 JSON 中多余字段导致异常。
• SimpleDateFormat：设置日期格式，确保在序列化和反序列化时统一日期格式。

2. 消息转换器的默认行为

如果未配置自定义转换器，Spring MVC 会自动注册一组默认的消息转换器。这些默认转换器涵盖了常见的序列化和反序列化需求，例如处理 JSON、XML、字符串等。

protected final List<HttpMessageConverter<?>> getMessageConverters() {
    if (this.messageConverters == null) {
        this.messageConverters = new ArrayList<>();
        // 添加通过 configureMessageConverters 自定义的转换器（此配置会覆盖默认配置）
        configureMessageConverters(this.messageConverters);
        // 如果未添加自定义转换器，则使用默认转换器
        if (this.messageConverters.isEmpty()) {
            addDefaultHttpMessageConverters(this.messageConverters);
        }
        // 添加通过 extendMessageConverters 配置的扩展转换器（此配置在默认配置基础上扩展）
        extendMessageConverters(this.messageConverters);
    }
    return this.messageConverters;
}

• addDefaultHttpMessageConverters 方法：如果没有自定义转换器，Spring 会添加一组默认的转换器（如 JSON、XML、字符串等）。
• extendMessageConverters 方法：允许在默认转换器的基础上扩展新的转换器，而不会覆盖原有配置。

3. 自定义转换器可能失效的原因

如果你在 configureMessageConverters 方法中添加了自定义转换器，但它未生效，通常是因为自定义转换器被放在了默认转换器之后。Spring MVC 在处理请求和响应时，会优先使用列表中靠前的转换器，如果默认转换器已经匹配了请求或响应类型，则自定义转换器不会被执行。

4. 解决方法：调整转换器顺序

为了确保自定义转换器生效，可以将其放在转换器列表的最前面：

converters.add(0, jackson2HttpMessageConverter);

这样做可以确保自定义转换器优先匹配并处理请求和响应数据，避免被默认转换器覆盖。

5. 扩展配置：extendMessageConverters

如果你希望在不影响默认转换器的情况下添加自定义转换器，可以使用 extendMessageConverters 方法：

@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    // 在默认转换器的基础上添加自定义转换器
    converters.add(jackson2HttpMessageConverter);
}

extendMessageConverters 方法不会覆盖默认配置，而是将自定义转换器添加到已有转换器列表的末尾。

6. 注意事项

• 使用 configureMessageConverters 添加转换器会覆盖默认配置，谨慎使用。
• 如果只是想扩展转换器而不影响默认行为，建议使用 extendMessageConverters 方法。
• 调整转换器顺序对于确保自定义逻辑生效非常重要。

总结

通过自定义消息转换器，Spring MVC 提供了灵活的方式来控制请求和响应中的数据格式化和解析逻辑。在实际开发中，可以根据业务需求选择合适的配置方式，确保系统在处理复杂数据时具备足够的扩展性和稳定性。