Java搭建Sa-Token权限认证环境指南

本文详细讲解了在 Spring Boot 项目中正确集成 Sa-Token 权限认证框架的四大关键实践：必须使用官方 starter（sa-token-spring-boot-starter）而非手写 Filter，以保障 session 持久化、token 续期和 Spring 生态兼容；需结合注解与显式路由拦截规则实现真正可靠的全局鉴权；务必通过 Redis 桥接配置解决集群部署和性能瓶颈问题；并重点提醒响应头暴露、Cookie 模式选择及跨域 withCredentials 等前端协作细节——每一步都直击开发者踩坑高频点，帮你避开“登录成功却取不到 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 预检通过、实际请求却没校验。

• 启用路由拦截，在配置中设：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 单独包）
• 在配置类中声明 RedisTemplate Bean，并确保泛型是
• 设置 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，自动写入 satoken Cookie
• 若坚持 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 不暴露——这问题不报错，但就是登不进去。

本篇关于《Java搭建Sa-Token权限认证环境指南》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！