接口联调时遇到一个怪现象:前端发 POST /api/items,请求体是 {"name":"widget"},控制器里的 @RequestBody 对象字段全是空,校验直接返回 400。抓包看请求体完整,浏览器网络面板也显示 payload 正常。把控制器单独用 MockMvc 测,又能通过。

根因在过滤器:为了打审计日志,过滤器里调用了 request.getInputStream() 把请求体读出来写日志。Servlet 的输入流只能顺序读一次,过滤器读完之后,后面 DispatcherServlet 再读就是空的。请求本身没坏,是读取动作把流消费掉了。

这类问题之所以难查,是因为「过滤器」「拦截器」「控制器」在代码里隔得远,各自看都正确。只有把一次请求的完整路径画出来,才知道哪一层先执行、哪一层能改请求、哪一层改了会影响后面。这一篇就按这条路径走,Java 语法不展开,只讲一个请求怎么被接住、分发、处理、返回。

容器之后,第一个接手的是 DispatcherServlet

内嵌 Tomcat 在 8081 端口收到连接后,从线程池取一个线程,把字节解析成 HttpServletRequest 和 HttpServletResponse,然后交给应用里注册的过滤器链。过滤器是 Servlet 规范的东西,不属于 Spring,它能看到原始请求,也能改写响应头、状态码,甚至直接返回而不往下走。

过滤器链走完,请求才进入 Spring 的前端控制器 DispatcherServlet。它是整个 MVC 的分发中心:先问「这个 URL 对应哪个方法」,再按顺序执行拦截器的 preHandle,然后调用控制器方法,把返回值交给消息转换器写成 JSON,最后执行拦截器的 postHandle 和 afterCompletion。异常也在这里被接住,转给全局异常处理器。

「分发」这个词可以理解成邮局分拣:DispatcherServlet 不处理业务,它只负责看地址、找对应的处理人、把结果送回去。路由表在启动时由 RequestMappingHandlerMapping 扫描所有控制器生成,所以路由错误通常在启动阶段就能看出来,而不是等到第一个请求。

还要记住线程这件事:处理请求的是 Tomcat 的工作线程,不是新起一个线程。线程池大小固定,一个请求在控制器里等数据库、等远程接口,占着的就是这个线程。所以「某个接口特别慢」会表现为「所有接口一起变慢」,因为线程被占满了。这个现象在第五篇讲线程池时会再出现一次。

路由怎么写,参数怎么绑

一个控制器类用 @RestController 标记,它等于 @Controller 加 @ResponseBody:返回值不再当成页面名去找模板,而是直接写进响应体。类上的 @RequestMapping 定公共前缀,方法上的注解定具体路径和 HTTP 方法。前缀和路径拼起来才是完整地址,拼错一个斜杠就是 404。

目录按请求经过的层来分,新增功能时先想清楚代码该落在哪一层,比事后重构省事:

controller:路由与参数绑定
web/filter:请求 ID、编码、访问日志
web/interceptor:方法级权限与耗时
web/advice:统一异常出口
config:注册过滤器与拦截器

下面这个控制器覆盖了三种最常见的参数来源:路径里的 ID、请求体里的 JSON、请求头里的值。@PathVariable 从 URL 模板取值,@RequestBody 让 Jackson 把 JSON 反序列化成对象,@RequestHeader 读头字段,required=false 表示可以不带:

package com.example.demo.controller;

import java.sql.PreparedStatement;
import java.util.List;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.support.GeneratedKeyHolder;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/items")
public class ItemController {
    private final JdbcTemplate jdbc;

    public ItemController(JdbcTemplate jdbc) {
        this.jdbc = jdbc;
    }

    @GetMapping("/{id}")
    public Map<String, Object> one(@PathVariable long id,
            @RequestHeader(value = "X-Trace", required = false) String trace) {
        List<Map<String, Object>> rows =
                jdbc.queryForList("select * from items where id = ?", id);
        if (rows.isEmpty()) {
            throw new ItemNotFoundException(id);
        }
        return rows.get(0);
    }

    @PostMapping
    public ResponseEntity<Map<String, Object>> create(@RequestBody ItemRequest req) {
        KeyHolder keyHolder = new GeneratedKeyHolder();
        jdbc.update(con -> {
            PreparedStatement ps = con.prepareStatement(
                    "insert into items(name) values (?)", new String[]{"id"});
            ps.setString(1, req.name());
            return ps;
        }, keyHolder);
        long id = keyHolder.getKey().longValue();
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(Map.of("name", req.name(), "id", id));
    }

    public record ItemRequest(String name) {}
}

