Resean0223头像

SpringMVC 6+源码分析(七)返回值处理

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,接下来就轮到返回值处理了。

用一张图标注出返回值处理在整个执行流程中的位置:

返回值处理在 doDispatch 中的位置

如果你读了这个专栏的前几篇,应该已经发现 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 中各个实现类支持的返回值类型(顺序即注册顺序,优先级从高到低):

顺序处理器支持的返回值处理效果
1ModelAndViewMethodReturnValueHandlerModelAndView视图名 + 模型存入 mavContainer
2ModelMethodProcessorModel加入模型
3ViewMethodReturnValueHandlerView直接设置视图对象
4ResponseBodyEmitterReturnValueHandlerResponseBodyEmitter、SseEmitterSSE / 流式输出
5StreamingResponseBodyReturnValueHandlerStreamingResponseBody流式输出
6ResponseEntityReturnValueHandler(6.2 新增)ResponseEntity委托给 HttpEntityMethodProcessor
7HttpHeadersReturnValueHandlerHttpHeaders只写响应头
8CallableMethodReturnValueHandlerCallable异步处理
9DeferredResultMethodReturnValueHandlerDeferredResult异步处理
10AsyncTaskMethodReturnValueHandlerFuture / CompletionStage异步处理
11ServletModelAttributeMethodProcessor(false)带 @ModelAttribute 注解加入模型
12RequestResponseBodyMethodProcessor类或方法带 @ResponseBody直接写响应体(JSON 主角)
13ViewNameMethodReturnValueHandlerString/CharSequence、void视图名存入 mavContainer
14MapMethodProcessorMap加入模型
15自定义处理器自定义自定义
16ServletModelAttributeMethodProcessor(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;
	}

注意两点:

  1. 每个"重量级"处理器在构造时都拿到了同一批组件:messageConverters(消息转换器)、contentNegotiationManager(内容协商)、requestResponseBodyAdvice(@ControllerAdvice 里的增强)。后面 3.3.1 会看到它们如何配合。
  2. 自定义处理器的插入位置:在内置处理器之后、兜底处理器之前。所以自定义处理器能接管的,是内置处理器都不支持的类型。这里对应 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 场景为例):

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/pojoUserRequestResponseBodyMethodProcessor{"id":1,"name":"陈皮","email":"chenpi@example.com"}
GET /user/listList<User>同上JSON 数组
GET /user/entityResponseEntity<User>ResponseEntityReturnValueHandler → HttpEntityMethodProcessor201 状态码 + X-Source 响应头
GET /user/wrappedUser(方法级 @ResponseBody)同 /pojo,额外经过 ResponseBodyAdvice{"code":0,"msg":"ok","data":{...}}
GET /pageStringViewNameMethodReturnValueHandler视图名为 home,走视图渲染
GET /redirectString同上,识别 redirect: 前缀302 重定向
GET /mavModelAndViewModelAndViewMethodReturnValueHandler视图 + 模型
GET /modelMapMapMethodProcessor加入模型,不是 JSON
GET /customCustomResult自定义的 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 启动后按上表逐个请求验证)

专栏往期:

本文为「源码学习」专栏系列文章,转载请注明出处。相互学习,共同进步!

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/qq_31366767/article/details/170760494

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--