Spring Boot 拦截器：解锁5大实用场景

一、Spring Boot中拦截器是什么

  在Spring Boot中，拦截器（Interceptor）是一种基于AOP（面向切面编程）思想的组件，用于在请求处理前后插入自定义逻辑，实现权限校验、日志记录、性能监控等非业务功能。

  其核心作用是在不修改业务代码的前提下，对请求进行统一处理，类似于Servlet中的Filter，但更贴近Spring MVC的体系。

二、拦截器与过滤器的区别

三、拦截器主要方法

在实现拦截器时，HandlerInterceptor接口提供了三个主要方法，它们在请求处理的不同阶段发挥着重要作用。
​
preHandle
  这个方法在请求进入Controller之前被调用 。它的返回值是一个布尔类型，如果返回true，请求将继续被处理，进入Controller。
   如果返回false，请求将被拦截，后续的Controller方法将不会被执行。在这个方法中，我们通常可以进行一些前置的处理操作，比如用户认证、权限校验、日志记录等。​

postHandle
  当Controller方法执行完毕后，视图渲染之前，这个方法会被调用 。

  在这个方法中，我们可以对ModelAndView进行一些操作，比如添加额外的模型数据，修改视图名称等。需要注意的是，如果在preHandle方法中返回了false，这个方法将不会被执行。​

afterCompletion
  在整个请求处理完成，包括视图渲染之后，这个方法会被调用。无论请求处理过程中是否发生异常，只要preHandle方法返回true，这个方法就会被执行。

  我们可以在这个方法中进行一些资源清理、记录日志等收尾工作。如果请求处理过程中发生了异常，异常信息会通过 ex 参数传递进来，我们可以根据这个参数进行相应的异常处理。

@Component
public class MyInterceptor implements HandlerInterceptor {@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {// 在请求处理之前执行的逻辑System.out.println("preHandle被调用，请求即将进入Controller");return true; // 返回true表示放行请求，返回false则拦截请求}@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {// 在请求处理之后，视图渲染之前执行的逻辑System.out.println("postHandle被调用，Controller方法已执行完毕，视图即将渲染");}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {// 在整个请求处理完成，包括视图渲染之后执行的逻辑System.out.println("afterCompletion被调用，整个请求已处理完毕");}
}

@Configuration
public class WebMvcConfig1 implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new MyInterceptor()).addPathPatterns("/**") // 拦截所有请求.excludePathPatterns("/static/**"); // 排除/static目录下的静态资源请求}
}

四、5 种常见的拦截器使用场景

1.用户认证拦截器

  用户认证拦截器的作用就是在用户请求进入 Controller 之前，验证用户的登录状态。如果用户已经登录，允许请求继续处理。如果用户未登录，则返回错误信息或者重定向到登录页面。

@Component
public class JwtHandlerInterceptor implements HandlerInterceptor {@Autowiredprivate JwtTokenProvider jwtTokenProvider;@Autowiredprivate UserInfoService userInfoService;@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {if (!(handler instanceof HandlerMethod)) {return true;}// 取出tokenString token = request.getHeader("token");if (!jwtTokenProvider.validateToken(token)) {response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);response.getWriter().write("{\"error\": \"Token已失效，请重新登录\"}");return false;}HandlerMethod handlerMethod = (HandlerMethod) handler;Method method = handlerMethod.getMethod();// 判断方法上是否有NoAuth注解，如果有则跳过认证if (method.isAnnotationPresent(NoAuth.class)) {return true;}String username = jwtTokenProvider.getUsernameFromJWT(token);User user = userInfoService.getUserInfoByUserName(username);if (user == null) {response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);response.getWriter().write("{\"error\": \"用户不存在\"}");return false;}// 判断角色权限HasRoles hasRoles = handlerMethod.getMethodAnnotation(HasRoles.class);if (!Objects.isNull(hasRoles)) {// 检查用户是否有所需角色String[] roles = hasRoles.value();boolean hasRole = false;// 角色校验 ...if (!hasRole) {response.setStatus(HttpServletResponse.SC_FORBIDDEN);response.getWriter().write("{\"error\": \"权限不足\"}");return false;}}// 将用户信息放入请求属性request.setAttribute("currentUser", user);return true;}@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {HandlerInterceptor.super.afterCompletion(request, response, handler, ex);}
}

  在WebMvcConfig配置类中，将JwtHandlerInterceptor注册到Spring的拦截器链中，并设置拦截路径为所有请求，排除了登录和注册接口，因为这两个接口不需要用户登录就可以访问。

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(new JwtHandlerInterceptor()).addPathPatterns("/**")// 拦截所有请求.excludePathPatterns("/login","/register");// 排除登录和注册接口}}

  通过这样的配置，就可以实现对用户登录状态的验证，确保只有登录用户才能访问受保护的资源。

2.日志记录拦截器

