内容总览

Spring MVC 请求处理链路 思维导图

一、起源

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 的语义不同

三个高频问题:

  1. @RequestBody 与 @RequestParam 混用:请求体读出后流已耗尽,后续读取为空,表现为参数始终为 null。
  2. 无注解简单类型依赖参数名:未开启 -parameters 编译参数时参数名变成 arg0,绑定失败;Spring Boot 的 Maven 与 Gradle 插件默认开启该参数,自建构建配置时需要确认。
  3. 校验失败的处理位置:@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 不跨线程 显式传递所需字段

四、总结

  1. Spring MVC 解决的核心问题是把参数解析、序列化、路由分派与异常处理四类重复劳动收敛为可替换组件,代价是链路变长、排障依赖组件级的日志。
  2. DispatcherServlet 初始化九类策略组件,优先取容器中的同类型 Bean,取不到才用默认实现;MultipartResolver 必须显式配置。
  3. 一次请求的顺序是:查找处理器、选择适配器、执行 preHandle、解析参数并调用、处理返回值、逆序 postHandle、渲染、afterCompletion;任一步的异常都进入 HandlerExceptionResolver。
  4. RequestMappingInfo 按路径与条件两类信息匹配,路径更具体、条件更多的优先,字面量路径不会被路径变量覆盖。
  5. 两套路径匹配器的主要差异是 PathPatternParser 要求 ** 只能位于末尾,升级时必须检查中间通配写法。
  6. 参数解析与返回值处理都是有序链,自定义时要注意追加位置与 supportsParameter 的判断范围;@RequestBody 只能读取一次请求体。
  7. 消息转换按 canRead 与 canWrite 判定,默认顺序决定了 String、byte[]、Resource 不会走 JSON;替换默认 JSON 转换器比追加更安全。
  8. 异常解析顺序固定为 @ExceptionHandler、@ResponseStatus、框架内建映射;Filter 中的异常不进入该链路。
  9. 异步请求会改变拦截器回调时机,耗时统计与上下文清理必须改用异步相应时机处理。
  10. RequestContextHolder 基于 ThreadLocal,异步与虚拟线程下上下文不自动传播,跨线程应显式传递所需字段。