内容总览
一、起源
1.1 Servlet 直接处理请求时的四类重复劳动
在 HttpServlet 中手写接口时,每个接口都要重复以下工作:
| 重复劳动 | 具体内容 | 重复的原因 |
|---|---|---|
| 参数获取与转换 | 从 getParameter 取字符串、手工做类型转换与校验、拼装对象 | 容器只提供字符串到字符串的映射 |
| 响应序列化 | 设置内容类型与编码、把对象转成 JSON、处理空值 | 容器只提供输出流 |
| 路由分派 | 根据路径与方法判断该执行哪段逻辑 | 容器只提供 URL 到 Servlet 的映射,粒度是类而非方法 |
| 异常处理与视图选择 | 捕获异常转成状态码、决定渲染方式 | 容器层只有 error-page,粒度是状态码 |
四类劳动的共同特点是:与具体业务无关,但每个接口都要写一遍,且各人写法不一致。
1.2 前端控制器模式的解法
Spring MVC 把这些步骤收敛成两类可替换组件,由唯一入口按固定顺序调度:
- 策略组件:负责"怎么做"(如何匹配处理器、如何解析参数、如何序列化、如何解析视图、如何处理异常)。
- 处理器:开发者编写的 Controller 方法,只保留业务逻辑。
代价是链路变长:一次请求要经过多个组件的查找与委托,出问题时调用栈深、组件多,需要明确每一步由谁负责。
1.3 取舍
- 抽象提升换来了可扩展性,但使"哪一步出错"不再直观,排障必须依赖链路日志与组件名。
- 同一能力存在多个实现(多种参数解析器、多种消息转换器、两套路径匹配器),选择由注册顺序与条件决定,配置错误的表现为"看起来配置了但没生效"。
- 异步与响应式模型引入后,链路的执行时机被拆分到不同线程,上下文传递成为必须显式处理的问题。
二、原理
2.1 DispatcherServlet 的初始化与默认策略组件
DispatcherServlet 是前端控制器,既是 Servlet 也是策略组件的持有者。容器调用其 initStrategies 时,对九类组件逐一查找:先找容器中同类型的 Bean,找不到再退回默认实现。
| 组件 | 职责 | 默认实现来源 |
|---|---|---|
HandlerMapping | 请求到处理器及其拦截器链的映射 | RequestMappingHandlerMapping 等 |
HandlerAdapter | 按处理器类型调用它 | RequestMappingHandlerAdapter 等 |
HandlerExceptionResolver | 异常到响应或视图的解析 | 组合解析器 |
ViewResolver | 逻辑视图名到视图实现的解析 | 视图解析器链 |
RequestToViewNameTranslator | 未返回视图名时按请求推导视图名 | 默认实现 |
LocaleResolver | 本次请求的区域设置 | 请求头解析 |
ThemeResolver | 主题解析 | 默认实现 |
MultipartResolver | 文件上传请求的解析 | 需显式配置才存在 |
FlashMapManager | 重定向间的临时数据传递 | 基于 Session |
要点:MultipartResolver 只有在配置后才会被注册,未配置时 MultipartFile 参数无法注入,这是文件上传接口不生效的常见原因。
2.2 一次请求的完整链路
客户端请求
|
v
Filter 链(Servlet 容器层,可改写 request/response)
|
v
DispatcherServlet.doDispatch
|
+-- 1. getHandler(request) 查找 HandlerExecutionChain(处理器 + 拦截器链)
| 未找到 -> 404,交由容器处理
|
+-- 2. getHandlerAdapter(handler) 按处理器类型选择适配器
| 未找到 -> 抛异常
|
+-- 3. 顺序执行拦截器 preHandle
| 返回 false -> 中断,直接返回(postHandle 与 afterCompletion 不再执行)
|
+-- 4. 适配器调用处理器方法
| a. 解析方法参数(HandlerMethodArgumentResolver 链)
| b. 反射调用 Controller 方法
| c. 处理返回值(HandlerMethodReturnValueHandler 链)
| 含 @ResponseBody -> HttpMessageConverter 写到响应体
| 返回视图名 -> 交给 ViewResolver
|
+-- 5. 逆序执行拦截器 postHandle
|
+-- 6. 解析视图并渲染(前后端分离下不经过此步)
|
+-- 7. 逆序执行拦截器 afterCompletion(无论成功或异常都会执行)
|
+-- 8. 异常路径:任一步抛异常 -> HandlerExceptionResolver 解析
|
v
响应提交
两个容易忽略的时序点:postHandle 在响应已写入的情况下不会被执行;afterCompletion 只在 preHandle 返回 true 后才被记录进链,因此 preHandle 返回 false 时对应的 afterCompletion 不会触发。
2.3 HandlerMapping:请求到处理器的映射
RequestMappingHandlerMapping 在容器启动时扫描所有带 @Controller 的 Bean,把 @RequestMapping 及其派生注解解析为 RequestMappingInfo 并注册。
RequestMappingInfo 包含六类条件:
| 条件 | 来源 | 匹配对象 |
|---|---|---|
| 路径模式 | value 或 path | 请求 URI |
| 请求方法 | method | HTTP 方法 |
| 参数条件 | params | 查询参数的存在性、取值、非取值 |
| 请求头条件 | headers | 请求头的存在性与取值 |
| 请求体类型 | consumes | Content-Type |
| 响应体类型 | produces | Accept |
查找过程分两步:先按路径匹配得到候选集合,再按其余条件过滤;多个都匹配时按比较规则排序取最优。
排序规则的关键点:
- 路径更具体的优先,即模式越精确、通配越少的排在前面。
- 条件更多的优先,即声明了方法、参数、头的映射比不声明的更优先。
- 因此
GET /orders/{id}与GET /orders/summary同时存在时,字面量路径优先,不会出现被路径变量吞掉的情况;反过来,若两者都写成路径变量则属于配置冲突,启动即报错。
路径匹配有两套实现:
| 维度 | AntPathMatcher | PathPatternParser |
|---|---|---|
| 匹配方式 | 运行时逐段解析模式字符串 | 启动时把模式解析为匹配器结构 |
| 性能 | 每次匹配都要解析 | 解析一次后重复使用 |
| 语法限制 | 支持 ** 出现在任意位置 | ** 只能出现在模式末尾 |
| 路径变量 | 支持正则约束 | 支持正则约束 |
| 引入版本 | 早期默认 | Spring 5.3 引入,Spring Boot 2.6 起为默认 |
语法限制导致升级时需要检查原有的中间通配写法,例如 /a/**/b 在 PathPatternParser 下不被允许,必须在启动时暴露出来而不是运行期才失败。
2.4 HandlerAdapter:处理器的适配
容器中可能存在多种处理器:注解方法、函数式端点、HttpRequestHandler。它们的调用方式不同,HandlerAdapter 的作用是把"按类型调用"收敛成统一接口。
对注解方法而言,RequestMappingHandlerAdapter 承担三件事:解析参数、调用方法、处理返回值。它持有两个有序列表,分别是参数解析器与返回值处理器。
2.5 参数解析:HandlerMethodArgumentResolver
解析器链按注册顺序尝试,第一个 supportsParameter 返回 true 的解析器负责该参数。
| 参数形态 | 解析器 | 解析方式与注意点 |
|---|---|---|
@RequestParam | RequestParamMethodArgumentResolver | 从参数或表单取字符串后做类型转换;required 默认 true,缺失即 400 |
@PathVariable | PathVariableMethodArgumentResolver | 从路径变量取值;名称需与占位符一致,不一致时必须显式指定 |
@RequestBody | RequestResponseBodyMethodProcessor | 用 HttpMessageConverter 读取请求体;请求体只能读一次,与其他读取方式冲突 |
@ModelAttribute | ModelAttributeMethodProcessor | 用数据绑定逐属性写入,支持嵌套与集合;绑定失败的错误进入 BindingResult |
@RequestHeader、@CookieValue | 对应解析器 | 从请求头或 Cookie 取值 |
HttpServletRequest、HttpServletResponse | ServletRequestMethodArgumentResolver | 直接注入原生对象 |
Principal、Authentication | 对应解析器 | 由安全过滤器链填充 |
| 无注解的简单类型 | 按名称匹配参数名 | 依赖编译期保留参数名(-parameters),否则需要显式注解 |
| 无注解的复杂对象 | ModelAttributeMethodProcessor | 按表单绑定处理,与 @RequestBody 的语义不同 |
三个高频问题:
@RequestBody与@RequestParam混用:请求体读出后流已耗尽,后续读取为空,表现为参数始终为 null。- 无注解简单类型依赖参数名:未开启
-parameters编译参数时参数名变成arg0,绑定失败;Spring Boot 的 Maven 与 Gradle 插件默认开启该参数,自建构建配置时需要确认。 - 校验失败的处理位置:
@Valid校验失败抛MethodArgumentNotValidException,若方法签名中紧跟BindingResult参数则异常不抛出而由开发者自行处理,两种方式混用时容易漏处理。
2.6 返回值处理:HandlerMethodReturnValueHandler
| 返回值形态 | 处理器 | 结果 |
|---|---|---|
标注 @ResponseBody 或类上标注 @RestController | RequestResponseBodyMethodProcessor | 经消息转换器写入响应体 |
返回 String 且未标注 @ResponseBody | ViewNameMethodReturnValueHandler | 作为逻辑视图名交给视图解析器 |
返回 ModelAndView | ModelAndViewMethodReturnValueHandler | 视图名与模型分开处理 |
返回 ResponseEntity | HttpEntityMethodProcessor | 可控制状态码与响应头 |
返回 Callable、DeferredResult、ResponseBodyEmitter | 异步处理器 | 请求进入异步模式,由另一线程完成写入 |
返回 void | 直接写响应或推导视图名 | 取决于参数中是否含响应对象 |
ResponseEntity 与 @ResponseBody 的差别是前者可以显式指定状态码与响应头,需要按业务返回不同状态码时使用前者;统一由异常处理器决定状态码时用后者即可。
2.7 消息转换:HttpMessageConverter
HttpMessageConverter 同时承担读与写,两条链路分别由 canRead 与 canWrite 判定。
- 读:按请求的
Content-Type在所有转换器中查找第一个canRead为真的。 - 写:按目标类型与
Accept查找第一个canWrite为真的,并用其getSupportedMediaTypes决定响应的Content-Type。
默认注册顺序中,ByteArrayHttpMessageConverter、StringHttpMessageConverter、ResourceHttpMessageConverter 等在 JSON 转换器之前,因此对 byte[]、String、Resource 返回类型的处理不会走 JSON 序列化,这是"返回字符串时没有引号"的原因。
JSON 转换器默认使用 Jackson,可配置的点集中在三处:ObjectMapper 的定制(时间格式、空值策略、未知字段容错)、MappingJackson2HttpMessageConverter 的媒体类型、WebMvcConfigurer 中转换器的顺序与增删。
内容协商决定"写哪种类型",由两类策略组成:
| 策略 | 依据 | 说明 |
|---|---|---|
| 请求头策略 | Accept | 默认启用,最常规的方式 |
| 参数策略 | 查询参数 | 需显式开启;通过路径扩展名判断的方式已被废弃 |
协商结果无匹配时返回 406。前后端分离项目通常固定为 application/json,混用 XML 或其他格式时才需要显式配置。
2.8 异常处理链路
异常先由 HandlerExceptionResolver 链处理,顺序固定:
| 顺序 | 解析器 | 处理对象 |
|---|---|---|
| 1 | ExceptionHandlerExceptionResolver | @ExceptionHandler 标注的方法 |
| 2 | ResponseStatusExceptionResolver | 标注 @ResponseStatus 的异常 |
| 3 | DefaultHandlerExceptionResolver | 框架内建异常到状态码的映射 |
@ExceptionHandler 的查找规则:
- 优先在抛出异常的 Controller 内部查找,再查找
@ControllerAdvice。 - 多个 Advice 匹配时,按 Advice 的
@Order与异常类型的具体程度选择,匹配到最具体的异常类型优先。 - 返回 null 表示该解析器未处理,继续交给下一个解析器。
与 Filter 层异常的区别:Filter 在 DispatcherServlet 之外,其中的异常不会进入上述解析链,因此 Filter 中需要自行捕获与转换,否则表现为容器默认错误页。
2.9 拦截器与异步请求
HandlerInterceptor 有三个回调时机,对应请求处理的不同阶段。异步请求下三个时机的语义会变化:preHandle 仍同步执行,方法返回 Callable 或 DeferredResult 后 postHandle 与 afterCompletion 立即执行并在响应完成前就返回,此时需要改用 AsyncHandlerInterceptor 的 afterConcurrentHandlingStarted 做资源清理。
因此"统计请求耗时"这类需求不能在 postHandle 中实现,异步请求下统计到的是提交耗时而非完成耗时;正确做法是记录开始时间并在 afterCompletion 或响应完成回调中计算,同时注意异步场景下的执行线程已变化。
2.10 请求上下文与线程
RequestContextHolder 用 ThreadLocal 保存当前请求的属性与区域设置,供非 Controller 层代码获取请求对象。它带来两个必须注意的问题:
- 异步与虚拟线程场景下上下文断裂:任务被提交到另一个线程后,
ThreadLocal中的请求属性不可见。RequestContextHolder提供了可继承模式,但继承的是提交时刻的快照,长时间异步任务中继续使用快照可能引用已回收的请求对象。 - 线程复用导致的脏数据:使用线程池时未在请求结束时清理,会把上一次请求的属性带到下一次;框架在请求结束时会清理,但手工设置到
ThreadLocal的自定义数据需要自行清理。
实践结论:跨线程使用请求上下文时显式传递所需字段(如租户标识、链路标识),不要依赖 ThreadLocal 自动传播。
三、实现
3.1 自定义参数解析器
// 把请求头中的租户标识解析为业务对象,避免每个方法重复声明
public class TenantArgumentResolver implements HandlerMethodArgumentResolver {
@Override
public boolean supportsParameter(MethodParameter parameter) {
return Tenant.class.isAssignableFrom(parameter.getParameterType());
}
@Override
public Object resolveArgument(MethodParameter parameter,
ModelAndViewContainer mavContainer,
NativeWebRequest webRequest,
WebDataBinderFactory binderFactory) {
String tenantId = webRequest.getHeader("X-Tenant-Id");
if (tenantId == null || tenantId.isBlank()) {
throw new BusinessException(ErrorCode.TENANT_MISSING);
}
return new Tenant(tenantId);
}
}
// 注册:使用 WebMvcConfigurer 时是追加,使用 WebMvcRegistrations 时可替换默认注册表
@Configuration
public class WebArgumentConfig implements WebMvcConfigurer {
@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
resolvers.add(new TenantArgumentResolver());
}
}
要点:addArgumentResolvers 是在默认解析器之后追加,自定义解析器的 supportsParameter 判断必须足够严格,否则会抢占简单类型参数的解析。
3.2 消息转换与内容协商配置
@Configuration
public class WebConverterConfig implements WebMvcConfigurer {
@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
ObjectMapper mapper = new ObjectMapper();
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); // 空值不输出
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); // 兼容新增字段
mapper.registerModule(new JavaTimeModule()); // 支持 java.time
mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); // 时间输出为字符串
MappingJackson2HttpMessageConverter jsonConverter = new MappingJackson2HttpMessageConverter(mapper);
// 替换默认 JSON 转换器,而不是新增,避免出现两个 JSON 转换器导致顺序歧义
converters.replaceAll(c -> c instanceof MappingJackson2HttpMessageConverter ? jsonConverter : c);
}
@Override
public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
configurer.favorParameter(false)
.ignoreAcceptHeader(false)
.defaultContentType(MediaType.APPLICATION_JSON);
}
}
要点:FAIL_ON_UNKNOWN_PROPERTIES 关闭是接口演进的前提,否则服务端新增字段会使旧客户端反序列化失败;这是兼容性设计中最常被忽略的一项。
3.3 统一异常处理与状态码
@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
// 业务异常:错误码与状态码由异常自身携带
@ExceptionHandler(BusinessException.class)
public ResponseEntity<ApiError> handleBusiness(BusinessException e) {
ApiError body = ApiError.of(e.getErrorCode(), MDC.get("traceId"));
return ResponseEntity.status(e.getErrorCode().httpStatus()).body(body);
}
// 请求体格式错误:由框架内建异常派生,覆盖后返回统一结构
@Override
protected ResponseEntity<Object> handleHttpMessageNotReadable(
HttpMessageNotReadableException ex, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
return ResponseEntity.badRequest()
.body(ApiError.of(ErrorCode.REQUEST_BODY_INVALID, MDC.get("traceId")));
}
// 兜底:只记录堆栈,不外泄内部细节
@ExceptionHandler(Exception.class)
public ResponseEntity<ApiError> handleUnknown(Exception e) {
String traceId = MDC.get("traceId");
log.error("未处理异常 traceId={}", traceId, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(ApiError.of(ErrorCode.SERVER_ERROR, traceId));
}
}
要点:继承 ResponseEntityExceptionHandler 可以覆盖框架内建异常(参数校验、请求体不可读、方法不支持、媒体类型不支持等)的响应结构,避免这些异常绕过自定义统一格式。
3.4 拦截器与执行顺序
@Configuration
public class WebInterceptorConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 顺序由注册顺序决定,先注册的先执行 preHandle、后执行 postHandle
registry.addInterceptor(new TraceIdInterceptor()).order(0).addPathPatterns("/**");
registry.addInterceptor(new AuthInterceptor()).order(10)
.addPathPatterns("/api/**")
.excludePathPatterns("/api/public/**", "/api/health");
}
}
// 异步请求场景:改用 AsyncHandlerInterceptor,在并发处理开始时做清理
public class TraceIdInterceptor implements AsyncHandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
// 仅生成与记录,不做耗时统计
return true;
}
@Override
public void afterConcurrentHandlingStarted(HttpServletRequest request,
HttpServletResponse response, Object handler) {
// 异步线程已接管,释放当前线程上的上下文
MDC.clear();
}
}
3.5 链路验证与排查
# 打开请求映射与处理器调用的 DEBUG 日志,观察实际选择结果
logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG
logging.level.org.springframework.web.servlet.mvc.method.annotation=DEBUG
logging.level.org.springframework.web.servlet.handler=DEBUG
# 列出容器中所有已注册的请求映射(Spring Boot Actuator)
curl -s http://localhost:8080/actuator/mappings | jq '.contexts[].mappings.dispatcherServlets'
# 确认某个路径命中哪个处理方法
curl -s http://localhost:8080/actuator/mappings | jq -r '..|.details?|select(.!=null)|.requestMappingConditions?|select(.!=null)|"\(.patterns) \(.methods)"'
# 确认响应内容类型与协商结果
curl -sI -H 'Accept: application/json' http://localhost:8080/api/orders/1 | grep -i content-type
curl -sI -H 'Accept: application/xml' http://localhost:8080/api/orders/1 | head -1
# 确认 406 是否由内容协商引起
curl -s -o /dev/null -w '%{http_code}\n' -H 'Accept: text/csv' http://localhost:8080/api/orders/1
# 确认上传接口是否因缺少 MultipartResolver 而失败
curl -s -o /dev/null -w '%{http_code}\n' -F 'file=@README.md' http://localhost:8080/api/upload
3.6 常见问题对照
| 现象 | 常见原因 | 核对手段 |
|---|---|---|
| 参数始终为 null | 同时读取了请求体,流已耗尽;或未开启 -parameters 导致无注解参数名不匹配 | DEBUG 日志与显式注解验证 |
| 新增字段后旧客户端反序列化失败 | 未关闭 FAIL_ON_UNKNOWN_PROPERTIES | 检查 ObjectMapper 配置 |
| 返回字符串被加了引号或未被转义 | 返回类型匹配到 StringHttpMessageConverter 而非 JSON 转换器 | 确认方法返回值与媒体类型 |
| 返回时间是一串数字 | 未关闭 WRITE_DATES_AS_TIMESTAMPS 或未注册 JavaTimeModule | 检查转换器配置 |
| 自定义转换器不生效 | 使用 add 追加导致默认转换器先匹配,或存在两个 JSON 转换器 | 用 extendMessageConverters 替换并核对顺序 |
| 校验失败返回的不是统一结构 | 未覆盖 ResponseEntityExceptionHandler 的对应方法 | 请求非法参数观察响应体 |
| 406 错误 | Accept 与 produces 不匹配 | 核对 produces 与请求头 |
| 上传接口 400 或参数为空 | 未配置 MultipartResolver,或未声明 MultipartFile 参数名 | 检查配置与接口签名 |
| 拦截器未生效 | 路径模式未覆盖,或注册了多个 WebMvcConfigurer 导致顺序不符合预期 | actuator/mappings 与拦截器顺序 |
| 异步接口耗时统计偏小 | 在 postHandle 中统计,异步下该时机提前执行 | 改用 afterCompletion 或完成回调 |
| 异步线程取不到请求对象 | ThreadLocal 不跨线程 | 显式传递所需字段 |
四、总结
- Spring MVC 解决的核心问题是把参数解析、序列化、路由分派与异常处理四类重复劳动收敛为可替换组件,代价是链路变长、排障依赖组件级的日志。
DispatcherServlet初始化九类策略组件,优先取容器中的同类型 Bean,取不到才用默认实现;MultipartResolver必须显式配置。- 一次请求的顺序是:查找处理器、选择适配器、执行
preHandle、解析参数并调用、处理返回值、逆序postHandle、渲染、afterCompletion;任一步的异常都进入HandlerExceptionResolver。 RequestMappingInfo按路径与条件两类信息匹配,路径更具体、条件更多的优先,字面量路径不会被路径变量覆盖。- 两套路径匹配器的主要差异是
PathPatternParser要求**只能位于末尾,升级时必须检查中间通配写法。 - 参数解析与返回值处理都是有序链,自定义时要注意追加位置与
supportsParameter的判断范围;@RequestBody只能读取一次请求体。 - 消息转换按
canRead与canWrite判定,默认顺序决定了String、byte[]、Resource不会走 JSON;替换默认 JSON 转换器比追加更安全。 - 异常解析顺序固定为
@ExceptionHandler、@ResponseStatus、框架内建映射;Filter 中的异常不进入该链路。 - 异步请求会改变拦截器回调时机,耗时统计与上下文清理必须改用异步相应时机处理。
RequestContextHolder基于ThreadLocal,异步与虚拟线程下上下文不自动传播,跨线程应显式传递所需字段。