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单独包) - 在配置类中声明
RedisTemplateBean,并确保泛型是 - 设置
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 不暴露——这问题不报错,但就是登不进去。
本篇关于《Java搭建Sa-Token权限认证环境指南》的介绍就到此结束啦,但是学无止境,想要了解学习更多关于文章的相关知识,请关注golang学习网公众号!
Go test命令怎么用?Golang单元测试全攻略
- 上一篇
- Go test命令怎么用?Golang单元测试全攻略
- 下一篇
- Linux设置SUID和SGID权限详解
-
- 文章 · java教程 | 1天前 | 反射 · Java教程 · java MethodHandle MethodHandles.filterArguments 参数适配
- Java MethodHandles.filterArguments 怎样按位置预处理方法参数
- 128浏览 收藏
-
- 文章 · java教程 | 1天前 |
- Java Key Encapsulation Mechanism API 怎样封装共享密钥
- 127浏览 收藏
-
- 文章 · java教程 | 1天前 |
- Java String Templates 为什么仍要关注模板处理器边界
- 263浏览 收藏
-
- 文章 · java教程 | 1天前 | 线程 · 并发编程 · Java教程 · java Thread.onSpinWait 自旋等待 线程可见性
- Java Thread.onSpinWait 怎样给自旋等待循环降成本
- 311浏览 收藏
-
- 文章 · java教程 | 1天前 |
- Java Locale.stripExtensions 怎样去掉扩展标签保留基础地区
- 474浏览 收藏
-
- 文章 · java教程 | 1天前 |
- Java StructuredTaskScope.Subtask.state 怎样区分未完成、成功与失败
- 137浏览 收藏
-
- 文章 · java教程 | 1天前 |
- Java Currency getNumericCodeAsString 怎样保留货币编号前导零
- 194浏览 收藏
-
- 文章 · java教程 | 1天前 | Java教程 · java 国际化 locale getDisplayCountry 地区名称
- Java Locale getDisplayCountry 怎样按指定语言显示地区名称
- 262浏览 收藏
-
- 文章 · java教程 | 1天前 | Java教程 · java 小程序 Java 25 Compact Source Files main 方法
- Java 25 Compact Source Files 怎样减少小程序样板代码
- 131浏览 收藏
-
- 文章 · java教程 | 1天前 | Java教程 · java Switch instanceof 装箱 Java 25 Primitive Types in Patterns
- Java 25 Primitive Types in Patterns 怎样避免模式匹配中的装箱误判
- 465浏览 收藏
-
- 文章 · java教程 | 2天前 | 并发编程 · Java教程 · java 结构化并发 ScopedValue ScopedValue.where 动态作用域
- Java ScopedValue.where 怎样在调用范围内绑定值
- 447浏览 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 485次学习
-
- PubMedQA
- 深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
- 1166次使用
-
- H2O EvalGPT
- H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
- 1151次使用
-
- LMArena
- LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
- 1329次使用
-
- HELM
- 深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
- 1268次使用
-
- MMBench
- MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
- 1126次使用
-
- Java 时间格式兼容多个输入格式的方法
- 2026-10-18 501浏览
-
- Java try-with-resources 多个资源关闭顺序是什么
- 2026-09-10 501浏览
-
- 矩阵主副对角线快速定位技巧
- 2026-05-31 501浏览
-
- Java多态优化流程代码与行为分发改进
- 2026-05-26 501浏览
-
- JVM 类元数据双亲委派链表深度解析
- 2026-05-21 501浏览