注意 @PostMapping 没有写路径,它会继承类上的 /api/items。这是最常见的写法,也最容易在复制代码时忘了改类前缀,导致两个控制器抢同一个路径,启动时报 ambiguous mapping。真出现这个报错,看异常里给出的两个方法名,比逐个文件搜路径快。

路由匹配还受 consumes 和 produces 影响。请求头 Content-Type 不是 application/json 时,@RequestBody 会返回 415;Accept 不匹配时返回 406。这两个状态码看起来像权限问题,实际是内容协商失败,排查时先看请求头,不要先去翻鉴权代码。

把服务跑起来后,这两个接口的实际返回如下,其中 items 表结构见第三篇的 V1 脚本。第一条是健康检查,第二条是创建,注意状态码 201 是 ResponseEntity 显式指定的,不是默认的 200:

curl -s 127.0.0.1:8081/health
{"status":"up","db":true}

curl -s -X POST 127.0.0.1:8081/api/items \
  -H "Content-Type: application/json" -d '{"name":"widget"}'
HTTP 201
{"name":"widget","id":1}

依赖和启动方式与第一篇一致,只需要父 pom、web 和 jdbc 三项,打包后直接跑 jar。这一篇没有引入新的库:

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.3.5</version>
</parent>
<properties>
  <java.version>21</java.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
  </dependency>
</dependencies>

mvn -q -DskipTests package
java -jar target/demo-0.0.1.jar

一次请求的完整顺序

把上面这些环节按实际执行顺序排开,就是下面这张流程。注意过滤器在 DispatcherServlet 之前,拦截器在 DispatcherServlet 之内、控制器之前;异常处理只在 DispatcherServlet 内部生效,过滤器里抛出的异常它管不到:

一次请求从进入到返回
Tomcat 工作线程接手连接
Filter 链:可改写请求与响应
DispatcherServlet 查路由表
Interceptor.preHandle:可拦截
Controller 执行并返回对象
消息转换器写 JSON
Interceptor.afterCompletion 收尾

这张图解释了两件事。第一,过滤器能拿到最原始的请求,适合做编码、跨域、请求 ID、访问日志这类与业务无关的事。第二,拦截器已经知道「将要执行哪个方法」,适合做基于注解的权限判断、耗时统计这类与路由相关的事。把两者的能力混用,就会出现开头那种「日志过滤器把 body 吃了」的问题。

还有一个顺序细节:preHandle 返回 false 表示中止,后面的控制器不会执行,但已经执行过的拦截器的 afterCompletion 仍会被调用;postHandle 只在控制器正常返回时执行,抛异常时不执行。很多人把清理逻辑放在 postHandle,结果异常路径下 ThreadLocal 没清,线程复用时串数据。清理放在 afterCompletion 才是安全的。

响应一旦提交就不能再改头或改状态码。控制器返回对象时,消息转换器在拦截器 postHandle 之后才把内容写出去,所以 postHandle 里还能补响应头;但如果方法里直接拿了 HttpServletResponse 写了一段流,头已经发出,后面再设就无效。想统一加头,放在过滤器里最稳。

过滤器里读请求体只能读一次。日志需要记录 body 时,用 ContentCachingRequestWrapper 缓存,并只对 1 兆以内的小请求开启;上传接口不要走这条缓存,否则整个文件会进堆内存。

过滤器与拦截器怎么选

两者都能在控制器之前插手,区别在「知道多少」和「能改多少」。过滤器拿到的是 Servlet 的原始对象,能换掉整个 request 和 response,也能在进入 Spring 之前直接返回;代价是它不知道路由、不知道方法、拿不到控制器上的注解。拦截器由 Spring 管理,能注入其他 bean,能拿到 HandlerMethod,因此在方法上打注解、在拦截器里读注解成为可能。

用过滤器

适合与业务无关的横切逻辑:字符编码、CORS、请求 ID、访问日志、压缩、最外层的令牌存在性检查。能改原始请求,也能在 Spring 之前短路。代价是拿不到路由元信息。

用拦截器

适合与路由相关的逻辑:按注解做权限、按控制器统计耗时、给方法准备上下文。能拿到方法签名和注解,能用 Spring 的依赖注入。代价是不能改写请求体,也不能处理静态资源之外的容器级行为。

选择原则很简单:需要看「请求本身」就用过滤器,需要看「要执行的方法」就用拦截器。两者都要用时,把与业务无关的放过滤器,把与权限和路由有关的放拦截器,顺序上过滤器先跑。

