Sa-Token 拦截器配置与SpringBoot Actuator端点访问问题解析

问题背景

在使用Sa-Token框架进行权限管理时，开发者经常会遇到需要排除某些特定路由不做拦截的情况。特别是在集成SpringBoot Actuator监控端点时，如何正确配置拦截器排除规则成为一个常见问题。

现象描述

开发者在SpringBoot 2.7.18项目中集成了Actuator和Prometheus监控组件，并配置了Sa-Token拦截器。虽然按照预期配置了notMatch("/actuator/**")规则来排除Actuator端点的拦截，但在访问/actuator/prometheus端点时，后台日志仍然出现了token校验相关的错误信息。

问题分析

经过深入排查，发现这个现象背后有几个关键点需要注意：

1. 浏览器行为特性：当访问一个URL时，浏览器会自动发起/favicon.ico请求来获取网站图标。这个请求是独立于原始请求的。

2. 拦截器执行顺序：Sa-Token拦截器会对所有请求进行拦截，包括/favicon.ico请求。如果这个请求没有被正确排除，就会触发token校验。

3. 日志误导：开发者看到的token校验错误实际上是针对/favicon.ico请求的，而非真正的/actuator/prometheus端点请求。

解决方案

要解决这个问题，需要采取以下措施：

1. 完善排除规则：在Sa-Token的notMatch配置中，不仅要排除Actuator端点，还应该排除常见的静态资源请求。

// 正确的排除配置示例
registry.addInterceptor(new SaInterceptor(handler))
    .addPathPatterns("/**")
    .excludePathPatterns("/favicon.ico")
    .excludePathPatterns("/actuator/**");

2. 日志分析技巧：当遇到类似问题时，应该仔细查看日志中的请求路径信息，确认到底是哪个请求触发了拦截。

3. 测试验证方法：使用Postman等工具直接测试API端点，避免浏览器自动请求带来的干扰。

最佳实践

基于这个案例，我们总结出以下Sa-Token拦截器配置的最佳实践：

1. 明确排除规则：对于不需要鉴权的端点，如健康检查、监控端点、静态资源等，应该明确列出排除规则。

2. 分层设计：可以考虑将应用的路由分为API路由和管理路由，分别配置不同的拦截策略。

3. 日志监控：建立完善的日志监控机制，能够清晰区分不同请求的拦截情况。

4. 测试覆盖：编写自动化测试用例，验证拦截规则是否按预期工作。

总结

Sa-Token作为一款优秀的权限认证框架，其拦截器功能强大但需要正确配置。通过这个案例，我们了解到在配置排除规则时需要考虑实际请求链路的完整性，特别是浏览器自动发起的附加请求。合理配置排除规则，既能保证安全性，又能确保监控等系统功能的正常运行。

对于开发者来说，掌握这些配置技巧和排查方法，能够更高效地使用Sa-Token构建安全的应用程序。同时，这也提醒我们在处理类似问题时，要透过现象看本质，从请求链路和日志细节中寻找真正的解决方案。