吃透 Spring Boot 拦截器!这 6 大核心场景你都用过吗?
在 Spring Boot 开发体系中，拦截器（Interceptor）是堪称 "瑞士军刀" 般的存在。这个诞生于 Spring MVC 框架的核心组件，通过对请求处理全链路的无缝切入，为开发者提供了预处理、后处理的强大能力。本文将深度解析 6 大典型应用场景，带你从入门到精通拦截器的实战技巧。
一、权限校验：构建系统安全第一道防线
在前后端分离架构中，接口权限控制是刚需。拦截器可在请求到达控制器前，完成用户身份验证和权限校验，避免非法请求浪费系统资源。
实现要点：
- 从 HttpServletRequest 获取 token（通常在请求头中）
- 调用认证中心接口验证 token 有效性
- 根据用户角色匹配接口访问权限
java
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
String token = request.getHeader("Authorization");
if (StringUtils.isEmpty(token)) {
sendErrorResponse(response, 401, "未提供认证令牌");
return false;
}
AuthResult authResult = authClient.validateToken(token);
if (!authResult.isValid()) {
sendErrorResponse(response, 403, "无效的认证令牌");
return false;
}
// 将用户信息存入ThreadLocal
UserContextHolder.setCurrentUser(authResult.getUser());
return true;
}
private void sendErrorResponse(HttpServletResponse response,
int status, String message) throws IOException {
response.setStatus(status);
response.setContentType(MediaType.APPLICATION_JSON_VALUE);
try (PrintWriter writer = response.getWriter()) {
writer.write(JSON.toJSONString(Result.error(status, message)));
}
}
}
最佳实践：
- 采用黑白名单机制，对公共接口（如登录、注册）设置排除路径
- 使用 ThreadLocal 存储当前用户信息，方便后续业务逻辑获取
- 结合 Spring EL 表达式实现细粒度权限控制（如 @PreAuthorize）
二、日志追踪：打造全链路请求监控体系
在微服务架构中，请求链路追踪至关重要。拦截器可记录请求的关键信息，为系统调优和故障排查提供依据。
核心功能：
- 记录请求时间、URI、HTTP 方法
- 采集客户端 IP、User-Agent 等环境信息
- 统计接口响应时间
- 记录异常请求堆栈信息
java
public class RequestLogInterceptor implements HandlerInterceptor {
private static final Logger LOGGER = LoggerFactory.getLogger(RequestLogInterceptor.class);
private ThreadLocal<Long> startTime = new ThreadLocal<>();
@Override
public void preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
startTime.set(System.currentTimeMillis());
LOGGER.info("请求开始：{} {}", request.getMethod(), request.getRequestURI());
// 记录请求参数
logParameters(request);
}
private void logParameters(HttpServletRequest request) {
Map<String, String[]> parameterMap = request.getParameterMap();
if (!parameterMap.isEmpty()) {
LOGGER.info("请求参数：{}", parameterMap.entrySet().stream()
.collect(Collectors.toMap(Map.Entry::getKey,
entry -> Arrays.toString(entry.getValue()))));
}
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Exception ex) {
long endTime = System.currentTimeMillis();
LOGGER.info("请求结束：{} 耗时{}ms 状态码{}",
request.getRequestURI(),
endTime - startTime.get(),
response.getStatus());
startTime.remove();
// 记录异常信息
if (ex != null) {
LOGGER.error("请求处理异常：", ex);
}
}
}
进阶应用：
- 结合 MDC（Mapped Diagnostic Context）实现分布式链路追踪
- 使用 AOP 对日志记录逻辑进行二次封装
- 支持日志级别动态配置（开发环境记录详细信息，生产环境简化日志）
三、参数处理：实现请求数据统一格式化
在实际开发中，经常需要对请求参数进行统一处理，比如：
- 字符串去空格、转义
- 日期格式统一转换
- 特殊符号过滤
- 数据格式校验
实现方案：
java
public class ParameterInterceptor implements HandlerInterceptor {
private static final Pattern SPECIAL_CHAR_PATTERN = Pattern.compile("[^a-zA-Z0-9_]");
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
// 处理路径参数
Map<String, String> pathVariables = getPathVariables(request);
processParameters(pathVariables);
// 处理查询参数
Map<String, String[]> queryParams = request.getParameterMap();
processParameters(queryParams);
// 处理表单参数（需要支持PUT/POST等方法）
if (isFormRequest(request)) {
Map<String, String[]> formParams = parseFormParameters(request);
processParameters(formParams);
// 重新封装请求参数
request = new ParameterRequestWrapper(request, formParams);
}
return true;
}
private void processParameters(Map<String, ?> params) {
params.forEach((key, value) -> {
if (value instanceof String) {
String processedValue = SPECIAL_CHAR_PATTERN.matcher((String) value)
.replaceAll("")
.trim();
params.put(key, processedValue);
} else if (value instanceof String[]) {
String[] processedValues = Arrays.stream((String[]) value)
.map(v -> SPECIAL_CHAR_PATTERN.matcher(v).replaceAll("").trim())
.toArray(String[]::new);
params.put(key, processedValues);
}
});
}
}
注意事项：
- 对于 PUT/POST 请求，需要自定义 RequestWrapper 来修改请求参数
- 支持参数校验失败后的统一异常处理
- 结合 @Valid 注解实现更强大的参数校验功能
四、响应封装：实现统一格式的 API 输出
在 RESTful API 设计中，统一的响应格式有助于前后端协作，拦截器可在响应返回前对数据进行统一封装。
标准响应结构：
json
{
"code": 200,
"message": "成功",
"data": { ... }
}
实现步骤：
- 创建响应包装器类
- 在 postHandle 方法中拦截响应内容
- 将原始响应数据封装成标准格式
- 通过 ResponseWrapper 修改输出内容
java
public class ResponseInterceptor implements HandlerInterceptor {
@Override
public void postHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Object responseBody) {
if (responseBody instanceof ResponseEntity) {
ResponseEntity<?> entity = (ResponseEntity<?>) responseBody;
Object body = entity.getBody();
// 封装响应数据
Result result = Result.success(body);
// 重新设置响应体
((HandlerMethod) handler).getMethodAnnotation(ResponseBody.class);
request.setAttribute("RESPONSE_RESULT_ENTITY",
new ResponseEntity<>(result, entity.getHeaders(), entity.getStatusCode()));
}
}
}
高级技巧：
- 支持不同版本 API 的响应格式兼容
- 对下载文件等特殊响应进行排除处理
- 结合 Jackson 自定义序列化规则
五、跨域处理：优雅解决前后端跨域问题
虽然 Spring Boot 提供了 @CrossOrigin 注解，但在复杂场景下，拦截器能提供更灵活的跨域解决方案。
处理流程：
- 检测 OPTIONS 预 flight 请求
- 设置跨域响应头（Access-Control-Allow-Origin、Access-Control-Allow-Methods 等）
- 支持动态跨域白名单配置
java
public class CorsInterceptor implements HandlerInterceptor {
private Set<String> allowedOrigins = new HashSet<>();
public CorsInterceptor(Set<String> allowedOrigins) {
this.allowedOrigins.addAll(allowedOrigins);
}
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
String origin = request.getHeader("Origin");
if (allowedOrigins.contains(origin)) {
response.setHeader("Access-Control-Allow-Origin", origin);
response.setHeader("Access-Control-Allow-Credentials", "true");
response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
response.setHeader("Access-Control-Allow-Headers",
"Authorization, Content-Type, X-Requested-With");
}
// 处理预flight请求
if ("OPTIONS".equals(request.getMethod())) {
response.setStatus(HttpServletResponse.SC_OK);
return false;
}
return true;
}
}
最佳实践：
- 结合 Nginx 实现生产环境的跨域处理
- 支持携带 cookie 的跨域请求
- 实现动态白名单管理（通过数据库或配置中心）
六、性能监控：精准定位系统性能瓶颈
在系统优化过程中，需要对接口性能进行监控，拦截器可方便地实现接口响应时间统计。
实现逻辑：
- 在 preHandle 记录请求开始时间
- 在 afterCompletion 计算响应时间
- 将性能数据输出到日志或发送到监控系统
java
public class PerformanceInterceptor implements HandlerInterceptor {
private static final Map<String, Long> performanceMetrics = new ConcurrentHashMap<>();
private ThreadLocal<Long> startTime = new ThreadLocal<>();
@Override
public void preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
startTime.set(System.currentTimeMillis());
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Exception ex) {
long endTime = System.currentTimeMillis();
long duration = endTime - startTime.get();
String uri = request.getRequestURI();
performanceMetrics.merge(uri, duration, Long::sum);
// 输出性能日志
LOGGER.info("接口性能：{} 耗时{}ms", uri, duration);
startTime.remove();
}
public static Map<String, Long> getPerformanceMetrics() {
return new HashMap<>(performanceMetrics);
}
}
扩展应用：
- 结合 Micrometer 实现与 Prometheus 的集成
- 设置性能阈值，超过阈值发送预警通知
- 支持按时间段统计接口调用次数和平均响应时间
拦截器配置最佳实践
java
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
private final AuthInterceptor authInterceptor;
private final RequestLogInterceptor requestLogInterceptor;
private final ParameterInterceptor parameterInterceptor;
public InterceptorConfig(AuthInterceptor authInterceptor,
RequestLogInterceptor requestLogInterceptor,
ParameterInterceptor parameterInterceptor) {
this.authInterceptor = authInterceptor;
this.requestLogInterceptor = requestLogInterceptor;
this.parameterInterceptor = parameterInterceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(authInterceptor)
.addPathPatterns("/api/**")
.excludePathPatterns("/api/auth/login", "/api/auth/register");
registry.addInterceptor(requestLogInterceptor)
.addPathPatterns("/**");
registry.addInterceptor(parameterInterceptor)
.addPathPatterns("/api/**");
// 其他拦截器配置...
}
}
配置关键点：
- 拦截顺序：先执行 preHandle，后注册的拦截器先执行
- 路径匹配：支持 Ant 风格路径（如 /api/*、/user/**）
- 排除路径：对静态资源、公共接口设置排除
深度思考：拦截器 vs 过滤器
很多开发者会混淆拦截器和过滤器，两者主要区别在于：
特性 | 拦截器 | 过滤器 |
框架层级 | Spring MVC 层 | Servlet 容器层 |
访问对象 | 可访问 Handler 相关对象 | 仅能访问 Servlet 相关对象 |
执行顺序 | 在 DispatcherServlet 之后 | 在 DispatcherServlet 之前 |
依赖注入 | 支持 Spring Bean 注入 | 不支持（需通过 ServletContext 获取） |
应用场景 | 业务逻辑相关处理 | 通用请求处理（编码、安全） |
在实际开发中，应根据需求选择合适的技术方案，两者并非互斥，常配合使用以实现完整的请求处理链路。
总结
Spring Boot 拦截器凭借其灵活的生命周期回调机制，成为构建高效、健壮系统的重要工具。从基础的权限校验到复杂的性能监控，掌握这 6 大核心场景，足以应对 90% 以上的拦截器应用需求。建议开发者在实际项目中，结合具体业务场景进行扩展，打造符合项目需求的拦截器体系。记住，优秀的拦截器设计不仅能提升开发效率，更能为系统的可维护性和扩展性奠定坚实基础。
你在实际开发中遇到过哪些有趣的拦截器应用场景？欢迎在评论区分享你的经验，让我们共同探讨拦截器的更多可能性。
感谢关注【AI码力】，感谢一键三连！