SpringMVC系列-5 消息转换器
背景
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> {
@Override
public boolean canWrite(Class clazz, MediaType mediaType) {
return clazz == UserInfo.class;
}
@Override
public List<MediaType> getSupportedMediaTypes() {
return Collections.singletonList(MediaType.APPLICATION_JSON);
}
@Override
public 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 {
@Override
public 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）的转换。
ByteArrayHttpMessageConverter
application/octet-stream
*/*
StringHttpMessageConverter：用于处理字符串的转换。
StringHttpMessageConverter
text/plain
*/*
StringHttpMessageConverter
text/plain
*/*
ResourceHttpMessageConverter：用于处理Spring Resource的实现类的转换。Spring Resource是一个抽象类，它封装了对各种资源（如文件、数据库连接等）的操作。
ResourceHttpMessageConverter
*/*
ResourceRegionHttpMessageConverter：这个类是ResourceHttpMessageConverter的子类，它用于处理Resource的某个特定区域（如文件的某个部分）。
ResourceRegionHttpMessageConverter
*/*
SourceHttpMessageConverter：用于处理javax.xml.transform.Source的转换。javax.xml.transform.Source是用于XML转换的接口。
SourceHttpMessageConverter
application/xml
text/xml
application/*+xml
AllEncompassingFormHttpMessageConverter：用于处理表单提交请求，能解析复杂的form表单，包括文件上传等。
AllEncompassingFormHttpMessageConverter
application/x-www-form-urlencoded
multipart/form-data
multipart/mixed
MappingJackson2HttpMessageConverter：用于处理JSON序列化和反序列化。
MappingJackson2HttpMessageConverter
application/json
application/*+json
MappingJackson2HttpMessageConverter
application/json
application/*+json
Jaxb2RootElementHttpMessageConverter：这个类使用JAXB（Java Architecture for XML Binding）进行XML序列化和反序列化。
Jaxb2RootElementHttpMessageConverter
application/xml
text/xml
application/*+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/json
addDefaultHeaders(headers, t, contentType);
if (outputMessage instanceof StreamingHttpOutputMessage) {
StreamingHttpOutputMessage streamingOutputMessage = (StreamingHttpOutputMessage) outputMessage;
streamingOutputMessage.setBody(outputStream -> writeInternal(t, type, new HttpOutputMessage() {
@Override
public OutputStream getBody() {
return outputStream;
}
@Override
public 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列表；因此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
(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)异常场景处理
未匹配到消息处理器的场景，抛出异常。
----以上为所有内容----