SpringMVC 6+源码分析(七)返回值处理
本文基于 Spring Framework 6.2.x(Spring Boot 3.4.x 所对应版本)源码编写,源码为开源项目 spring-projects/spring-framework(Apache 2.0 协议),文中引用均为学习目的的片段摘录,版权归原项目作者所有。
上一篇我们分析了 SpringMVC 的参数处理流程,Controller 方法的参数在 HandlerMethodArgumentResolver 的作用下解析完成,紧接着方法被反射调用,得到一个返回值。那么问题来了:这个返回值是怎么变成浏览器里的 JSON 数据,或者页面上的内容的?
本文我们接着往下看返回值的处理流程,也就是 HandlerMethodReturnValueHandler 体系。
一、概述
先回顾一下整体位置。在上一篇(五)执行流程里我们讲到,请求经过 DispatcherServlet#doDispatch() 分发,最终由 RequestMappingHandlerAdapter 调用我们写的 Controller 方法。方法内部的参数解析完成后,得到 returnValue,接下来就轮到返回值处理了。
用一张图标注出返回值处理在整个执行流程中的位置:

如果你读了这个专栏的前几篇,应该已经发现 SpringMVC 组件设计上有个很常见的套路:接口 + Composite 门面 + 一堆实现类,按注册顺序遍历,谁支持谁来。参数解析器 HandlerMethodArgumentResolver 是这么玩的(上一篇讲过),返回值处理器 HandlerMethodReturnValueHandler 同样是这个套路,甚至连类的命名都高度对称——一个叫 HandlerMethodArgumentResolverComposite,一个叫 HandlerMethodReturnValueHandlerComposite。
所以本文的分析方式和上一篇会有点像:先看接口体系和初始化,再看执行流程,最后逐个看几个有代表性的处理器。
二、返回值处理器体系
2.1 HandlerMethodReturnValueHandler 接口
接口位于 spring-web 模块的 org.springframework.web.method.support 包下,只有两个方法:
public interface HandlerMethodReturnValueHandler {
/**
* Whether the given {@linkplain MethodParameter method return type} is
* supported by this handler.
* @param returnType the method return type to check
* @return {@code true} if this handler supports the supplied return type;
* {@code false} otherwise
*/
boolean supportsReturnType(MethodParameter returnType);
/**
* Handle the given return value by adding attributes to the model and
* setting a view or setting the
* {@link ModelAndViewContainer#setRequestHandled} flag to {@code true}
* to indicate the response has been handled directly.
*/
void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception;
}
两个方法的分工和参数解析器一样:supportsReturnType 判断这个处理器支不支持当前返回值类型,handleReturnValue 做真正的处理。
注意 handleReturnValue 的 javadoc 里专门提到了 ModelAndViewContainer#setRequestHandled 这个标志位,它是理解返回值处理的一把钥匙:处理器把返回值处理完之后,要告诉容器这个请求是"我已经直接写响应了"(比如返回 JSON),还是"只是设置了视图,后面还要走视图渲染"。后面 3.2 节会看到它的具体作用。
2.2 Composite 门面:选择处理器
和参数解析一样,真正的调度由 HandlerMethodReturnValueHandlerComposite 完成:
public class HandlerMethodReturnValueHandlerComposite implements HandlerMethodReturnValueHandler {
private final List<HandlerMethodReturnValueHandler> returnValueHandlers = new ArrayList<>();
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
HandlerMethodReturnValueHandler handler = selectHandler(returnValue, returnType);
if (handler == null) {
throw new IllegalArgumentException("Unknown return value type: " + returnType.getParameterType().getName());
}
handler.handleReturnValue(returnValue, returnType, mavContainer, webRequest);
}
@Nullable
private HandlerMethodReturnValueHandler selectHandler(@Nullable Object value, MethodParameter returnType) {
boolean isAsyncValue = isAsyncReturnValue(value, returnType);
for (HandlerMethodReturnValueHandler handler : this.returnValueHandlers) {
if (isAsyncValue && !(handler instanceof AsyncHandlerMethodReturnValueHandler)) {
continue;
}
if (handler.supportsReturnType(returnType)) {
return handler;
}
}
return null;
}
private boolean isAsyncReturnValue(@Nullable Object value, MethodParameter returnType) {
for (HandlerMethodReturnValueHandler handler : this.returnValueHandlers) {
if (handler instanceof AsyncHandlerMethodReturnValueHandler asyncHandler &&
asyncHandler.isAsyncReturnValue(value, returnType)) {
return true;
}
}
return false;
}
public HandlerMethodReturnValueHandlerComposite addHandler(HandlerMethodReturnValueHandler handler) {
this.returnValueHandlers.add(handler);
return this;
}
public HandlerMethodReturnValueHandlerComposite addHandlers(
@Nullable List<? extends HandlerMethodReturnValueHandler> handlers) {
if (handlers != null) {
this.returnValueHandlers.addAll(handlers);
}
return this;
}
}
逻辑很好懂,两个点值得留意:
selectHandler是按注册顺序遍历,第一个调用supportsReturnType返回 true 的处理器胜出。所以注册顺序非常重要,谁排在前面谁优先级高,3.1 节的初始化顺序就是全部的优先级。- 如果返回值是异步类型(
Callable、DeferredResult等),isAsyncReturnValue会先判断出来,此时只有实现了AsyncHandlerMethodReturnValueHandler接口的处理器才有资格参与匹配,普通处理器直接跳过。
2.3 实现类一览
看一眼整体体系,一图胜千言:

