背景
SpringMVC系列的第五篇介绍消息转换器，本文讨论的消息转换指代调用Controller接口后，对结果进行转换处理的过程。
内容包括介绍自定义消息转换器、SpringMVC常见的消息转换器、Spring消息转换器工作原理等三部分。
本文以 SpringMVC系列-2 HTTP请求调用链 和 SpringMVC系列-4 参数解析器 为基础，对相同内容不再重述。
1.自定义消息转换器
自定义消息转换器，需要实现HttpMessageConverter接口，该接口定义如下：
public interface HttpMessageConverter<T> {boolean canWrite(Class<?> clazz, @Nullable MediaType mediaType);void write(T t, @Nullable MediaType contentType, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException;List<MediaType> getSupportedMediaTypes();// ⚠️：read相关逻辑不是本文关注的部分boolean canRead(Class<?> clazz, @Nullable MediaType mediaType);T read(Class<? extends T> clazz, HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException;
}
有三个比较重要的方法：
(1) getSupportedMediaTypes方法返回该解析器支持的MIME媒体类型；
(2) canWrite方法判断该解析器能否将目标类型的对象转化为指定的MIME媒体类型；
(3) write方法将目标对象转化为mediaType的二进制流并写入到outputMessage流对象中。
自定义消息转换器：
public class UserInfoHttpMessageConverter implements HttpMessageConverter<UserInfo> {@Overridepublic boolean canWrite(Class clazz, MediaType mediaType) {return clazz == UserInfo.class;}@Overridepublic List<MediaType> getSupportedMediaTypes() {return Collections.singletonList(MediaType.APPLICATION_JSON);}@Overridepublic void write(UserInfo userInfo, MediaType contentType, HttpOutputMessage outputMessage)throws IOException, HttpMessageNotWritableException {String result = userInfo.getId() + "_" + userInfo.getName() + "_" + LocalDateTime.now();outputMessage.getBody().write(result.getBytes(StandardCharsets.UTF_8));}//...read Ignore
}
该自定义转换器表示可以将UserInfo类型的消息以"application/json"媒体格式写出。
将自定义的消息转换器注册到SpringMVC：
@Configuration
public class MyWebMvcConfigurer implements WebMvcConfigurer {@Overridepublic void configureMessageConverters(List<HttpMessageConverter<?>> converters) {converters.add(0, new UserInfoHttpMessageConverter());}
}
注意：这里通过SpringMVC的配置类WebMvcConfigurer进行注册，注册原理在本文第三章中说明。
用例涉及的Controller接口和基础类：
@RestController
@RequestMapping("/api/user")
public class UserInfoController {@GetMapping("/query")public UserInfo query() {return new UserInfo().setName("test_sy").setId(28);}
}@Data
@Accessors(chain = true)
public class UserInfo {private Integer id;private String name;
}
使用postman调用结果如下所示：
2.消息转换器
SpringBoot版本为2.3.2.RELEASE
2.1 框架内置的消息解析器
框架内置的消息解析器支持的MIME类型分布如下所示：
ByteArrayHttpMessageConverter：用于处理字节数组（byte array）的转换。
ByteArrayHttpMessageConverterapplication/octet-stream*/*
StringHttpMessageConverter：用于处理字符串的转换。
StringHttpMessageConvertertext/plain*/*StringHttpMessageConvertertext/plain*/*
ResourceHttpMessageConverter：用于处理Spring Resource的实现类的转换。Spring Resource是一个抽象类，它封装了对各种资源（如文件、数据库连接等）的操作。
ResourceHttpMessageConverter*/*
ResourceRegionHttpMessageConverter：这个类是ResourceHttpMessageConverter的子类，它用于处理Resource的某个特定区域（如文件的某个部分）。
ResourceRegionHttpMessageConverter*/*
SourceHttpMessageConverter：用于处理javax.xml.transform.Source的转换。javax.xml.transform.Source是用于XML转换的接口。
SourceHttpMessageConverterapplication/xml text/xml application/*+xml
AllEncompassingFormHttpMessageConverter：用于处理表单提交请求，能解析复杂的form表单，包括文件上传等。
AllEncompassingFormHttpMessageConverterapplication/x-www-form-urlencodedmultipart/form-datamultipart/mixed
MappingJackson2HttpMessageConverter：用于处理JSON序列化和反序列化。
MappingJackson2HttpMessageConverterapplication/json application/*+jsonMappingJackson2HttpMessageConverterapplication/jsonapplication/*+json
Jaxb2RootElementHttpMessageConverter：这个类使用JAXB（Java Architecture for XML Binding）进行XML序列化和反序列化。
Jaxb2RootElementHttpMessageConverterapplication/xmltext/xmlapplication/*+xml
上述内置转换器中包括2个StringHttpMessageConverter和2个MappingJackson2HttpMessageConverter。转换器的顺序决定了其优先级，因此第二个StringHttpMessageConverter和MappingJackson2HttpMessageConverter处于失效状态：
[1] HttpMessageConvertersAutoConfiguration自动装配类引入的StringHttpMessageConverter替代了默认的StringHttpMessageConverter(SpringMVC框架自带)，区别是前者默认字符集为UTF_8，后者为ISO_8859_1。
[2] JacksonHttpMessageConvertersConfiguration自动装配类引入的MappingJackson2HttpMessageConverter替代了默认的MappingJackson2HttpMessageConverter。区别是使用其内部实现序列化和反序列化的ObjectMapper对象来自全局Bean对象(来自JacksonAutoConfiguration自动装配类引入的ObjectMapper)。因此在配置文件中对spring.jackson属性的配置可以体现在MappingJackson2HttpMessageConverter转换器上。
2.2 MappingJackson2HttpMessageConverter转换器
(1) 匹配方法
由于MappingJackson2HttpMessageConverter是GenericHttpMessageConverter接口的实现类，匹配时根据canWrite(Type, Class<?>, MediaType)方法进行:
@Override
public boolean canWrite(@Nullable Type type, Class<?> clazz, @Nullable MediaType mediaType) {return canWrite(clazz, mediaType);
}
上述方法实现时吞掉了Type类型的参数, 调用重载的canWrite(Class<?>, MediaType)方法:
@Override
public boolean canWrite(Class<?> clazz, @Nullable MediaType mediaType) {
if (!canWrite(mediaType)) {return false;
}
if (mediaType != null && mediaType.getCharset() != null) {Charset charset = mediaType.getCharset();if (!ENCODINGS.containsKey(charset.name())) {return false;}
}AtomicReference<Throwable> causeRef = new AtomicReference<>();
if (this.objectMapper.canSerialize(clazz, causeRef)) {return true;
}
logWarningIfNecessary(clazz, causeRef.get());
return false;
}
该方法可以分为三个部分:
[1] 调用canWrite(MediaType)判断媒体类型是否支持:
protected boolean canWrite(@Nullable MediaType mediaType) {if (mediaType == null || MediaType.ALL.equalsTypeAndSubtype(mediaType)) {return true;}for (MediaType supportedMediaType : getSupportedMediaTypes()) {if (supportedMediaType.isCompatibleWith(mediaType)) {return true;}}return false;
}
如果mediaType为空或者*/*或者与消息解析器支持的类型匹配则返回true;框架预置MappingJackson2HttpMessageConverter时，支持的MediaType已确定，为application/json和application/*+json
[2] 判断编码类型是否符合, 支持的编码格式有UTF-8,UTF-16BE,UTF-16LE,UTF-32BE,UTF-32LE,US-ASCII
if (mediaType != null && mediaType.getCharset() != null) {Charset charset = mediaType.getCharset();if (!ENCODINGS.containsKey(charset.name())) {return false;}
}
MediaType对象的Charset为空时，默认支持；
[3] 调用ObjectMapper的canSerialize方法判断是否可被序列化;
AtomicReference<Throwable> causeRef = new AtomicReference<>();
if (this.objectMapper.canSerialize(clazz, causeRef)) {return true;
}
(2) 写方法
@Override
public final void write(final T t, @Nullable final Type type, @Nullable MediaType contentType, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException {final HttpHeaders headers = outputMessage.getHeaders();// 添加Content-type: application/jsonaddDefaultHeaders(headers, t, contentType);if (outputMessage instanceof StreamingHttpOutputMessage) {StreamingHttpOutputMessage streamingOutputMessage = (StreamingHttpOutputMessage) outputMessage;streamingOutputMessage.setBody(outputStream -> writeInternal(t, type, new HttpOutputMessage() {@Overridepublic OutputStream getBody() {return outputStream;}@Overridepublic HttpHeaders getHeaders() {return headers;}}));} else {writeInternal(t, type, outputMessage);outputMessage.getBody().flush();}
}
write方法包含两个逻辑步骤：添加默认头域和写操作，写操作的实际执行方法在writeInternal中：
@Override
protected void writeInternal(Object object, @Nullable Type type, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException {MediaType contentType = outputMessage.getHeaders().getContentType();// 默认为UTF_8类型JsonEncoding encoding = getJsonEncoding(contentType);JsonGenerator generator = this.objectMapper.getFactory().createGenerator(outputMessage.getBody(), encoding);writePrefix(generator, object);Object value = object;Class<?> serializationView = null;FilterProvider filters = null;JavaType javaType = null;if (object instanceof MappingJacksonValue) {MappingJacksonValue container = (MappingJacksonValue) object;value = container.getValue();serializationView = container.getSerializationView();filters = container.getFilters();}if (type != null && TypeUtils.isAssignable(type, value.getClass())) {javaType = getJavaType(type, null);}ObjectWriter objectWriter = (serializationView != null ?this.objectMapper.writerWithView(serializationView) : this.objectMapper.writer());if (filters != null) {objectWriter = objectWriter.with(filters);}if (javaType != null && javaType.isContainerType()) {objectWriter = objectWriter.forType(javaType);}SerializationConfig config = objectWriter.getConfig();if (contentType != null && contentType.isCompatibleWith(MediaType.TEXT_EVENT_STREAM) &&config.isEnabled(SerializationFeature.INDENT_OUTPUT)) {objectWriter = objectWriter.with(this.ssePrettyPrinter);}objectWriter.writeValue(generator, value);writeSuffix(generator, object);generator.flush();
}
上述方法可以分为三个步骤：添加前缀(如果有,内置的对象无前缀)、写内容、添加后缀(如果有,内置的对象无前缀)，操作完全基于objectMapper对象；关于ObjectMappr的API用法不是本文的重点，不进行赘述。
3.工作原理
框架内置的消息转换器为处理HTTP请求和响应提供了强大的支持，基本可以满足项目的需要。这些转换器在容器启动时进行实例化和设置，后被保存在RequestMappingHandlerAdapter对象的messageConverters属性中。
当HTTP请求到达后，RequestMappingHandlerAdapter会构造一个ServletInvocableHandlerMethod对象，
且该对象拥有来自RequestMappingHandlerAdapter的消息转换器。
ServletInvocableHandlerMethod与HttpMessageConveter的关系图如下所示：
当HTTP请求被DispatcherServlet接受时，调用链会进入RequestMappingHandlerAdapter的invokeHandlerMethod方法，构造ServletInvocableHandlerMethod对象并调用invokeAndHandle方法：
public void invokeAndHandle(ServletWebRequest webRequest, ModelAndViewContainer mavContainer, Object... providedArgs) throws Exception {// 反射调用Controller接口获取返回结果Object returnValue = invokeForRequest(webRequest, mavContainer, providedArgs);//... //将ModelAndViewContainer对象设置为请求未处理状态mavContainer.setRequestHandled(false);//处理结果this.returnValueHandlers.handleReturnValue(returnValue, getReturnValueType(returnValue), mavContainer, webRequest);
}
说明：
从Controller接口获取返回结果后，将结果处理工作委托给了returnValueHandlers属性，该属性是HandlerMethodReturnValueHandlerComposite组合类型，内部维持了一个List<HandlerMethodReturnValueHandler> returnValueHandlers列表；因此handleReturnValue实际会根据匹配关系分派到指定的HandlerMethodReturnValueHandler中。
框架内置的HandlerMethodReturnValueHandler和匹配关系如下：
ModelAndView及其子类->ModelAndViewMethodReturnValueHandler
Model及其子类->ModelMethodProcessor
View及其子类->ViewMethodReturnValueHandler
ResponseEntity及其子类或(ResponseEntity包裹)->ResponseBodyEmitterReturnValueHandler
StreamingResponseBody及其子类或(ResponseEntity包裹)->StreamingResponseBodyReturnValueHandler
HttpEntity，ResponseEntity->HttpEntityMethodProcessor
HttpHeaders及其子类->HttpHeadersReturnValueHandler
Callable及其子类->CallableMethodReturnValueHandler
DeferredResult、ListenableFuture、CompletionStage及其子类->DeferredResultMethodReturnValueHandler
WebAsyncTask及其子类->AsyncTaskMethodReturnValueHandler
ModelAttribute注解->ModelAttributeMethodProcessor
方法或类被ResponseBody注解->RequestResponseBodyMethodProcessor
void,CharSequence及其子类->ViewNameMethodReturnValueHandler
Map及其子类->MapMethodProcessor
本文重点关注RequestResponseBodyMethodProcessor, 该结果处理器的匹配规则如下：
public boolean supportsReturnType(MethodParameter returnType) {return (AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), ResponseBody.class) ||returnType.hasMethodAnnotation(ResponseBody.class));
}
即方法或者类被@ResponseBody注解的Controller接口使用RequestResponseBodyMethodProcessor。
当请求进入RequestResponseBodyMethodProcessor的handleReturnValue方法后:
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws IOException, HttpMediaTypeNotAcceptableException, HttpMessageNotWritableException {// 将该HTTP请求标记为已处理mavContainer.setRequestHandled(true);// 从webRequest获取HttpServletRequest的代理类ServletServerHttpRequest inputMessage = createInputMessage(webRequest);// 从webRequest获取HttpServletResponse的代理类ServletServerHttpResponse outputMessage = createOutputMessage(webRequest);// Try even with null return value. ResponseBodyAdvice could get involved.writeWithMessageConverters(returnValue, returnType, inputMessage, outputMessage);
}
核心逻辑在writeWithMessageConverters方法:
protected <T> void writeWithMessageConverters(@Nullable T value, MethodParameter returnType, ServletServerHttpRequest inputMessage, ServletServerHttpResponse outputMessage) throws IOException, HttpMediaTypeNotAcceptableException, HttpMessageNotWritableException {// ...
}
该方法较长，主要步骤如下:
(1)获取返回对象类型，并使用Object对象接收返回对象
Object body;
Class<?> valueType;
Type targetType;
if (value instanceof CharSequence) {// 字符类型，则直接进行转换body = value.toString();valueType = String.class;targetType = String.class;
} else {body = value;valueType = getReturnValueType(body, returnType);targetType = GenericTypeResolver.resolveType(getGenericType(returnType), returnType.getContainingClass());
}
注意：valueType为对象实际类型，不包括泛型信息；targetType包含泛型信息。
如:
public Map<String, Integer> getMap() {return new HashMap<>();
}
valueType为java.util.HashMap;而 targetType表示java.util.Map<java.lang.String, java.lang.Integer>
(2)InputStreamResource和Resource资源类型的特殊处理(Ignore);
(3)协商媒体类型，确定媒体类型
HttpServletRequest request = inputMessage.getServletRequest();
// 获取HTTP请求头中接收的媒体类型，代表客户端要求的MIME类型[标注1]
List<MediaType> acceptableTypes = getAcceptableMediaTypes(request);
// 从所有的消息转换器中取媒体类型交集，代表服务器可以处理的媒体类型
List<MediaType> producibleTypes = getProducibleMediaTypes(request, valueType, targetType);if (body != null && producibleTypes.isEmpty()) {throw new HttpMessageNotWritableException("No converter found for return value of type: " + valueType);
}
// 从服务器支持的媒体类型中筛选出客户端要求的MIME类型
List<MediaType> mediaTypesToUse = new ArrayList<>();
for (MediaType requestedType : acceptableTypes) {for (MediaType producibleType : producibleTypes) {if (requestedType.isCompatibleWith(producibleType)) {mediaTypesToUse.add(getMostSpecificMediaType(requestedType, producibleType));}}
}if (mediaTypesToUse.isEmpty()) {if (body != null) {throw new HttpMediaTypeNotAcceptableException(producibleTypes);}if (logger.isDebugEnabled()) {logger.debug("No match for " + acceptableTypes + ", supported: " + producibleTypes);}return;
}
// 排序，按照品质因子进行[标注2]
MediaType.sortBySpecificityAndQuality(mediaTypesToUse);
for (MediaType mediaType : mediaTypesToUse) {if (mediaType.isConcrete()) {selectedMediaType = mediaType;break;} else if (mediaType.isPresentIn(ALL_APPLICATION_MEDIA_TYPES)) {selectedMediaType = MediaType.APPLICATION_OCTET_STREAM;break;}
}
上述逻辑有两个地方需要补充说明一下：
[1] getAcceptableMediaTypes方法从HttpServletRequest对象中获取客户端允许的MIME类型，由于框架内置的媒体协商器是HeaderContentNegotiationStrategy，即从请求头中的ACCEPT字段获取MIME类型;
[2] Accept代表客户端允许的媒体类型，客户端可以同时支持多种类型的资源，且可通过品质因数进行排序，如下所示:
Accept: text/html;q=0.1,application/xhtml+xml;q=0.2,application/xml;q=0.3,application/json;q=0
Note: 不接受application/json类型，按照期望排序可接收text/html、application/xhtml+xml、application/xml；类型
即q值越大，表示期望值越高。另外，出Accept外，Accept-Charset(字符集)、Accept-Encoding(压缩算法)、Accept-Language(国际化)在HTTP媒体协商过程也可携带品质因子.
(4)选择消息解析器，进行消息处理
// 删除选中的MIME的品质因子(即q值)
selectedMediaType = selectedMediaType.removeQualityValue();
// 遍历HttpMessageConverter，寻找第一个匹配的消息解析器处理body对象(待返回结果)
for (HttpMessageConverter<?> converter : this.messageConverters) {GenericHttpMessageConverter genericConverter = (converter instanceof GenericHttpMessageConverter ?(GenericHttpMessageConverter<?>) converter : null);// [标注1]if (genericConverter != null ?((GenericHttpMessageConverter) converter).canWrite(targetType, valueType, selectedMediaType) :converter.canWrite(valueType, selectedMediaType)) {body = getAdvice().beforeBodyWrite(body, returnType, selectedMediaType,(Class<? extends HttpMessageConverter<?>>) converter.getClass(),inputMessage, outputMessage);if (body != null) {Object theBody = body;// [标注2]addContentDispositionHeader(inputMessage, outputMessage);if (genericConverter != null) {genericConverter.write(body, targetType, selectedMediaType, outputMessage);} else {((HttpMessageConverter) converter).write(body, selectedMediaType, outputMessage);}}return;}
}
代码按照遍历+匹配+处理的思路铺开，逻辑比较清晰。有两个地方需要补充说明一下：
[1] 按照消息解析器是HttpMessageConverter还是GenericHttpMessageConverter，会使用不同的canWrite进行判断，后者多一个参数；write也有区别。
[2] addContentDispositionHeader用于为文件请求添加Content-Disposition头域，用于指示文件的名称和下载方式。取值范围有inline和attachment，inline表示文件直接浏览器中显示文本attachment表示文件下载到本地。
(5)异常场景处理
未匹配到消息处理器的场景，抛出异常。
----以上为所有内容----
