Spring Boot 拦截器“白名单”：excludePathPatterns vs @PassToken 注解，谁更胜一筹？✨

Spring Boot拦截器白名单方案对比

原创于 2025-07-21 21:14:52 发布 · 859 阅读

CC 4.0 BY-SA版权

文章标签：

154 篇文章

订阅专栏

“配置白名单” vs “注解式白名单”是一个非常经典、极具探讨价值的架构设计话题。这篇博客将为你深入对比这两种方案的优劣，并完全遵循你的所有格式要求。

嘿，各位后端架构师和 Spring Boot 开发者！👋

在构建安全的 RESTful API (Application Programming Interface, 应用程序接口) 时，使用拦截器 (Interceptor) 来进行统一的 Token (令牌) 校验，是一种优雅而强大的实践。但随之而来的一个问题是：并非所有接口都需要“安检”。

比如：

这时，我们就需要为这些特殊的接口开辟一条“绿色通道”，也就是设置 “白名单”。在 Spring Boot 中，实现这一目标通常有两种主流方式：

集中配置式：在 WebMvcConfigurer 中使用 excludePathPatterns 来排除 URL (Uniform Resource Locator, 统一资源定位符) 路径。
声明式注解：创建一个自定义注解（如 @PassToken），并将其标注在需要放行的 Controller 方法上。

这两种方式都能实现功能，但在可读性、可维护性和耦合度上却有着天壤之别。今天，我们就来一场深度对决，看看哪种方式才是你项目中的“最优解”！

在开始对决之前，我们先用一张表格来快速了解两位“选手”的核心信息。

对比项	方案一：`excludePathPatterns` (集中配置)	方案二：`@PassToken` 注解 (声明式)
实现方式	在 `WebMvcConfigurer` 配置类中，硬编码需要排除的 URL 路径字符串。	创建一个自定义注解，并将其标注在需要放行的 Controller 方法或类上。
核心思想	配置优于约定 (Configuration over Convention)	约定优于配置 (Convention over Configuration)
耦合度	💔 高。配置类与 Controller 的 URL 路径强耦合。	❤️ 低。Controller 的安全策略由自身声明，与外部配置解耦。
可维护性	😥 差。修改 Controller 路径时，极易忘记同步更新配置，导致 Bug。	😊 好。注解与方法绑定，路径修改不影响安全策略。
可读性	🤔 差。无法在 Controller 中直观地看出一个方法的访问权限。	😎 好。一目了然，`@PassToken` 就是一个清晰的“免检”标签。
一句话总结	“全局的交通管制清单”	“每个门口挂的‘请进’牌”

这张图清晰地展示了两种方案在 Spring MVC (Model-View-Controller, 模型-视图-控制器) 处理流程中的不同作用点。

这张图更深入地展示了两种方案在 Spring MVC 内部的交互差异。

想象一下，你重构了一个 Controller，将其路径从 /api/v1/brands 改为了 /api/v1/solution-brands。

使用 excludePathPatterns: 你必须记住去 JwtInterceptorConfig.java 文件中，找到那行硬编码的字符串，并手动更新它。如果忘了，生产环境就会出现 Bug！
使用 @PassToken: 你什么都不用做！注解是跟着方法走的，无论路径怎么变，这个“免检”的特性都牢牢地绑定在方法上。

使用 excludePathPatterns: 当你阅读一个 Controller 方法时，你无法立刻知道它是否需要认证。你必须跳转到全局配置文件去查找，增加了心智负担。
使用 @PassToken: @PassToken 就像一个醒目的标签，直接告诉你：“这个方法是公开的，不需要 Token！” 这就是“代码即文档”的最佳体现。