SpringBoot 拦截器（Interceptor）自定义实现登录鉴权

在 Web 项目中，登录鉴权是最核心的安全机制：
接口必须校验用户是否登录、是否拥有权限，未登录则直接拦截，禁止访问。

SpringBoot 提供的HandlerInterceptor 拦截器，是实现登录校验、日志记录、接口限流最优雅的方案。

本篇文章将介绍原理、自定义拦截器、登录校验实战、放行白名单、全局异常处理。

一、什么是拦截器？作用是什么？

拦截器（Interceptor）：在请求进入Controller 之前/之后/渲染完成进行拦截处理。

核心用途：

1. 登录状态校验
2. 权限校验
3. 接口日志记录
4. 防重复提交
5. 性能监控

特点：

• 只拦截Controller 请求

• 不拦截静态资源（可配置）

• 可中断请求，直接返回结果

• 全局统一控制，代码干净

二、拦截器核心 API

实现HandlerInterceptor接口，重写 3 个方法：

1publicinterfaceHandlerInterceptor{ 2 3// 1. 请求进入Controller之前执行（鉴权写这里） 4defaultbooleanpreHandle(HttpServletRequest request,HttpServletResponse response,Object handler)throwsException{ 5returntrue;// true=放行 false=拦截 6} 7 8// 2. Controller执行完毕，渲染页面之前执行 9defaultvoidpostHandle(...)throwsException{} 10 11// 3. 整个请求完全结束后执行（清理资源） 12defaultvoidafterCompletion(...)throwsException{} 13}

登录鉴权只需要 preHandle

三、自定义登录拦截器

创建LoginInterceptor.java：

1importlombok.extern.slf4j.Slf4j; 2importorg.springframework.web.servlet.HandlerInterceptor; 3importjavax.servlet.http.HttpServletRequest; 4importjavax.servlet.http.HttpServletResponse; 5 6/** 7* 登录拦截器：校验是否登录 8*/ 9@Slf4j 10publicclassLoginInterceptorimplementsHandlerInterceptor{ 11 12// 进入Controller前执行：核心校验逻辑 13@Override 14publicbooleanpreHandle(HttpServletRequest request,HttpServletResponse response,Object handler)throwsException{ 15 16// 1. 获取前端传递的 Token / Session 17String token = request.getHeader("token"); 18 log.info("当前请求token：{}", token); 19 20// 2. 判断是否登录（真实项目：查询Redis/数据库） 21if(token ==null|| token.isEmpty()){ 22 log.error("用户未登录，请求被拦截"); 23 24// 拦截，返回未登录提示 25 response.setContentType("application/json;charset=utf-8"); 26 response.getWriter().write("{\"code\":401,\"msg\":\"未登录，请先登录\",\"data\":null}"); 27returnfalse; 28} 29 30// 3. 登录有效，放行 31returntrue; 32} 33}

四、注册拦截器 + 配置白名单

创建WebConfig.java：
实现WebMvcConfigurer，注册拦截器并设置放行接口（登录、注册、放行接口）。

1importorg.springframework.context.annotation.Configuration; 2importorg.springframework.web.servlet.config.annotation.InterceptorRegistry; 3importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer; 4 5/** 6*Web 配置：注册拦截器 7*/ 8@Configuration 9publicclassWebConfigimplementsWebMvcConfigurer{ 10 11@Override 12publicvoidaddInterceptors(InterceptorRegistry registry){ 13 registry.addInterceptor(newLoginInterceptor()) 14.addPathPatterns("/**")// 拦截所有请求 15.excludePathPatterns(// 放行白名单 16"/user/login",// 登录接口 17"/user/register",// 注册接口 18"/swagger/**",// 接口文档 19"/v3/api-docs/**" 20); 21} 22}

✅配置完成，所有接口都会自动校验登录

五、配合统一返回结构

拦截器中直接返回Result 格式：

1response.setContentType("application/json;charset=utf-8"); 2Result result =Result.fail(401,"未登录，请先登录"); 3response.getWriter().write(newObjectMapper().writeValueAsString(result)); 4returnfalse;

返回格式：

1{ 2"code":401, 3"msg":"未登录，请先登录", 4"data":null 5}

六、登录校验逻辑

真实项目中，登录逻辑一般是：

1. 前端登录成功，后端生成Token

2. Token 存入Redis（设置过期时间）

3. 前端每次请求在请求头 header 携带 token

4. 拦截器获取 token，查询 Redis 是否有效

5. 有效放行，无效拦截

完整版拦截器

1@Slf4j 2publicclassLoginInterceptorimplementsHandlerInterceptor{ 3 4@Autowired 5privateRedisTemplate<String,Object> redisTemplate; 6 7@Override 8publicbooleanpreHandle(HttpServletRequest request,HttpServletResponse response,Object handler)throwsException{ 9String token = request.getHeader("token"); 10 11// 1. 无token 12if(token ==null|| token.isBlank()){ 13returnresponseFail(response,"未登录，请先登录"); 14} 15 16// 2. 校验Redis 17Object user = redisTemplate.opsForValue().get("login:token:"+ token); 18if(user ==null){ 19returnresponseFail(response,"登录已过期，请重新登录"); 20} 21 22// 3. 放行 23returntrue; 24} 25 26// 统一返回错误 27privatebooleanresponseFail(HttpServletResponse response,String msg)throwsException{ 28 response.setContentType("application/json;charset=utf-8"); 29Result<?> result =Result.fail(401, msg); 30 response.getWriter().write(newObjectMapper().writeValueAsString(result)); 31returnfalse; 32} 33}

七、拦截器常见高级用法

1. 获取当前请求接口信息

1HandlerMethod handlerMethod =(HandlerMethod) handler; 2String methodName = handlerMethod.getMethod().getName(); 3String className = handlerMethod.getBean().getClass().getName();

2. 放行静态资源

1.excludePathPatterns("/static/**","/img/**","/css/**","/js/**")

3. 多拦截器顺序

1registry.addInterceptor(A).order(1); 2registry.addInterceptor(B).order(2);

数字越小，越先执行。

八、拦截器 VS 过滤器 Filter

登录鉴权优先用拦截器！

九、总结

1. 实现 HandlerInterceptor
2. preHandle 写登录校验
3. WebConfig 注册 + 白名单
4. 返回 401 未登录
5. 配合 Redis 实现真实登录鉴权