《深入理解Spring》拦截器（Interceptor）——请求处理的艺术

最新推荐文章于 2025-12-16 15:49:30 发布
原创 最新推荐文章于 2025-12-16 15:49:30 发布 · 712 阅读 · 10 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#spring #java #后端

1. 引言：拦截器在Web开发中的重要性

在现代Web应用开发中，我们经常需要在请求处理的前后执行一些通用逻辑，例如身份验证、日志记录、性能监控、权限检查等。如果将这些逻辑分散到每个控制器方法中，会导致代码重复、维护困难以及关注点混淆。

Spring拦截器（Interceptor）正是为了解决这一问题而设计的核心组件。它基于AOP（面向切面编程） 思想，允许你在请求到达控制器之前和之后插入自定义逻辑，实现对HTTP请求的精细化控制。

比喻：如果将请求处理比作一场演出，那么拦截器就像是后台的舞台管理人员。他们在演员（控制器）上台前检查服装和道具（预处理），在演出结束后清理舞台和记录表现（后处理），甚至决定是否允许演员登台（拦截）。

2. 拦截器 vs 过滤器：明确边界与职责

在深入拦截器之前，必须明确它与Servlet过滤器的区别和关系。以下是两者的对比：

特性

拦截器 (Interceptor)

过滤器 (Filter)

所属规范

Spring框架特有

Servlet规范标准

依赖关系

依赖于Spring容器

不依赖Spring，属于Web容器

作用范围

只能拦截Controller请求

可以拦截所有HTTP请求（静态资源等）

访问上下文

可以访问Spring的Bean和上下文

只能访问Servlet API

实现复杂度

简单，提供更精细的控制点

相对底层，控制粒度较粗

两者在请求处理流程中的位置关系如下图所示：

image

从图中可以看出，过滤器是Web应用的第一道防线，而拦截器是Spring MVC框架内部的处理机制。

3. 拦截器核心接口与执行流程

3.1 HandlerInterceptor接口详解

Spring拦截器的核心是HandlerInterceptor接口，它定义了三个方法：

public interface HandlerInterceptor {
    // 预处理方法 - 在控制器执行前调用
    default boolean preHandle(HttpServletRequest request, 
                             HttpServletResponse response, 
                             Object handler) throws Exception {
        return true;
    }
    
    // 后处理方法 - 在控制器执行后，视图渲染前调用
    default void postHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler,
                           ModelAndView modelAndView) throws Exception {
    }
    
    // 完成方法 - 在请求完成后调用（视图渲染完成后）
    default void afterCompletion(HttpServletRequest request, 
                                HttpServletResponse response, 
                                Object handler, 
                                Exception ex) throws Exception {
    }
}

3.2 拦截器执行流程深度解析

为了更直观地理解拦截器的执行流程，我们通过一个序列图来展示：

image

关键点说明：

  1. preHandle()方法按拦截器配置顺序执行，返回false时中断流程
  2. postHandle()方法按拦截器配置的逆序执行
  3. afterCompletion()方法同样按配置的逆序执行，无论控制器是否抛出异常都会执行

4. 实战演练：自定义拦截器开发

4.1 创建自定义拦截器

让我们通过几个实际案例来演示如何创建和使用拦截器。

示例1：日志记录拦截器

@Component
public class LoggingInterceptor implements HandlerInterceptor {
    
    private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class);
    
    @Override
    public boolean preHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler) throws Exception {
        long startTime = System.currentTimeMillis();
        request.setAttribute("startTime", startTime);
        
        logger.info("请求开始: URL={}, Method={}, IP={}", 
                   request.getRequestURL(), 
                   request.getMethod(),
                   request.getRemoteAddr());
        
        return true; // 继续执行流程
    }
    
    @Override
    public void postHandle(HttpServletRequest request, 
                          HttpServletResponse response, 
                          Object handler,
                          ModelAndView modelAndView) throws Exception {
        long startTime = (Long) request.getAttribute("startTime");
        long endTime = System.currentTimeMillis();
        long executeTime = endTime - startTime;
        
        logger.info("请求处理完成: URL={}, 执行时间={}ms", 
                   request.getRequestURL(), 
                   executeTime);
    }
    
    @Override
    public void afterCompletion(HttpServletRequest request, 
                               HttpServletResponse response, 
                               Object handler, 
                               Exception ex) throws Exception {
        if (ex != null) {
            logger.error("请求处理异常: URL={}, 异常信息={}", 
                        request.getRequestURL(), 
                        ex.getMessage());
        } else {
            logger.info("请求完全结束: URL={}", request.getRequestURL());
        }
    }
}

示例2：身份验证拦截器

