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

在 Web 项目中登录鉴权是最核心的安全机制接口必须校验用户是否登录、是否拥有权限未登录则直接拦截禁止访问。SpringBoot 提供的HandlerInterceptor 拦截器是实现登录校验、日志记录、接口限流最优雅的方案。本篇文章将介绍原理、自定义拦截器、登录校验实战、放行白名单、全局异常处理。一、什么是拦截器作用是什么拦截器Interceptor在请求进入Controller 之前/之后/渲染完成进行拦截处理。核心用途登录状态校验权限校验接口日志记录防重复提交性能监控特点只拦截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.java1importlombok.extern.slf4j.Slf4j; 2importorg.springframework.web.servlet.HandlerInterceptor; 3importjavax.servlet.http.HttpServletRequest; 4importjavax.servlet.http.HttpServletResponse; 5 6/** 7* 登录拦截器校验是否登录 8*/ 9Slf4j 10publicclassLoginInterceptorimplementsHandlerInterceptor{ 11 12// 进入Controller前执行核心校验逻辑 13Override 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;charsetutf-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*/ 8Configuration 9publicclassWebConfigimplementsWebMvcConfigurer{ 10 11Override 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;charsetutf-8); 2Result result Result.fail(401,未登录请先登录); 3response.getWriter().write(newObjectMapper().writeValueAsString(result)); 4returnfalse;返回格式1{ 2code:401, 3msg:未登录请先登录, 4data:null 5}六、登录校验逻辑真实项目中登录逻辑一般是前端登录成功后端生成TokenToken 存入Redis设置过期时间前端每次请求在请求头 header 携带 token拦截器获取 token查询 Redis 是否有效有效放行无效拦截完整版拦截器1Slf4j 2publicclassLoginInterceptorimplementsHandlerInterceptor{ 3 4Autowired 5privateRedisTemplateString,Object redisTemplate; 6 7Override 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;charsetutf-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组件技术作用范围适用场景拦截器 InterceptorSpring只拦截Controller登录、权限、日志过滤器 FilterServlet所有请求编码、跨域、限流登录鉴权优先用拦截器九、总结实现 HandlerInterceptorpreHandle 写登录校验WebConfig 注册 白名单返回 401 未登录配合 Redis 实现真实登录鉴权