  日志记录对于系统的运维和故障排查非常重要。日志记录拦截器可以在请求处理的前后记录请求的相关信息，比如请求的 URL、请求方法、请求参数、客户端 IP 等。这些日志信息可以帮助我们了解系统的运行情况，分析用户行为，在出现问题时快速定位问题。

@Component
public class RequestLoggingInterceptor implements HandlerInterceptor {private static final Logger logger = LoggerFactory.getLogger(RequestLoggingInterceptor.class);@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {logger.info("Request URL: {}, Method: {}, IP: {}", request.getRequestURI(), request.getMethod(), request.getRemoteAddr());// 记录请求参数Map<String, String[]> paramMap = request.getParameterMap();StringBuilder params = new StringBuilder();if (!paramMap.isEmpty()) {for (Map.Entry<String, String[]> entry : paramMap.entrySet()) {params.append(entry.getKey()).append("=").append(String.join(",", entry.getValue())).append("&");}if (params.length() > 0) {params.deleteCharAt(params.length() - 1);}}// 记录请求体（仅POST/PUT/PATCH请求）String method = request.getMethod();String requestBody = "";if (HttpMethod.POST.matches(method) ||HttpMethod.PUT.matches(method) ||HttpMethod.PATCH.matches(method)) {// 使用包装请求对象来多次读取请求体ContentCachingRequestWrapper wrappedRequest =new ContentCachingRequestWrapper(request);// 为了触发内容缓存，我们需要获取一次输入流if (wrappedRequest.getContentLength() > 0) {wrappedRequest.getInputStream().read();requestBody = new String(wrappedRequest.getContentAsByteArray(),wrappedRequest.getCharacterEncoding());}}logger.info("Request URL: {}, Method: {}, IP: {}，params: {}，requestBody: {}", request.getRequestURI(), request.getMethod(), request.getRemoteAddr(), params, requestBody);return true;}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {logger.info("Request to {} has been completed", request.getRequestURI());if (ex != null) {logger.error("An exception occurred during request handling", ex);}}
}

3.性能监控拦截器

  性能监控对于优化系统性能至关重要。性能监控拦截器可以用来计算和记录请求的处理时间，通过分析这些时间数据，我们可以找出系统中的性能瓶颈，进而进行针对性的优化。

@Component
public class PerformanceInterceptor implements HandlerInterceptor {private static final ThreadLocal<Long> startTimeThreadLocal = new ThreadLocal<>();@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {long startTime = System.currentTimeMillis();startTimeThreadLocal.set(startTime);return true;}@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {// 计算请求处理时间long endTime = System.currentTimeMillis();long startTime = startTimeThreadLocal.get();long executeTime = endTime - startTime;System.out.println("Request URL: " + request.getRequestURL() + ", Execution Time: " + executeTime + "ms");}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {startTimeThreadLocal.remove();}
}

4.接口限流拦截器
  在高并发场景下，接口限流是保护系统的重要手段 。接口限流拦截器可以限制单位时间内对某个接口的访问次数，防止因大量请求导致系统资源耗尽，从而保证系统的稳定性和可用性 。

@Component
public class AccessLimitInterceptor implements HandlerInterceptor {@Autowiredprivate RedisTemplate<String, Integer> redisTemplate;@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {if (!(handler instanceof HandlerMethod)) {return true;}HandlerMethod handlerMethod = (HandlerMethod) handler;AccessLimit accessLimit = handlerMethod.getMethodAnnotation(AccessLimit.class);if (accessLimit == null) {return true;}int seconds = accessLimit.seconds();int maxCount = accessLimit.maxCount();boolean needLogin = accessLimit.needLogin();if (needLogin) {// 检查用户登录状态，这里省略具体实现// 如果未登录，返回错误信息return false;}String key = request.getRemoteAddr() + request.getRequestURI();Integer count = redisTemplate.opsForValue().get(key);if (count == null) {redisTemplate.opsForValue().set(key, 1, seconds, TimeUnit.SECONDS);} else if (count < maxCount) {redisTemplate.opsForValue().increment(key, 1);} else {render(response, "请求过于频繁，请稍后再试");return false;}return true;}private void render(HttpServletResponse response, String msg) throws IOException {response.setContentType("application/json;charset=UTF-8");PrintWriter out = response.getWriter();out.write(msg);out.flush();out.close();}@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {}}

5.数据加密解密拦截器
  在数据传输和存储过程中，保护敏感数据的安全至关重要。数据加密解密拦截器可以在请求到达Controller之前对敏感数据进行加密，在响应返回给客户端之前对加密数据进行解密，确保数据在传输和处理过程中的安全性。

  比如在用户登录时，对用户输入的密码进行加密后再传输到服务器。在从数据库中查询用户的身份证号、手机号等敏感信息时，对查询结果进行解密后再返回给前端。

@Component
public class EncryptionInterceptor implements HandlerInterceptor {/*** 密钥*/private static final String KEY = "secret_key";@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {// 假设请求参数中有一个名为"sensitiveData"的敏感数据需要加密String sensitiveData = request.getParameter("sensitiveData");if (sensitiveData != null) {SecretKey secretKey = new SecretKeySpec(KEY.getBytes(), "AES");byte[] encryptedData = AESUtil.encrypt(sensitiveData, secretKey);String encryptedDataStr = Base64.getEncoder().encodeToString(encryptedData);// 将加密后的数据重新放回请求参数中request.setAttribute("sensitiveData", encryptedDataStr);}return true;}@Overridepublic void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {// 假设响应中有一个名为"sensitiveResponseData"的敏感数据需要解密String sensitiveResponseData = (String) request.getAttribute("sensitiveResponseData");if (sensitiveResponseData != null) {SecretKey secretKey = new SecretKeySpec(KEY.getBytes(), "AES");byte[] decodedData = Base64.getDecoder().decode(sensitiveResponseData);String decryptedData = AESUtil.decrypt(decodedData, secretKey);// 将解密后的数据重新放回请求属性中，方便后续处理request.setAttribute("sensitiveResponseData", decryptedData);}}@Overridepublic void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);}
}

五、总结

  在 Spring Boot 开发中，拦截器就像是一把 “万能钥匙”，为我们提供了丰富的功能扩展和业务处理的可能性。

  希望大家在实际项目中，能够根据业务需求，灵活地运用这些拦截器，让我们的 Spring Boot 应用更加健壮、高效、安全。

  同时，拦截器还有很多值得深入探讨的地方，比如如何在拦截器中优雅地处理事务、如何实现更加复杂的动态拦截规则等 ，后续我们可以一起继续探索。

  如果大家在使用拦截器的过程中有任何问题或心得，欢迎在留言区分享交流。