过滤器的顺序由 @Order 或 FilterRegistrationBean 的 order 值决定,数值越小越先执行。编码过滤器必须排在读参数的逻辑之前,否则参数已经按错误编码解析过了,后面再设编码也没用。这个顺序错误在中文乱码问题里极常见,而且只在特定容器和特定请求下出现。

异常统一出口:@RestControllerAdvice

控制器里不要写 try-catch 把异常吞掉再返回一段自定义 JSON,每个方法都复制一遍,状态码还容易写错。统一做法是抛出一个带语义的异常,让全局处理器决定 HTTP 状态码和响应体。这样控制器只表达「发生了什么」,不负责「怎么呈现」。

全局处理器用 @RestControllerAdvice 标记,里面用 @ExceptionHandler 按异常类型匹配。匹配规则是「最具体的赢」:有 ItemNotFoundException 的处理器就优先用它,没有再落到 Exception。所以兜底的 Exception 处理器必须存在,但它的职责只是记日志和返回 500,不能把异常信息原样吐给调用方。

package com.example.demo.web;

import com.example.demo.controller.ItemNotFoundException;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(ItemNotFoundException.class)
    public ResponseEntity<Map<String, Object>> notFound(ItemNotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(Map.of("error", "not found"));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> fallback(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("error", "internal"));
    }
}

这里有一个必须知道的边界:@RestControllerAdvice 只处理进入 DispatcherServlet 之后抛出的异常。过滤器里抛的异常、Tomcat 层解析请求失败的异常,都不会走到这里。如果所有错误响应都要求统一格式,过滤器内部必须自己写响应,或者把异常包装后转交。

配套的异常类很简单,带一个 id 只为了日志能定位,响应体不会把它带出去:

package com.example.demo.controller;

public class ItemNotFoundException extends RuntimeException {
    public ItemNotFoundException(long id) {
        super("item " + id + " not found");
    }
}

另一个边界是异常处理器本身抛异常。比如兜底方法里又去查数据库,数据库也挂了,异常会继续向上抛,最终由容器返回默认错误页。兜底逻辑要足够简单:只读异常对象、写日志、返回固定结构,不要再依赖外部资源。

返回体里的 {"error":"not found"} 就是本机实测的输出。状态码 404,响应体只有这一个字段。真实项目通常还会带一个 code 或 traceId,但字段越多,越要保证不把内部细节漏出去,比如 SQL、堆栈、表名。

curl -s 127.0.0.1:8081/api/items/99
{"error":"not found"}

这段响应能对上,说明三件事都对了:路由匹配到了带路径参数的方法,方法里的查询返回空列表并抛出了指定异常,全局处理器把异常映射成 404 和固定 JSON。只要中间任何一环错位,看到的就不是这个结构,而是 Spring 默认的错误页。把这条请求固定成冒烟测试,比记一串排查步骤更可靠。

出错时先看哪一层

下面这张表把常见现象按「最先怀疑的层」排。左边是你看到的结果,中间是真实原因,右边是第一条命令或第一个文件。顺序基本对应请求经过的顺序:容器、过滤器、路由、拦截器、控制器、异常处理。

现象真实原因第一步查什么
POST 的 body 全空,字段校验失败过滤器提前读了输入流搜过滤器里的 getInputStream 和 getReader
接口 404,日志没有异常路径拼错,或控制器不在扫描包内启动日志里的映射表,和启动类的包名
接口 405 Method Not AllowedURL 对上了,HTTP 方法不匹配看注解是 @GetMapping 还是 @PostMapping
跨域预检 OPTIONS 返回 401鉴权过滤器把预检也拦了过滤器里是否对 OPTIONS 放行
全局异常处理没生效Advice 不在扫描范围,或异常被提前吞掉看控制器和 Advice 的包位置,搜 catch
返回 415 或 406Content-Type 或 Accept 与接口不匹配curl -i 看请求头的两个字段
拦截器返回 false,客户端拿到空响应只中止了链,没写状态码和响应体看 preHandle 是否设置 response
中文乱码只在某些接口出现编码过滤器顺序晚于参数解析过滤器的 order 值和编码设置位置
异常路径下 ThreadLocal 残留清理写在 postHandle 而不是 afterCompletion看拦截器的三个回调分别做了什么

这张表的用法是「从外往里」:先确认请求有没有到 Spring,再看路由有没有匹配,最后看方法内部。如果访问日志里连这条请求都没有,问题在容器或反向代理;如果有访问日志但返回 404,问题在路由;如果进入了方法但结果不对,才去看业务代码。

为什么权限判断不该塞进 Controller

