应使用 sa-token-spring-boot-starter 启动，避免手写 Filter；需配置路由拦截、Redis 桥接及响应头暴露，确保 token 正确传递与集群支持。
直接用 Sa-Token Starter 启动，别手写 Filter
Spring Boot 项目里，Sa-Token 的标准接入方式是引入 sa-token-spring-boot-starter，不是自己写 SaTokenFilter 或手动注册拦截器。手写 Filter 容易漏掉 session 持久化、token 续期、跨域预检支持等细节，而且和 Spring Security 生态不兼容（比如无法自动注入 StpUtil）。
常见错误现象：StpUtil.getLoginId() 在 Controller 里返回 null，但没报错；或登录后刷新页面就掉登录态——大概率是 Filter 没生效或顺序不对。
- 在
pom.xml中添加依赖：sa-token-spring-boot-starter（版本需与 Spring Boot 主版本对齐，如 Boot 3.x 用1.35.0+） - 删掉所有自定义的
Filter、Interceptor注册代码 - 配置项写在
application.yml里，例如：sa-token.token-name: satoken、sa-token.timeout: 2592000 - 启动类无需额外注解，
@SpringBootApplication足够
权限校验别只靠 @SaCheckRole，得配路由拦截规则
@SaCheckRole 和 @SaCheckPermission 是方法级校验，适合细粒度控制，但不能替代全局路由鉴权。如果只加注解，API 被直接绕过 Controller（比如通过网关转发、Feign 调用）时，权限就失效了。
真实使用场景：前后端分离项目中，前端发请求到 /api/user/info，后端必须确保该路径被纳入 Sa-Token 的路由守卫范围，否则 OPTIONS 预检通过、实际请求却没校验。
立即学习“Java免费学习笔记（深入）”；
- 启用路由拦截，在配置中设：
sa-token.is-open-route-check: true - 在
com.pj.satoken.config.SaTokenConfig类里重写addPathPatterns()，明确指定哪些路径需要鉴权，例如：/api/** - 排除静态资源和登录接口：
/login、/favicon.ico、/webjars/**必须加到excludePathPatterns() - 注意路径匹配优先级：通配符
**会覆盖精确路径，/api/user/**要写在/api/**前面才有效
Redis 配置不生效？检查 spring.redis 和 sa-token.redis 是否共用连接池
很多人配了 spring.redis.host，却发现 SaToken 还是走内存模式，日志里出现 redisTemplate is null 或 no redis connection 错误信息。根本原因是 sa-token 默认不复用 Spring 的 RedisTemplate，需显式桥接。
性能影响明显：不用 Redis，所有 token、session、权限数据都存在 JVM 堆里，集群部署直接失效；单机压测 QPS 上不去，GC 压力大。
- 确认已引入
spring-boot-starter-data-redis（不是jedis单独包） - 在配置类中声明
RedisTemplateBean，并确保泛型是<String, Object> - 设置
sa-token.redis: true，并指定sa-token.redis-prefix: satoken:（避免和其他系统 key 冲突） - 如果用 Lettuce，记得加
spring.redis.lettuce.pool.max-active: 20，否则默认 8 个连接在并发场景下容易阻塞
登录成功后拿不到 token？检查响应头和前端取值逻辑
SaToken 默认把 token 放在响应头 satoken 字段里（不是 Authorization），前端如果还按传统 JWT 方式读 response.headers.get('Authorization')，必然取不到。
更隐蔽的问题：某些 HTTP 客户端（如 axios 0.21）默认不暴露自定义响应头，导致 get('satoken') 返回 null，但控制台无报错。
- 后端可改用 Cookie 模式：配置
sa-token.token-mode: cookie，自动写入satokenCookie - 若坚持 Header 模式，前端需显式设置
Access-Control-Expose-Headers: satoken（后端配置 CORS 时加上） - 登录接口返回体不要包装成
{ code: 0, data: { token: "xxx" } }——SaToken不解析 body，只认 header 或 cookie - 调试时用 curl 直接看响应头：
curl -i http://localhost:8080/login，确认satoken:行存在且非空
最常被忽略的是跨域场景下 withCredentials: true 没开，导致 Cookie 不携带、Header 不暴露——这问题不报错，但就是登不进去。
