Sa-Token 如何忽略鉴权？三种方式让你灵活放行接口！

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！

在使用Sa-Token做权限控制时，我们通常希望：

• /login、/register、/health等接口无需登录即可访问；
• Swagger 文档、静态资源、验证码接口跳过鉴权；
• 某些临时调试接口暂时关闭权限校验。

但如果你配置了全局拦截器，所有请求都会被拦截，返回401 Unauthorized！

怎么办？

本文将教你三种官方推荐方式，安全、灵活地忽略 Sa-Token 鉴权，并附上完整 Spring Boot 示例 + 反例避坑指南！

🧩 一、前提：你已配置全局拦截器

假设你已经注册了 Sa-Token 的全局路由拦截器（这是最佳实践）：

@Configuration public class SaTokenConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SaRouteInterceptor()) .addPathPatterns("/**"); // 拦截所有请求 } }

此时，所有接口都需要登录才能访问。我们需要“放行”部分路径。

✅ 方法一：excludePathPatterns（推荐！最常用）

在注册拦截器时，直接排除不需要鉴权的路径。

@Configuration public class SaTokenConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SaRouteInterceptor()) .addPathPatterns("/**") .excludePathPatterns( "/login", "/register", "/captcha", "/health", "/doc.html", "/webjars/**", "/swagger-resources/**", "/v3/api-docs/**" ); } }

✅优点：配置清晰、性能高、无侵入
🔥适用场景：公开接口、文档、健康检查等

✅ 方法二：@SaIgnore 注解（方法级忽略）

如果你只想忽略某个 Controller 方法，可以用@SaIgnore注解。

1. 确保你的 Sa-Token 版本 ≥ 1.25.0

2. 在方法上加注解

@RestController public class PublicController { @SaIgnore // ← 忽略 Sa-Token 鉴权 @GetMapping("/public/hello") public String hello() { return "无需登录也能访问！"; } @SaIgnore @PostMapping("/register") public String register(@RequestBody User user) { // 注册逻辑 return "注册成功"; } }

✅优点：精准控制，适合临时放行
⚠️注意：该注解只对 SaRouteInterceptor 生效，对自定义拦截器无效！

✅ 方法三：在拦截器中手动放行（高级用法）

如果你有复杂的放行逻辑（比如根据 IP、Header 动态判断），可以在自定义拦截器中处理。

public class CustomSaInterceptor extends SaRouteInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String uri = request.getRequestURI(); // 自定义放行规则 if (uri.startsWith("/api/open/") || isWhiteIp(request)) { return true; // 直接放行，不执行父类鉴权 } // 否则走正常 Sa-Token 鉴权 return super.preHandle(request, response, handler); } private boolean isWhiteIp(HttpServletRequest request) { String ip = request.getRemoteAddr(); return "127.0.0.1".equals(ip) || "192.168.1.100".equals(ip); } }

然后注册这个自定义拦截器：

@Configuration public class InterceptorConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new CustomSaInterceptor()) .addPathPatterns("/**"); } }

✅适用场景：IP 白名单、内部系统调用、灰度发布等

⚠️ 四、反例：错误的忽略方式（千万别用！）

❌ 反例1：在 Controller 里 try-catch 绕过

@GetMapping("/test") public String test() { try { StpUtil.checkLogin(); // 手动校验 } catch (Exception e) { // 忽略异常 → 表面上能访问，但逻辑混乱！ } return "xxx"; }

问题：

• 代码冗余；
• 无法统一管理；
• 容易漏掉权限校验。

❌ 反例2：全局不注册拦截器，靠每个方法手动 check

@GetMapping("/user") public String user() { StpUtil.checkLogin(); // 每个方法都写 return "..."; }

后果：

• 极易遗漏；
• 后期维护成本高；
• 违背“约定优于配置”原则。

✅ 正确做法：用 excludePathPatterns 或 @SaIgnore！

🔒 五、安全注意事项

1. 不要过度放行
   例如：excludePathPatterns("/**")→ 等于没鉴权！

2. 敏感接口即使公开也要做参数校验
   比如/register虽然免登录，但要防刷、防注入。

3. Swagger 路径要放全
   常见遗漏：

   - /v3/api-docs - /swagger-ui/** - /doc.html - /webjars/springfox-swagger-ui/**

4. 生产环境关闭调试接口
   可通过 profile 控制：

   @Profile("dev") @SaIgnore @GetMapping("/debug/clear-cache") public String clear() { ... }

🧪 六、完整示例项目结构

src/main/java └── com.example.satoken ├── config/SaTokenConfig.java ← 拦截器配置 ├── controller │ ├── AuthController.java ← /login（放行） │ ├── UserController.java ← /user/info（需登录） │ └── PublicController.java ← /public/hello（@SaIgnore） └── SatokenApplication.java

测试流程：

1. 访问/login→ 成功（放行）
2. 访问/user/info→ 返回 401（未登录）
3. 登录后携带 token 访问/user/info→ 成功
4. 访问/public/hello→ 无需 token 也能访问

🎯 总结：如何选择忽略方式？

记住：鉴权要严，放行要明！合理使用忽略机制，既能保证安全，又不失灵活性。

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！