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 {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 在请求处理之前执行的逻辑
        System.out.println("preHandle被调用，请求即将进入Controller");
        return true; // 返回true表示放行请求，返回false则拦截请求
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        // 在请求处理之后，视图渲染之前执行的逻辑
        System.out.println("postHandle被调用，Controller方法已执行完毕，视图即将渲染");
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 在整个请求处理完成，包括视图渲染之后执行的逻辑
        System.out.println("afterCompletion被调用，整个请求已处理完毕");
    }
}

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

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

1.用户认证拦截器

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

@Component
public class JwtHandlerInterceptor implements HandlerInterceptor {

    @Autowired
    private JwtTokenProvider jwtTokenProvider;

    @Autowired
    private UserInfoService userInfoService;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {

        if (!(handler instanceof HandlerMethod)) {
            return true;
        }
        // 取出token
        String 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;
    }


    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);
    }

    @Override
    public 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 {

    @Override
    public 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);

    @Override
    public 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;
    }

    @Override
    public 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<>();

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        long startTime = System.currentTimeMillis();
        startTimeThreadLocal.set(startTime);
        return true;
    }

    @Override
    public 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");
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        startTimeThreadLocal.remove();
    }
}

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

@Component
public class AccessLimitInterceptor implements HandlerInterceptor {

    @Autowired
    private RedisTemplate<String, Integer> redisTemplate;

    @Override
    public 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();
    }
            
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {

    }
            
    @Override
    public 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";

    @Override
    public 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;
    }

    @Override
    public 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);
        }
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);
    }
}

五、总结

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

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

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

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