再用表格整理一下 6.2.x 中各个实现类支持的返回值类型(顺序即注册顺序,优先级从高到低):
| 顺序 | 处理器 | 支持的返回值 | 处理效果 |
|---|---|---|---|
| 1 | ModelAndViewMethodReturnValueHandler | ModelAndView | 视图名 + 模型存入 mavContainer |
| 2 | ModelMethodProcessor | Model | 加入模型 |
| 3 | ViewMethodReturnValueHandler | View | 直接设置视图对象 |
| 4 | ResponseBodyEmitterReturnValueHandler | ResponseBodyEmitter、SseEmitter | SSE / 流式输出 |
| 5 | StreamingResponseBodyReturnValueHandler | StreamingResponseBody | 流式输出 |
| 6 | ResponseEntityReturnValueHandler(6.2 新增) | ResponseEntity | 委托给 HttpEntityMethodProcessor |
| 7 | HttpHeadersReturnValueHandler | HttpHeaders | 只写响应头 |
| 8 | CallableMethodReturnValueHandler | Callable | 异步处理 |
| 9 | DeferredResultMethodReturnValueHandler | DeferredResult | 异步处理 |
| 10 | AsyncTaskMethodReturnValueHandler | Future / CompletionStage | 异步处理 |
| 11 | ServletModelAttributeMethodProcessor(false) | 带 @ModelAttribute 注解 | 加入模型 |
| 12 | RequestResponseBodyMethodProcessor | 类或方法带 @ResponseBody | 直接写响应体(JSON 主角) |
| 13 | ViewNameMethodReturnValueHandler | String/CharSequence、void | 视图名存入 mavContainer |
| 14 | MapMethodProcessor | Map | 加入模型 |
| 15 | 自定义处理器 | 自定义 | 自定义 |
| 16 | ServletModelAttributeMethodProcessor(true) | 兜底:任意非简单类型 | 当作模型属性 |
这里有个容易踩坑的点先标出来:同一个返回类型,在不同注解环境下会走完全不同的处理器。最典型的是 Map 和 String——在 @RestController 里返回 Map 走的是 12 号 RequestResponseBodyMethodProcessor(JSON),在普通 @Controller 里返回 Map 走的是 14 号 MapMethodProcessor(模型属性)。原因就是 12 号排在 14 号前面,@ResponseBody 的判断条件先满足。第四节 Demo 里会实际验证。
三、返回值的解析过程
3.1 处理器的初始化
回顾完体系,接下来看这些处理器是什么时候装进 Composite 的。
上一篇(四)讲过,RequestMappingHandlerAdapter 实现了 InitializingBean,容器启动时会回调 afterPropertiesSet()。返回值处理器的初始化就在这里:
@Override
public void afterPropertiesSet() {
// Do this first, it may add ResponseBody advice beans
// 先初始化 @ControllerAdvice,其中会收集 ResponseBodyAdvice
initControllerAdviceCache();
initMessageConverters();
if (this.argumentResolvers == null) {
List<HandlerMethodArgumentResolver> resolvers = getDefaultArgumentResolvers();
this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
}
if (this.initBinderArgumentResolvers == null) {
List<HandlerMethodArgumentResolver> resolvers = getDefaultInitBinderArgumentResolvers();
this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
}
if (this.returnValueHandlers == null) {
List<HandlerMethodReturnValueHandler> handlers = getDefaultReturnValueHandlers();
this.returnValueHandlers = new HandlerMethodReturnValueHandlerComposite().addHandlers(handlers);
}
// ... 参数校验相关,略
}
三个关键动作都在这一步完成:收集 @ControllerAdvice(ResponseBodyAdvice 就在这里被缓存进 requestResponseBodyAdvice)、初始化消息转换器、组装返回值处理器链。如果我们在配置里没有显式指定 setReturnValueHandlers,就会走 getDefaultReturnValueHandlers():
private List<HandlerMethodReturnValueHandler> getDefaultReturnValueHandlers() {
List<HandlerMethodReturnValueHandler> handlers = new ArrayList<>(20);
ResponseBodyEmitterReturnValueHandler responseBodyEmitterHandler =
new ResponseBodyEmitterReturnValueHandler(getMessageConverters(),
this.reactiveAdapterRegistry, this.taskExecutor, this.contentNegotiationManager,
initViewResolvers(), initLocaleResolver());
HttpEntityMethodProcessor httpEntityMethodProcessor = new HttpEntityMethodProcessor(getMessageConverters(),
this.contentNegotiationManager, this.requestResponseBodyAdvice, this.errorResponseInterceptors);
// Single-purpose return value types
// 第一组:单一用途的返回值类型
handlers.add(new ModelAndViewMethodReturnValueHandler());
handlers.add(new ModelMethodProcessor());
handlers.add(new ViewMethodReturnValueHandler());
handlers.add(responseBodyEmitterHandler);
handlers.add(new StreamingResponseBodyReturnValueHandler());
handlers.add(new ResponseEntityReturnValueHandler(httpEntityMethodProcessor, responseBodyEmitterHandler));
handlers.add(new HttpHeadersReturnValueHandler());
handlers.add(new CallableMethodReturnValueHandler());
handlers.add(new DeferredResultMethodReturnValueHandler());
handlers.add(new AsyncTaskMethodReturnValueHandler(this.beanFactory));
// Annotation-based return value types
// 第二组:基于注解的返回值类型
handlers.add(new ServletModelAttributeMethodProcessor(false));
handlers.add(new RequestResponseBodyMethodProcessor(getMessageConverters(),
this.contentNegotiationManager, this.requestResponseBodyAdvice, this.errorResponseInterceptors));
// Multi-purpose return value types
// 第三组:多用途的返回值类型
handlers.add(new ViewNameMethodReturnValueHandler());
handlers.add(new MapMethodProcessor());
// Custom return value types
// 第四组:我们自定义的处理器,插在兜底处理器之前
if (getCustomReturnValueHandlers() != null) {
handlers.addAll(getCustomReturnValueHandlers());
}
// Catch-all
// 兜底:任意非简单类型当作模型属性
if (!CollectionUtils.isEmpty(getModelAndViewResolvers())) {
handlers.add(new ModelAndViewResolverMethodReturnValueHandler(getModelAndViewResolvers()));
}
else {
handlers.add(new ServletModelAttributeMethodProcessor(true));
}
return handlers;
}
注意两点:
- 每个"重量级"处理器在构造时都拿到了同一批组件:
messageConverters(消息转换器)、contentNegotiationManager(内容协商)、requestResponseBodyAdvice(@ControllerAdvice里的增强)。后面 3.3.1 会看到它们如何配合。 - 自定义处理器的插入位置:在内置处理器之后、兜底处理器之前。所以自定义处理器能接管的,是内置处理器都不支持的类型。这里对应
WebMvcConfigurer#addReturnValueHandlers()的回调,后面 3.4 节用 demo 验证。
3.2 执行流程
初始化好的处理器链,会在每次请求时通过 ServletInvocableHandlerMethod 被使用。回顾(五)执行流程里贴过的调用链:doDispatch() → ha.handle() → invokeHandlerMethod() → invokeAndHandle(),直接看最后一环的源码:
public void invokeAndHandle(ServletWebRequest webRequest, ModelAndViewContainer mavContainer,
Object... providedArgs) throws Exception {
// 参数解析(上一篇) + 反射调用方法,拿到返回值
Object returnValue = invokeForRequest(webRequest, mavContainer, providedArgs);
// 处理方法上的 @ResponseStatus 注解
setResponseStatus(webRequest);
if (returnValue == null) {
if (isRequestNotModified(webRequest) || getResponseStatus() != null || mavContainer.isRequestHandled()) {
disableContentCachingIfNecessary(webRequest);
mavContainer.setRequestHandled(true);
return;
}
}
else if (StringUtils.hasText(getResponseStatusReason())) {
mavContainer.setRequestHandled(true);
return;
}
mavContainer.setRequestHandled(false);
Assert.state(this.returnValueHandlers != null, "No return value handlers");
try {
this.returnValueHandlers.handleReturnValue(
returnValue, getReturnValueType(returnValue), mavContainer, webRequest);
}
catch (Exception ex) {
if (logger.isTraceEnabled()) {
logger.trace(formatErrorForReturnValue(returnValue), ex);
}
throw ex;
}
}
几个分支解读一下:
- 返回值为 null 的三种情况(304 Not Modified、方法上标了
@ResponseStatus、参数解析阶段已经有人把请求处理完了)直接标记requestHandled = true结束���不再走处理器链。 - 正常情况下先把
requestHandled重置为 false,然后交给 Composite 去选择处理器——最终是谁把标志位置为 true,取决于选中的处理器自己。
完整的调用过程用时序图表示(以最常用的 @ResponseBody 场景为例):

