项目里有两个接口:一个查询当前账号资料,一个修改当前账号资料。它们的业务逻辑不同,但进入业务之前,都要解决同一个问题:这次请求是谁发起的?
如果两个 Controller 都自己取 token、校验 JWT、读取账号 ID,这段逻辑很快就会出现在更多接口里。我们可以把它放进 LoginInterceptor:登录校验通过后,Controller 直接使用当前账号信息。校验失败时,拦截器返回未登录响应,请求到这里结束。
本文以 Spring Boot 3、Spring MVC 和同步请求为例,沿用项目里的 JwtUtils、`AccountDTO`、`BizCodeEnum` 和 JsonData。
一、一个请求什么时候会经过拦截器?
假设前端要查询当前账号,发送了这样一个请求:
GET /api/account/me
token: <登录时拿到的 JWT>
Spring MVC 找到这个请求对应的 Controller 方法后,会先执行与路径匹配的拦截器。`HandlerInterceptor` 提供了三个回调,其中登录校验主要用到第一个和最后一个。Spring HandlerInterceptor 文档
https://docs.spring.io/spring-framework/docs/6.2.x/javadoc-api/org/springframework/web/servlet/HandlerInterceptor.html
| 方法 | 在本例中的执行时机 | 适合做什么 |
|---|---|---|
preHandle() | 调用 Controller 之前 | 校验 token,保存当前账号 |
postHandle() | Controller 正常执行完成之后、视图渲染之前 | 对有视图的请求补充模型数据 |
afterCompletion() | 当前同步请求处理结束时 | 清理当前线程上的账号信息 |
preHandle() 的返回值决定请求能否继续。返回 true,Spring MVC 继续执行后续拦截器和 Controller。返回 false,处理链在这里停止,因此拦截器需要自己把错误响应写给客户端。
二、编写登录拦截器
下面的代码根据项目中的 LoginInterceptor 整理。保留了 token 请求头和原有的未登录响应,并做了三处调整:只通过请求头接收凭证、校验 accountId 的格式、将账号上下文封装为私有字段。
package net.Bdu.interceptor;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwtException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import net.Bdu.dto.AccountDTO;
import net.Bdu.enums.BizCodeEnum;
import net.Bdu.utils.CommonUtil;
import net.Bdu.utils.JsonData;
import net.Bdu.utils.JwtUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.cors.CorsUtils;
import org.springframework.web.servlet.HandlerInterceptor;
@Component
public class LoginInterceptor implements HandlerInterceptor {
private static final ThreadLocal<AccountDTO> CURRENT_ACCOUNT =
new ThreadLocal<>();
public static AccountDTO currentAccount() {
return CURRENT_ACCOUNT.get();
}
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) throws Exception {
if (CorsUtils.isPreFlightRequest(request)) {
return true;
}
String token = request.getHeader("token");
if (StringUtils.isBlank(token)) {
return reject(response);
}
Claims claims;
try {
claims = JwtUtils.checkLoginJWT(token);
} catch (JwtException | IllegalArgumentException ex) {
return reject(response);
}
if (claims == null) {
return reject(response);
}
Object rawId = claims.get("accountId");
Object rawUsername = claims.get("username");
if (rawId == null || !(rawUsername instanceof String username)
|| StringUtils.isBlank(username)) {
return reject(response);
}
long accountId;
try {
accountId = Long.parseLong(rawId.toString());
} catch (NumberFormatException ex) {
return reject(response);
}
AccountDTO account = AccountDTO.builder()
.id(accountId)
.username(username)
.build();
CURRENT_ACCOUNT.set(account);
return true;
}
private boolean reject(HttpServletResponse response) throws Exception {
response.setStatus(HttpStatus.UNAUTHORIZED.value());
CommonUtil.sendJsonMessage(
response,
JsonData.buildResult(BizCodeEnum.ACCOUNT_UNLOGIN)
);
return false;
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Exception ex) {
CURRENT_ACCOUNT.remove();
}
}
原代码的 postHandle() 只调用了接口默认实现,因此这里直接省略。阅读这个拦截器时,可以关注三个具体问题。
第一个问题:从哪里取 token? 原代码先读请求头,取不到时再调用 request.getParameter("token")。如果调用方把 token 拼进 URL,它可能留在访问日志或浏览器历史中。示例统一从请求头读取。如果已有客户端依赖参数传递,需要同步调整调用方式。
第二个问题:什么时候可以相信 accountId? JwtUtils.checkLoginJWT(token) 是整个流程的前提。这个工具方法需要按项目约定验证签名、有效期等条件,再返回可信的 Claims。即使校验通过,也要检查项目需要的字段。原代码直接执行 accountIdObj.toString(),遇到缺少 accountId 的凭证会抛出空指针异常,客户端可能收到 500。这里把这种情况归入未登录响应。
第三个问题:为什么最后才调用 CURRENT_ACCOUNT.set()? 对当前拦截器而言,只有 preHandle() 成功返回 true 后,Spring MVC 才会调用它的 afterCompletion()。把 set() 放在所有失败分支之后,就能保证被拒绝的请求不会留下一个等不到清理的账号对象。Spring HandlerInterceptor 回调约定
三、注册拦截器,指定哪些接口需要登录
@Component 会让 Spring 创建 LoginInterceptor 实例。要让它参与 MVC 请求处理,还要通过 WebMvcConfigurer 注册,并指定生效范围。Spring MVC 拦截器配置
package net.Bdu.config;
import net.Bdu.interceptor.LoginInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
private final LoginInterceptor loginInterceptor;
public WebMvcConfig(LoginInterceptor loginInterceptor) {
this.loginInterceptor = loginInterceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(loginInterceptor)
.addPathPatterns("/api/account/**")
.excludePathPatterns(
"/api/account/login",
"/api/account/register"
);
}
}
按这份配置,`/api/account/me` 需要登录,`/api/account/login` 和 /api/account/register 可以直接访问。路径要与项目真实的 Controller 映射一致。比如消息接口位于 /api/message/**,也需要登录,就要把这组路径加入 addPathPatterns()。
原代码对所有 OPTIONS 请求设置 204,随后返回 true。这里有个容易忽略的区别:设置响应状态不会结束处理链,返回 true 后请求仍会继续。 示例使用 CorsUtils.isPreFlightRequest() 识别浏览器的跨域预检,由项目的 CORS 配置处理允许的来源、方法和请求头。前端跨域发送自定义 token 请求头时,CORS 配置也要允许这个请求头。
四、在 Controller 中获取当前账号
完成注册后,查询当前账号的接口可以写得很短:
package net.Bdu.controller;
import net.Bdu.dto.AccountDTO;
import net.Bdu.interceptor.LoginInterceptor;
import net.Bdu.utils.JsonData;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/account")
public class AccountController {
@GetMapping("/me")
public JsonData me() {
AccountDTO account = LoginInterceptor.currentAccount();
return JsonData.buildSuccess(account);
}
}
这里有个实际收益:前端调用 /me 时,只需带上登录凭证。 后端使用已校验 JWT 中的账号 ID 来确定当前用户。以后实现“修改我的昵称”,也可以从这个上下文获取操作人,再用请求体接收新昵称。
如果接口是“修改某个群聊资料”,知道当前账号是谁只完成了身份确认。这个账号是不是群主、有没有修改权限,仍要根据具体资源做授权判断。对需要覆盖整个应用的认证与授权,Spring 官方推荐使用 Spring Security 或与 Servlet 过滤器链集成的方案。Spring MVC 关于拦截器适用范围的说明
五、为什么请求结束后必须 remove()?
ThreadLocal 把值绑定在当前线程上。一次普通的同步请求中,拦截器和 Controller 通常运行在同一个线程,因此前面 set(account),后面就能 get()。
但 Web 容器会复用工作线程。假设线程先处理了小明的请求,请求结束后,这个线程还可能处理一个公开接口。如果没有清理,公开接口中的日志代码一旦读取账号上下文,就可能读到上一次请求留下的小明。
所以本例将账号上下文的使用范围限定为:
登录校验通过 → set(account) → Controller 使用 → afterCompletion 中 remove()
这个约定适用于本文的同步 MVC 示例。如果把任务提交给 @Async 或线程池,工作线程有自己的 ThreadLocal。异步任务需要操作人 ID 时,可以在提交任务前读取 accountId 并作为参数传入。使用 MVC 异步请求时,还需要考虑原请求线程退出后的清理时机。Spring HandlerInterceptor 异步处理说明
六、用四次请求验证拦截器
可以在 preHandle()、`AccountController.me()` 和 afterCompletion() 各打一个断点,用 Postman 对照下面的结果:
| 请求 | 预期结果 |
|---|---|
调用 /api/account/me,不带 token | 返回 HTTP 401 和未登录业务响应,`me()` 不执行 |
调用 /api/account/me,携带已过期的 token | JWT 校验失败,返回未登录响应 |
调用 /api/account/me,携带有效 token | 进入 me(),读到当前账号,完成后清理上下文 |
| 调用已排除的登录接口 | 直接进入登录流程,`LoginInterceptor` 不参与 |
联调时尤其值得看一眼真实的 HTTP 状态码。`JsonData.buildResult(...)` 决定响应体里的业务码,`response.setStatus(401)` 决定 HTTP 状态。如果 Postman 里显示“正文提示未登录,但 HTTP 仍然是 200”,就要检查 CommonUtil.sendJsonMessage() 写 JSON 时是否又设置了响应状态。
把有效 token 的那次请求用断点走完,就能看到这个拦截器最重要的三行代码分别在什么时候生效:`set()` 让当前账号在同步请求中可用,`return true` 让业务方法继续执行,`remove()` 在线程被复用前结束这次请求的账号上下文。
2583



被折叠的 条评论
为什么被折叠?



