【避坑】Spring MVC 自定义 HttpMessageConverter 优先级问题

避坑：自定义 Spring MVC 的 HttpMessageConverter 时，应显式设置各Converter的先后顺序，避免被Spring框架的“自动调整”打乱优先级。

 

@Configuration
public class MyConfig impliments WebMvcConfigurer {
  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(0, converter1);
    converters.add(1, converter2);
    converters.add(2, converter3);
    ...
  }
}

 

HttpMessageConverter 是用于 读写 HTTP Message Body 的数据转换器。

用 序列化和反序列化 类比：

• 读 Request Body 时， 其职能类似 反序列化；
• 写 Response Body 时，其职能类似 序列化。

 

踩坑经历

最近某个项目升级 Spring Boot，其依赖的 spring-boot-starter-web 原版本为 1.5.12.RELEASE，现使用版本为 “2.1.3.RELESE”。

结果升级出了点问题，请我去帮忙排查。

 

升级后发现 HTTP REST API 的返回值“格式”变了：返回类型为 复杂对象的 API，其返回值中的字段名都不符合序列化设置。

如，原来返回的字段名为 task_id，现在是 taskId 。

这显然是针对HTTP Response的“序列化”出了问题。

 

于是找到相关配置代码：

@Configuration
public class MyHttpMsgConverter extends WebMvcConfigurerAdapter {
  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    StringHttpMessageConverter strConverter = ...
    converters.add(strConverter);

    FastJsonHttpMessageConverter objConverter = ...
    converters.add(objConverter);
  }
}

 

原作者是想用 FastJson 序列化复杂对象。他在相关返回类中用 @JSONField 注解设置了各字段序列化后的名称。

因为 FastJson 序列化字符串时会在其前后加引号，所以先添加一个 StringHttpMessageConverter，优先级高于 FastJsonHttpMessageConverter。

注：

FastJson 中的StringCodec类负责序列化字符串；
StringCodec 会调用 SerializeWriter 的 writeString(String text)方法；
writeString 方法会在原字符串前后加了一对引号（双引号或单引号）：

package com.alibaba.fastjson.serializer;
public final class SerializeWriter extends Writer {
  public void writeString(String text) {
    if (useSingleQuotes) {
      writeStringWithSingleQuote(text);
    } else {
      writeStringWithDoubleQuote(text, (char) 0);
    }
  }
}

 

经过调试发现是新版 spring-webmvc（5.1.5.RELEASE） 中 原来两个自定义的Converter 被spring框架默认的Converter取代了。

自定义的Converter排在末尾，优先级低于其它默认Converter。

MappingJackson2HttpMessageConverter 接管了“序列化”复杂对象的职责，而不是 FastJsonHttpMessageConverter。

这两类Converter都实现了 HttpMessageConverter<Object> 接口，所以 FastJsonHttpMessageConverter 可以被替代。

AbstractMessageConverterMethodProcessor 中的 writeWithMessageConverters 方法负责选取合适的 Converter。

它们在下图右侧中的序号分别为 7 和 12。

因为默认 StringHttpMessageConverter 的字符编码（Charset） 与 原自定义Converter 相同，所以返回类型为String的API一切正常。

它们在下图右侧中的序号分别为 1 和 11。

 

 

原 spring-webmvc（4.3.16.RELEASE）中这两个自定义Converter排在最前面，优先级高于默认的Converter。

新版本的 spring-webmvc 中，因为 WebMvcConfigurer 实例列表中各项顺序不同，所以最终得到的Converter列表里各项顺序也不同。 

Spring框架提供的默认Converter来自 WebMvcAutoConfiguration。
在新版spring-webmvc中，它先于自定义的MyHttpMsgConverterConfig被处理，所以自定义Converter优先级最低。

 

相关代码：

class WebMvcConfigurerComposite implements WebMvcConfigurer {
  public void addWebMvcConfigurers(List<WebMvcConfigurer> configurers) {
    if (!CollectionUtils.isEmpty(configurers)) {
      this.delegates.addAll(configurers);
    }
  }
}

 

改造配置类

最直接的解决思路就是将自定义的Converter放到列表头部，使其优先级高于Spring默认的Converter。

@Configuration
public class MyHttpMsgConverterConfig impliments WebMvcConfigurer {
  @Override
  public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    StringHttpMessageConverter strConverter = ...
    converters.add(0, strConverter);

    FastJsonHttpMessageConverter objConverter = ...
    converters.add(1, objConverter);
  }
}