@Component
public class AuthInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler) throws Exception {
        
        // 检查是否是登录相关请求，避免循环拦截
        if (request.getRequestURI().contains("/login")) {
            return true;
        }
        
        // 检查会话中是否有用户信息
        HttpSession session = request.getSession(false);
        if (session == null || session.getAttribute("user") == null) {
            // 未登录，重定向到登录页面
            response.sendRedirect(request.getContextPath() + "/login");
            return false; // 中断请求
        }
        
        return true; // 继续执行
    }
}

4.2 注册与配置拦截器

创建拦截器后，需要通过配置类将其注册到Spring MVC中：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    
    @Autowired
    private LoggingInterceptor loggingInterceptor;
    
    @Autowired
    private AuthInterceptor authInterceptor;
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册日志拦截器，拦截所有请求
        registry.addInterceptor(loggingInterceptor)
                .addPathPatterns("/**") // 拦截所有路径
                .excludePathPatterns("/static/**"); // 排除静态资源
        
        // 注册认证拦截器，拦截特定路径
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/admin/**", "/user/**") // 拦截管理端和用户端
                .excludePathPatterns("/login", "/register", "/error"); // 排除登录注册页
        
        // 可以设置拦截器执行顺序
        registry.addInterceptor(new AnotherInterceptor())
                .addPathPatterns("/**")
                .order(1); // 数字越小优先级越高
    }
}

4.3 测试拦截器效果

编写测试控制器来验证拦截器工作：

@RestController
@RequestMapping("/api")
public class TestController {
    
    @GetMapping("/public/data")
    public ResponseEntity<String> publicData() {
        return ResponseEntity.ok("这是公开数据");
    }
    
    @GetMapping("/private/data")
    public ResponseEntity<String> privateData(HttpSession session) {
        String user = (String) session.getAttribute("user");
        return ResponseEntity.ok("这是私有数据，用户: " + user);
    }
    
    @PostMapping("/login")
    public ResponseEntity<String> login(@RequestParam String username, 
                                       HttpSession session) {
        session.setAttribute("user", username);
        return ResponseEntity.ok("登录成功");
    }
}

使用curl或Postman测试：

# 测试公开接口（应正常返回）
curl http://localhost:8080/api/public/data
# 测试私有接口（应被重定向）
curl http://localhost:8080/api/private/data
# 登录后再测试私有接口
curl -X POST -d "username=testuser" http://localhost:8080/api/login
curl http://localhost:8080/api/private/data

5. 高级应用与最佳实践

5.1 多拦截器执行顺序控制

当有多个拦截器时，执行顺序非常重要：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(interceptorA).order(1); // 最先执行preHandle，最后执行postHandle/afterCompletion
    registry.addInterceptor(interceptorB).order(2);
    registry.addInterceptor(interceptorC).order(3); // 最后执行preHandle，最先执行postHandle/afterCompletion
}

5.2 基于注解的精细化控制

你可以创建自定义注解来实现更精细的拦截控制：

// 定义权限注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiredPermission {
    String[] value() default {};
}
// 在拦截器中检查注解
@Override
public boolean preHandle(HttpServletRequest request, 
                       HttpServletResponse response, 
                       Object handler) throws Exception {
    
    if (handler instanceof HandlerMethod) {
        HandlerMethod handlerMethod = (HandlerMethod) handler;
        RequiredPermission permission = handlerMethod.getMethodAnnotation(RequiredPermission.class);
        
        if (permission != null) {
            // 检查用户是否有所需权限
            String[] requiredPermissions = permission.value();
            if (!hasPermissions(request, requiredPermissions)) {
                response.sendError(HttpStatus.FORBIDDEN.value(), "权限不足");
                return false;
            }
        }
    }
    return true;
}

5.3 异常处理与统一响应

在拦截器中实现统一异常处理：

@Override
public void afterCompletion(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler, 
                           Exception ex) throws Exception {
    if (ex != null) {
        // 记录异常日志
        logger.error("请求处理异常", ex);
        
        // 统一异常响应
        if (!response.isCommitted()) {
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            response.setStatus(HttpStatus.INTERNAL_SERVER_ERROR.value());
            
            Map<String, Object> errorResponse = new HashMap<>();
            errorResponse.put("code", 500);
            errorResponse.put("message", "系统内部错误");
            errorResponse.put("timestamp", System.currentTimeMillis());
            
            response.getWriter().write(new ObjectMapper().writeValueAsString(errorResponse));
        }
    }
}

6. 常见问题与解决方案

6.1 拦截器不生效的可能原因

  1. 配置类未加载：确保配置类被@ComponentScan扫描到
  2. 路径模式错误：检查addPathPatterns和excludePathPatterns配置
  3. 静态资源被拦截：确保排除静态资源路径
  4. 拦截器顺序问题：某些拦截器中断了请求链

6.2 性能优化建议

  1. 避免在preHandle中执行耗时操作：如数据库查询等
  2. 使用缓存：对重复数据进行缓存，如权限信息
  3. 合理设置拦截范围：不要过度使用拦截器，避免不必要的拦截

7. 总结

Spring拦截器是Web开发中极其重要的组件，它提供了以下核心价值：

  1. 代码复用：将横切关注点（如日志、认证、授权）从业务逻辑中分离
  2. 请求预处理：在控制器执行前进行验证、准备数据等操作
  3. 响应后处理：在控制器执行后统一处理响应数据
  4. 流程控制：可以中断请求处理流程，实现权限控制等功能

通过合理使用拦截器，你可以构建出更加健壮、可维护和安全的Web应用程序。掌握拦截器的原理和使用技巧，是每个Spring开发者必备的核心能力。

最佳实践提示：

保持拦截器职责单一，每个拦截器只做一件事

谨慎使用afterCompletion，注意性能影响

对于复杂业务逻辑，考虑使用Spring AOP代替拦截器

始终考虑异常处理情况，确保资源正确释放

java中的拦截器(Interceptor)，详细分析Spring拦截器，如何理解过滤器(Filter)和拦截器(Interceptor)的关系/执行顺序【保姆级教程】
zhangfuping123456789的博客
07-16 1330
拦截器、过滤器
Spring MVC拦截器和跨域请求
热门推荐
qq_53317005的博客
07-20 8万+
Spring MVC拦截器和跨域请求
拦截器（Interceptor）
2301_76161469的博客
06-05 1792
拦截器（Interceptor）是Spring框架提供的核心功能之一，主要用于拦截用户请求，在指定方法前后，根据业务需求执行预先设定的代码拦截器允许开发人员提前预定义一些逻辑，在用户的请求响应前后执行，也可以在用户请求前阻止其执行，在拦截器当中，开发人员可以在应用程序中做一些通用性的操作例如，可以通过拦截器拦截前端发来的请求，判断Session中是否有登录用户的信息，若有，则放行；若没有，则进行拦截在了解了什么是拦截器之后，我们来学习如何实现拦截器。
Mybatis——拦截器Interceptor
娜娜米的博客
05-08 3万+
本篇介绍Mybatis拦截器/插件相关知识，包括相关的类及作用、拦截器有哪几种、拦截器可以在Mybatis的执行过程中的哪些节点起作用、拦截器如何使用、相关的API，最后附上代码示例。
过滤器 Filter vs 拦截器 Interceptor
weixin_64178283的博客
10-03 1610
Filter 和 Interceptor 都是 Spring Boot 应用中不可或缺的请求拦截利器，它们就像城堡的护城河和城门守卫，在不同阶段、不同层面守护着应用的安全。开发者需要根据具体的应用场景选择合适的拦截器，并充分利用 Spring Boot 提供的便捷 API 和灵活的配置，才能构建出安全、高效、用户体验俱佳的 Web 应用。
后端登录校验——Filter过滤器和Interceptor拦截器
m0_73991249的博客
07-09 2127
外部请求是一个乘客，买了一张高铁票要上高铁Filter就是高铁检票的N多个闸机，它就固定在那，你要进去大厅、进站台就得被它拦一次然后DispatcherServlet就是站台，你终于通过重重难关来到站台，等待高铁到来然后坐到座位Interceptor就是检票员，你终于准备要找到高铁座位，准备坐下，Interceptor检票员就动态随机的出现在你面前，要检查你的高铁票，发现你是逃票、站票就让你滚一边呆着，是坐票你就坐着。
Spring 拦截器：详解原理与实战用法，轻松搞定请求拦截
m0_60277481的博客
09-07 1541
摘要：Spring拦截器是SpringMVC框架的核心组件，用于在请求处理的不同阶段（预处理、后处理和完成阶段）插入自定义逻辑。与过滤器相比，拦截器更贴近Spring生态，能精准拦截控制器方法，适合处理权限校验、日志记录等业务逻辑。文章详细解析了拦截器的工作原理、三个核心方法（preHandle、postHandle、afterCompletion）的执行时机，并通过登录权限校验的实战案例，演示了如何实现和配置拦截器。同时对比了拦截器与过滤器的关键区别，帮助开发者合理选择使用场景。
Spring——拦截器（Interceptor）和过滤器（Filter）的使用
程序员阿皓的博客
04-21 484
在Spring中，拦截器（Interceptor）和过滤器（Filter）都是用来处理请求的中间组件，但它们的作用和实现方式有所不同。
Spring Boot拦截器(Interceptor)用法
weixin_45690338的博客
02-27 1127
拦截器(Interceptor)同 Filter 过滤器一样，它俩都是面向切面编程——AOP 的具体实现可以使用 Interceptor 来执行某些任务，例如在 Controller 处理请求之前编写日志，添加或更新配置…Interceptor 作用日志记录、权限检查、性能检测、通用行为1.自定义。
SpringMVC笔记——配置拦截器Interceptor
zxb的博客
04-20 218
SpringMVC 中 拦截器用于拦截控制器方法的执行。
Spring Boot Aspect 切面 AOP 拦截器 Interceptor 监控control请求耗时
03-13
在Spring Boot中，我们可以通过实现`HandlerInterceptor`接口并重写其三个方法——`preHandle()`, `postHandle()`, 和 `afterCompletion()` 来创建自定义的拦截器。 `preHandle()` 方法在目标处理方法调用之前执行...
SpringMVC拦截器——实现登录验证拦截器的示例代码
08-31
在Spring MVC框架中，拦截器（Interceptor）是一种用于处理请求和响应之间通用逻辑的机制，例如权限检查、日志记录等。本示例主要展示了如何创建一个登录验证拦截器，确保只有登录过的用户才能访问特定的页面。 ...
基于Springboot午托管理系统的设计与实现588oe817（程序、源码、数据库、调试部署方案及开发环境）系统界面展示及获取方式置于文档末尾，可供参考。
最新发布
2509_93102599的博客
12-16 826
课题的创新点 业务场景深度融合创新： 并非简单通用的“学生管理系统”，而是深度结合午托机构“招生-日常-财务”的闭环业务流程进行定制化设计，更贴合实际应用。 “管理后台+家长小程序”双端协同创新： 构建机构内部管理与外部家校服务的双向通道，实现管理效率与用户体验的双重提升。 数据驱动的服务优化创新： 通过系统沉淀的考勤、健康、餐饮、费用等多维度数据，为机构提供生源分析、服务质量评估、资源优化配置等数据支持，赋能科学决策。 安全与便捷的平衡创新： 在保障学生隐私和数据安全的前提下，通过预留标准化接口
Spring支持的消费器模式，支持在当前事务提交、或回滚的前、后执行业务操作
m0_37606574的博客
12-11 182
update是业务对象，customer是约定的消费器变量名称。
nl2sql技术实现自动sql生成之Spring AI Alibaba Nl2sql
疾风sxp的博客
12-15 723
上一节我们在介绍了自然语言转sql的基本思路，今天我们通过实操来解决这一技术实现，通过Spring AI Alibaba开源的nl2sql框架进行这块技术的讲解。
日志打印配置：logback-spring.xml配置；info和error完全区分了，并且按时间拆分了
还在活水泥的未来包工头
12-16 106
【代码】日志打印配置：logback-spring.xml配置；info和error完全区分了，并且按时间拆分了。
springboot 1.54 双redis连接池 配置和使用
stregeditor的程序人生
12-12 751
事情原因 我手上主redis 内存不大 ，不想迁移了，重新配置一台redis做额外计算使用，所以打算修改服务增加第二个redis连接配置 ，把新增需求放在第二个redis上计算，废话就不多说，上图和代码。@Qualifier("averageRedisTemplate") // 新增：用于平均值计算的Redis。@Qualifier("rediskqxsTemplate") // 原Redis。// 第二个Redis配置（平均值Redis）// 第一个Redis配置（原Redis）
【面试题-8】Spring/Spring MVC/Spring Boot/Spring Cloud
小何的博客
12-16 1211
【面试题-8】Spring/Spring MVC/Spring Boot/Spring Cloud
SpringBoot 项目 JNI 接口无法注入Bean
Yingtaozi_0的博客
12-10 297
JNI库加载时机：在 SpringBoot 应用启动时通过System.loadLibrary("xxx") 加载本地库，这个操作往往发生在main方法或某个@Configuration类的静态块中，一旦加载完成，C++代码就可能立即注册回调函数，并在后续被触发。：在SpringBoot项目中，需要用到JNI接口调用一段由 C++写的高性能模块，该模块在执行过程中，需要回调 Java 层的某个业务服务Bean，去注入这些业务Bean的时候报错，空指针注入失败。
SpringBoot与SSM整合：拦截器与异常处理详解
4. **拦截器（Interceptor）实现**：拦截器是用于拦截SpringMVC中请求的组件，可以用来实现请求日志记录、权限检查等功能。在SpringBoot中实现拦截器需要定义一个实现了HandlerInterceptor接口的类，并注册到...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

一枚后端工程狮

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值