3.3 不同返回值处理器的处理过程
3.3.1 RequestResponseBodyMethodProcessor:@ResponseBody 的主流程
这是日常开发中 90% 场景的处理器,先看它是怎么匹配的:
@Override
public boolean supportsReturnType(MethodParameter returnType) {
return (AnnotatedElementUtils.hasAnnotation(returnType.getContainingClass(), ResponseBody.class) ||
returnType.hasMethodAnnotation(ResponseBody.class));
}
判断条件就一个:类上或者方法上有没有 @ResponseBody 注解。AnnotatedElementUtils.hasAnnotation 支持查找元注解,所以 @RestController(它本身组合了 @Controller + @ResponseBody)标注的类,所有方法都会命中这个处理器。
再看到处理逻辑:
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest)
throws IOException, HttpMediaTypeNotAcceptableException, HttpMessageNotWritableException {
// 标记请求已处理,后面不会再走视图渲染
mavContainer.setRequestHandled(true);
ServletServerHttpRequest inputMessage = createInputMessage(webRequest);
ServletServerHttpResponse outputMessage = createOutputMessage(webRequest);
// 6.x 对 RFC 9457 错误响应的支持,返回 ProblemDetail 时自动设置状态码
if (returnValue instanceof ProblemDetail detail) {
outputMessage.setStatusCode(HttpStatusCode.valueOf(detail.getStatus()));
if (detail.getInstance() == null) {
URI path = URI.create(inputMessage.getServletRequest().getRequestURI());
detail.setInstance(path);
}
invokeErrorResponseInterceptors(detail, null);
}
// Try even with null return value. ResponseBodyAdvice could get involved.
// 即使返回值是 null 也要继续走,因为 ResponseBodyAdvice 可能参与进来
writeWithMessageConverters(returnValue, returnType, inputMessage, outputMessage);
}
第一行 setRequestHandled(true) 直接拍板:这个请求我来处理完,没有视图渲染的事了。真正的写出动作在父类 AbstractMessageConverterMethodProcessor#writeWithMessageConverters() 里,这个方法比较长,我们挑主干看。
第一步,MediaType 协商——决定响应到底是 JSON 还是 XML 还是别的:
MediaType selectedMediaType = null;
MediaType contentType = outputMessage.getHeaders().getContentType();
// 如果响应头里已经预设了具体的 Content-Type,直接用
boolean isContentTypePreset = contentType != null && contentType.isConcrete();
if (isContentTypePreset) {
selectedMediaType = contentType;
}
else {
HttpServletRequest request = inputMessage.getServletRequest();
// acceptableTypes:从请求的 Accept 头解析,浏览器能接受什么
List<MediaType> acceptableTypes;
try {
acceptableTypes = getAcceptableMediaTypes(request);
}
catch (HttpMediaTypeNotAcceptableException ex) {
// ... 错误响应场景的处理,略
}
// producibleTypes:转换器们能写什么(含 @RequestMapping 的 produces 属性)
List<MediaType> producibleTypes = getProducibleMediaTypes(request, valueType, targetType);
if (body != null && producibleTypes.isEmpty()) {
throw new HttpMessageNotWritableException(
"No converter found for return value of type: " + valueType);
}
// 求交集
List<MediaType> compatibleMediaTypes = determineCompatibleMediaTypes(acceptableTypes, producibleTypes);
// ... ProblemDetail 的兜底协商,略
if (compatibleMediaTypes.isEmpty()) {
if (body != null) {
throw new HttpMediaTypeNotAcceptableException(producibleTypes);
}
return;
}
// 按具体程度排序,选第一个具体的类型(如 application/json 而不是 application/*)
MimeTypeUtils.sortBySpecificity(compatibleMediaTypes);
for (MediaType mediaType : compatibleMediaTypes) {
if (mediaType.isConcrete()) {
selectedMediaType = mediaType;
break;
}
else if (mediaType.isPresentIn(ALL_APPLICATION_MEDIA_TYPES)) {
selectedMediaType = MediaType.APPLICATION_OCTET_STREAM;
break;
}
}
// ...
}
协商的思路一句话概括:浏览器想要的(Accept)∩ 系统能给的(转换器支持 + produces)= 实际响应的 Content-Type。
第二步,遍历消息转换器,选一个能写这个类型的:
if (selectedMediaType != null) {
selectedMediaType = selectedMediaType.removeQualityValue();
ResolvableType targetResolvableType = null;
for (HttpMessageConverter converter : this.messageConverters) {
ConverterType converterTypeToUse = null;
if (converter instanceof GenericHttpMessageConverter genericConverter) {
if (genericConverter.canWrite(targetType, valueType, selectedMediaType)) {
converterTypeToUse = ConverterType.GENERIC;
}
}
else if (converter instanceof SmartHttpMessageConverter smartConverter) {
targetResolvableType = getNestedTypeIfNeeded(ResolvableType.forMethodParameter(returnType));
if (smartConverter.canWrite(targetResolvableType, valueType, selectedMediaType)) {
converterTypeToUse = ConverterType.SMART;
}
}
else if (converter.canWrite(valueType, selectedMediaType)){
converterTypeToUse = ConverterType.BASE;
}
// 选中了能处理的转换器
if (converterTypeToUse != null) {
// 先走 ResponseBodyAdvice 的增强链
body = getAdvice().beforeBodyWrite(body, returnType, selectedMediaType,
(Class<? extends HttpMessageConverter<?>>) converter.getClass(), inputMessage, outputMessage);
if (body != null) {
Object theBody = body;
LogFormatUtils.traceDebug(logger, traceOn ->
"Writing [" + LogFormatUtils.formatValue(theBody, !traceOn) + "]");
addContentDispositionHeader(inputMessage, outputMessage);
switch (converterTypeToUse) {
case BASE -> converter.write(body, selectedMediaType, outputMessage);
case GENERIC -> ((GenericHttpMessageConverter) converter).write(body, targetType, selectedMediaType, outputMessage);
case SMART -> ((SmartHttpMessageConverter) converter).write(body, targetResolvableType, selectedMediaType, outputMessage, null);
}
}
else {
if (logger.isDebugEnabled()) {
logger.debug("Nothing to write: null body");
}
}
return;
}
}
}
这段是返回 JSON 的核心,串起来讲:
- SpringBoot 环境下默认的转换器里,返回
User对象时,MappingJackson2HttpMessageConverter的canWrite会命中(它支持application/json),于是整个对象被 Jackson 序列化后写到响应体; - 写出前有一道**
ResponseBodyAdvice#beforeBodyWrite()的增强链**——这是@ControllerAdvice体系里专门针对响应体的扩展点,我们常用的"统一响应结构包装"就是在这里做的。注意它的位置:在转换器写出之前,所以 advice 里改过的对象才是最终写出去的内容; - 如果遍历完没有任何转换器能处理(比如
Accept头要求 XML 但依赖里没加 jackson-dataformat-xml),最后会抛HttpMediaTypeNotAcceptableException,也就是常说的 406。
3.3.2 ViewNameMethodReturnValueHandler:String 与 void
普通 @Controller 里返回 String,走的不是 JSON 而是视图名。看这个处理器的源码:
public class ViewNameMethodReturnValueHandler implements HandlerMethodReturnValueHandler {
@Override
public boolean supportsReturnType(MethodParameter returnType) {
Class<?> paramType = returnType.getParameterType();
// 6.x 起也支持 void,返回 null 时不做任何事
return (void.class == paramType || CharSequence.class.isAssignableFrom(paramType));
}
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
if (returnValue instanceof CharSequence) {
String viewName = returnValue.toString();
// 视图名存入 mavContainer,等 doDispatch 后半段的 render() 去渲染
mavContainer.setViewName(viewName);
if (isRedirectViewName(viewName)) {
mavContainer.setRedirectModelScenario(true);
}
}
else if (returnValue != null) {
// should not happen
throw new UnsupportedOperationException("Unexpected return type: " +
returnType.getParameterType().getName() + " in method: " + returnType.getMethod());
}
}
protected boolean isRedirectViewName(String viewName) {
return (PatternMatchUtils.simpleMatch(this.redirectPatterns, viewName) || viewName.startsWith("redirect:"));
}
}
和 3.3.1 对比一下就非常清晰了:这里没有 setRequestHandled(true),只是把视图名放进 mavContainer。请求没有被"处理完",doDispatch() 后半段的 processDispatchResult() → render() 还会拿着这个视图名去渲染页面——这是返回值处理两条路线的分水岭:直接写响应(JSON)vs 交给视图渲染(页面)。
另外 "redirect:" 前缀也在这里识别,标记为重定向场景,后面的 RedirectView 会据此拼装重定向响应。
3.3.3 ModelAndViewMethodReturnValueHandler:ModelAndView
返回 ModelAndView 的处理最直观,视图和模型一起带走:
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
if (returnValue == null) {
mavContainer.setRequestHandled(true);
return;
}
if (returnValue instanceof Collection<?> mavs) {
returnValue = FragmentsRendering.fragments((Collection<ModelAndView>) mavs).build();
}
if (returnValue instanceof FragmentsRendering rendering) {
mavContainer.setView(rendering);
return;
}
ModelAndView mav = (ModelAndView) returnValue;
if (mav.isReference()) {
// 逻辑视图名
String viewName = mav.getViewName();
mavContainer.setViewName(viewName);
if (viewName != null && isRedirectViewName(viewName)) {
mavContainer.setRedirectModelScenario(true);
}
}
else {
// 直接持有 View 对象
View view = mav.getView();
mavContainer.setView(view);
if (view instanceof SmartView smartView && smartView.isRedirectView()) {
mavContainer.setRedirectModelScenario(true);
}
}
mavContainer.setStatus(mav.getStatus());
mavContainer.addAllAttributes(mav.getModel());
}
逻辑视图名和 View 对象分别对应 setViewName / setView,模型属性用 addAllAttributes 全部搬进 mavContainer。6.2 里还多了对 FragmentsRendering(片段渲染)的支持,属于新特性,这里不展开。
3.3.4 HttpEntityMethodProcessor:ResponseEntity
返回 ResponseEntity 的场景,特点是状态码、响应头、响应体三样都由返回值自己决定。不过要注意,6.2 开始注册顺序上先遇到的是 ResponseEntityReturnValueHandler,它是一层包装(委托类):
public class ResponseEntityReturnValueHandler implements HandlerMethodReturnValueHandler {
@Override
public boolean supportsReturnType(MethodParameter returnType) {
return this.httpEntityMethodProcessor.supportsReturnType(returnType);
}
@Override
public void handleReturnValue(
@Nullable Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer,
NativeWebRequest request) throws Exception {
if (returnValue instanceof HttpEntity<?> httpEntity) {
Object body = httpEntity.getBody();
if (body != null) {
// body 是流式类型(ResponseBodyEmitter 等)时交给流式处理器
if (this.responseBodyEmitterHandler.supportsBodyType(body.getClass())) {
this.responseBodyEmitterHandler.handleReturnValue(returnValue, returnType, mavContainer, request);
return;
}
}
}
// 普通情况委托给 HttpEntityMethodProcessor
this.httpEntityMethodProcessor.handleReturnValue(returnValue, returnType, mavContainer, request);
}
}
它先看一眼 body 是不是流式类型,是就交给流式处理器,否则委托给 HttpEntityMethodProcessor。核心处理在后者:
@Override
public void handleReturnValue(@Nullable Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
// 同样拍板:直接写响应
mavContainer.setRequestHandled(true);
if (returnValue == null) {
return;
}
ServletServerHttpRequest inputMessage = createInputMessage(webRequest);
ServletServerHttpResponse outputMessage = createOutputMessage(webRequest);
// ErrorResponse / ProblemDetail 统一包装成 ResponseEntity
HttpEntity<?> httpEntity;
if (returnValue instanceof ErrorResponse response) {
httpEntity = new ResponseEntity<>(response.getBody(), response.getHeaders(), response.getStatusCode());
}
else if (returnValue instanceof ProblemDetail detail) {
httpEntity = ResponseEntity.of(detail).build();
}
else {
Assert.isInstanceOf(HttpEntity.class, returnValue);
httpEntity = (HttpEntity<?>) returnValue;
}
// 把 entity 里的响应头搬到 Servlet 响应(VARY 头有去重逻辑,略)
HttpHeaders outputHeaders = outputMessage.getHeaders();
HttpHeaders entityHeaders = httpEntity.getHeaders();
if (!entityHeaders.isEmpty()) {
entityHeaders.forEach((key, value) -> {
if (HttpHeaders.VARY.equals(key) && outputHeaders.containsKey(HttpHeaders.VARY)) {
// ...
}
else {
outputHeaders.put(key, value);
}
});
}
if (httpEntity instanceof ResponseEntity<?> responseEntity) {
// 状态码由返回值决定
HttpStatusCode returnStatus = responseEntity.getStatusCode();
outputMessage.getServletResponse().setStatus(returnStatus.value());
// GET/HEAD + 304 的缓存协商场景,直接 flush 返回
if (returnStatus.value() == HttpStatus.OK.value()) {
HttpMethod method = inputMessage.getMethod();
if ((HttpMethod.GET.equals(method) || HttpMethod.HEAD.equals(method)) &&
isResourceNotModified(inputMessage, outputMessage)) {
outputMessage.flush();
return;
}
}
else if (returnStatus.is3xxRedirection()) {
// 3xx 时保存 FlashAttributes,供重定向后的请求使用
String location = outputHeaders.getFirst(HttpHeaders.LOCATION);
if (location != null) {
saveFlashAttributes(mavContainer, webRequest, location);
}
}
}
// body 依旧走消息转换写出,和 3.3.1 的后半段是同一段代码
writeWithMessageConverters(httpEntity.getBody(), returnType, inputMessage, outputMessage);
// Ensure headers are flushed even if no body was written.
outputMessage.flush();
}
可以看到 writeWithMessageConverters() 是复用的——@ResponseBody 和 ResponseEntity 的响应体写出,最终殊途同归到同一段消息转换逻辑,差别只是 ResponseEntity 多了状态码和响应头的处理。
3.4 自定义返回值处理器
体系讲完,看一个实战场景:框架自带的处理器都不支持我们的自定义类型时,怎么扩展。
先定义一个自定义返回值类型 CustomResult:
/**
* 自定义返回值类型:只要方法返回这个类型,
* 就会被 CustomResultReturnValueHandler 接管
*/
public record CustomResult(String type, Object payload) {
public static CustomResult of(String type, Object payload) {
return new CustomResult(type, payload);
}
}
然后实现 HandlerMethodReturnValueHandler 接口:
public class CustomResultReturnValueHandler implements HandlerMethodReturnValueHandler {
private static final ObjectMapper MAPPER = new ObjectMapper();
@Override
public boolean supportsReturnType(MethodParameter returnType) {
return CustomResult.class.isAssignableFrom(returnType.getParameterType());
}
@Override
public void handleReturnValue(Object returnValue, MethodParameter returnType,
ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
// 响应体由我们自己写,标记请求已处理,避免再走视图渲染
mavContainer.setRequestHandled(true);
CustomResult result = (CustomResult) returnValue;
Map<String, Object> body = new LinkedHashMap<>();
body.put("type", result.type());
body.put("payload", result.payload());
HttpServletResponse response = webRequest.getNativeResponse(HttpServletResponse.class);
response.setContentType("application/json;charset=UTF-8");
MAPPER.writeValue(response.getWriter(), body);
}
}
最后通过 WebMvcConfigurer 注册(回顾 3.1 节,会插在兜底处理器之前):
@Configuration
public class CustomWebConfig implements WebMvcConfigurer {
@Override
public void addReturnValueHandlers(List<HandlerMethodReturnValueHandler> handlers) {
handlers.add(new CustomResultReturnValueHandler());
}
}
有一个细节要注意:Controller 类上不要标 @RestController。因为类上有了 @ResponseBody 之后,12 号 RequestResponseBodyMethodProcessor 会先匹配成功,自定义处理器根本轮不到——再次印证 3.1 节说的"注册顺序就是优先级"。
四、Demo 实战验证
以上所有场景整理成一个可运行的 SpringBoot 3.4.5 工程(文末有完整代码地址),Controller 关键代码如下:
@RestController
@RequestMapping("/user")
public class UserRestController {
@GetMapping("/pojo")
public User pojo() {
return new User(1L, "陈皮", "chenpi@example.com");
}
@GetMapping("/entity")
public ResponseEntity<User> entity() {
User user = new User(1L, "陈皮", "chenpi@example.com");
HttpHeaders headers = new HttpHeaders();
headers.add("X-Source", "returnvalue-demo");
return new ResponseEntity<>(user, headers, HttpStatus.CREATED);
}
@GetMapping("/wrapped")
@ResponseBody // 方法级别注解,配合 @ControllerAdvice 的 ResponseBodyAdvice 演示
public User wrapped() {
return new User(1L, "陈皮", "chenpi@example.com");
}
}
@Controller
public class ViewController {
@GetMapping("/page")
public String page() {
return "home"; // 视图名
}
@GetMapping("/model")
public Map<String, Object> model() {
return Map.of("name", "陈皮"); // 注意:普通 @Controller 里返回 Map 是模型属性,不是 JSON!
}
}
其中 EnvelopeResponseBodyAdvice 是一个 @ControllerAdvice + ResponseBodyAdvice 的演示,只拦截方法上显式标注 @ResponseBody 的方法,做统一包装:
@ControllerAdvice
public class EnvelopeResponseBodyAdvice implements ResponseBodyAdvice<Object> {
@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
return returnType.hasMethodAnnotation(ResponseBody.class);
}
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> selectedConverterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body == null || body instanceof String) {
return body;
}
Map<String, Object> envelope = new LinkedHashMap<>();
envelope.put("code", 0);
envelope.put("msg", "ok");
envelope.put("data", body);
return envelope;
}
}
启动后逐个请求验证,结果与源码分析完全对应:
| 请求 | 返回值类型 | 选中的处理器 | 实际响应 |
|---|---|---|---|
| GET /user/pojo | User | RequestResponseBodyMethodProcessor | {"id":1,"name":"陈皮","email":"chenpi@example.com"} |
| GET /user/list | List<User> | 同上 | JSON 数组 |
| GET /user/entity | ResponseEntity<User> | ResponseEntityReturnValueHandler → HttpEntityMethodProcessor | 201 状态码 + X-Source 响应头 |
| GET /user/wrapped | User(方法级 @ResponseBody) | 同 /pojo,额外经过 ResponseBodyAdvice | {"code":0,"msg":"ok","data":{...}} |
| GET /page | String | ViewNameMethodReturnValueHandler | 视图名为 home,走视图渲染 |
| GET /redirect | String | 同上,识别 redirect: 前缀 | 302 重定向 |
| GET /mav | ModelAndView | ModelAndViewMethodReturnValueHandler | 视图 + 模型 |
| GET /model | Map | MapMethodProcessor | 加入模型,不是 JSON |
| GET /custom | CustomResult | 自定义的 CustomResultReturnValueHandler | {"type":"report","payload":{"no":"R-2025","title":"季度数据报表"}} |
最后用一张图把本文的知识点归纳一下:

五、总结
返回值处理由 HandlerMethodReturnValueHandlerComposite 作为门面,按注册顺序选择第一个支持的 HandlerMethodReturnValueHandler:@ResponseBody/ResponseEntity 走消息转换器直接写响应体(setRequestHandled(true)),String/ModelAndView/Map 等只是往 mavContainer 里塞视图和模型,交给后续的视图渲染流程。
下一篇我们分析 doDispatch() 中排在这个流程之前的另一个组件——拦截器 HandlerInterceptor,看看 preHandle、postHandle、afterCompletion 三个方法分别在什么时机被调用。
Demo 完整代码:SpringMVC/07-返回值处理/returnvalue-demo(SpringBoot 3.4.5 + JDK 17,mvn spring-boot:run 启动后按上表逐个请求验证)
专栏往期:
- SpringMVC 6+源码分析(一)初始化流程
- SpringMVC 6+源码分析(二)DispatcherServlet实例化流程 1
- SpringMVC 6+源码分析(三)DispatcherServlet实例化流程 2
- SpringMVC 6+源码分析(四)DispatcherServlet实例化流程 3——HandlerAdapter初始化
- SpringMVC 6+源码分析(五)执行流程
- SpringMVC 6+源码分析(六)参数处理
本文为「源码学习」专栏系列文章,转载请注明出处。相互学习,共同进步!
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/qq_31366767/article/details/170760494