先说一个反例:每个控制器方法开头都写 if (token == null) return 401;,再写一段角色判断。这样做的直接后果是复制粘贴,二十个接口就有二十份判断;改一次规则要改二十处,漏一处就是越权漏洞。更隐蔽的后果是有人只写了「有没有 token」,忘了判断「这个用户能不能操作这条数据」,接口看起来有鉴权,实际谁都能改别人的订单。

合理的分层是:令牌存在性和签名校验放过滤器,因为它在路由之前,能统一挡住所有请求;「这个角色能不能访问这个方法」放拦截器读方法上的注解,因为它知道将要执行哪个方法;「这个用户能不能操作这条记录」必须放业务层,因为它要查数据归属。三层各管一件事,互不替代。

把权限放在控制器方法里还有一个测试上的代价:单元测试要构造完整的 Web 上下文,或者用 MockMvc 模拟请求头。放在拦截器和业务层之后,权限规则可以单独测,控制器只测业务分支。项目一旦超过几十个接口,这个差别会变成测试写不写的分界线。

还有一点是错误响应的一致性。过滤器或拦截器统一返回 401 和 403,格式固定,客户端只需要处理两三种结构。散落在控制器里的判断,每个人写的 JSON 都不一样,前端要针对每个接口写兼容,最后没人说得清哪个字段才是权威。

举个具体的越权例子:PUT /api/orders/123 的控制器里判断了「当前用户已登录」,但没判断订单 123 属不属于他。攻击者把 ID 改成 124 就能改别人的订单。这种漏洞在代码评审里很难看出来,因为方法开头确实有鉴权代码。正确的写法是在业务层拿订单,然后比对订单的 user_id 与当前用户,不匹配就当作不存在,连「有没有这条记录」都不该泄露。

边界与代价

过滤器链不是越短越好,但每加一个都要明确它做什么、什么时候短路。常见的问题是「一个过滤器干了三件事」:既做鉴权又做日志又做限流,出问题时无法单独关闭。拆成三个独立过滤器,用 order 控制顺序,排查时可以按需禁用,代价是请求多经过两次链,几乎可以忽略。

读请求体这件事有正规做法:用 ContentCachingRequestWrapper 包一层,让容器缓存内容,后续可以重复读。代价是内存,大文件上传时不能这么干,否则整个文件进堆。判断标准是请求体大小上限,常见 API 设 1 兆以内可以缓存,上传接口单独走另一条链路。

拦截器的能力边界也要说清:它不能改请求体,不能处理容器级错误,对静态资源的映射默认也不生效。想给所有响应加头,用过滤器;想给所有控制器方法计时,用拦截器。用错地方不会立刻报错,而是某些路径悄悄不生效,这种问题最难发现。

异步请求会打乱上面的顺序。控制器返回 Callable 或 DeferredResult 时,preHandle 仍在原线程执行,但后续回调可能在另一个线程,postHandle 和 afterCompletion 的线程也变了。依赖 ThreadLocal 的逻辑会失效。真要用异步,先确认拦截器实现的是 AsyncHandlerInterceptor,并想清楚上下文怎么传。

最后是性能上的边界。一次请求多走两层过滤器、一层拦截器、一次反射调用、一次 JSON 序列化,单看都是微秒级,QPS 上万时才会显现。真到那个量级,优化顺序应该是减少数据库往返、加缓存、再考虑减少框架层,而不是一上来就把 Spring MVC 换掉。

当天能自己验证的练习

  1. 写一个只打日志的过滤器,打印方法、URI 和耗时,用 curl -i 请求 /health,确认它在控制器之前执行。
  2. 在过滤器里调用 request.getInputStream() 读一次 body,再发 POST,观察 @RequestBody 变成空对象,然后删掉这行代码恢复。
  3. 写一个拦截器,在 preHandle 里返回 false 且不写响应,用 curl 看客户端收到什么,再补上 401 和 JSON。
  4. 把 ItemNotFoundException 的处理器注释掉,请求不存在的 ID,对比默认错误页和统一 JSON 的差别。
  5. 给两个控制器写同一个路径,启动服务,抄下 ambiguous mapping 的完整报错,理解路由在启动期就确定。

小结

三句话收束:请求先过过滤器、再进 DispatcherServlet、经过拦截器才到控制器,异常只在这条链的内部被统一处理;路由错误先看启动日志的映射表,参数错误先看请求头和输入流有没有被提前消费;权限判断按「令牌校验在过滤器、方法权限在拦截器、数据归属在业务层」拆开,控制器只留业务。

下一篇进入数据层。路由解决的是「请求找不找得到方法」,接下来要解决「方法拿到数据后怎么落库、连接从哪里来、事务从哪开始」。那篇会从连接池被打满的真实日志讲起,解释为什么池子开得越大,故障反而越突然。