Sa-Token 开发助手

面向日常 Java 开发的 Sa-Token 编码助手。推荐 1.45.0+（最新稳定版），1.40.x 及以上全线适用，核心 API（StpUtil / SaInterceptor / StpInterface / SaSession 等）保持向后兼容，新版本可能在已有基础上新增方法，本 skill 中的示例在 1.40.x ~ 最新版均可直接使用。历史版本差异已在文中以 v1.xx.0+ 标注。 采用完全本地自包含策略：所有知识沉淀于本地 references/，运行时不依赖任何外部文档站点。

版本与依赖（先判 SpringBoot 版本）

• 切勿同时引入 sa-token-spring-boot-starter 和 sa-token-reactor-spring-boot-starter，项目无法启动。
• Redis 集成：引 sa-token-redis-template + commons-pool2，分布式场景必须。
• SpringBoot 3.x：Redis 前缀从 spring.redis 改为 spring.data.redis。
• 微服务网关用 Reactor 依赖，子服务用 Servlet 依赖，不要在父 pom 统一引入。

何时使用本技能

检查点：判定为「不适用」→ 告知用户当前问题不在 Sa-Token 范围，建议退出本技能。

独特价值

本技能不只是 API 字典，而是 Sa-Token 最佳实践指南：

1. antipattern 纠偏（10-antipattern.md）：28 条 Agent 生成 Sa-Token 代码时的常见错误，每条含「错误写法 → 正确写法 → 为什么」。
2. 强约束：12 条核心规则，Agent 生成代码前必须遵守。
3. 关键决策检查点：6 个关键决策点（JWT 模式 / SSO 模式 / Cookie vs Header / 注解 vs 路由 / 微服务 Session / 多账号），Agent 不可擅自替用户选择，必须先确认方向。
4. 决策树：注解 vs 路由拦截、Cookie vs Header、JWT 三种模式选型、SSO 三种模式选型——均有明确指引。
5. 全本地自包含：SSO、OAuth2、微服务、插件等高级模块全部本地化，无需 web search。

快速判断

常见任务速查

主动行为触发

核心强约束（Agent 必须遵守）

1. 先注册拦截器再用注解：@SaCheck* 注解依赖 SaInterceptor，默认关闭。必须先 registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**") 注册，注解才生效。高版本 SpringBoot（≥2.6.x）可能需额外加 @EnableWebMvc。
2. SaSession ≠ HttpSession：StpUtil.getSession() 返回的 SaSession 与 HttpSession 无任何关系，互不通。用 Sa-Token 时统一使用 SaSession，不要混用。
3. 权限校验后端必须做：前端按钮级权限只是辅助显示，后端接口必须用 StpUtil.checkPermission() 或 @SaCheckPermission 再次校验。
4. 实现 StpInterface 才能鉴权：权限/角色校验依赖 StpInterface 实现类（@Component），返回权限码和角色集合。不实现则所有权限/角色校验通过。
5. timeout vs active-timeout 独立：timeout 是长久有效期（默认 30 天），active-timeout 是最低活跃频率（超时冻结）。两者独立，任一过期 token 不可用。-1 代表永久/不限制。
6. 踢人 vs 注销 vs 顶人不同：logout=正常退出；kickout=被动踢下线（场景值 -5）；replaced=被顶下线（场景值 -4）。is-share 和 is-concurrent 配置影响行为。
7. 封禁需先踢下线：StpUtil.disable(id, time) 不会自动让已登录用户下线。需先 StpUtil.kickout(id) 再 disable。v1.31.0+ login() 不再自动校验封禁，需显式 checkDisable。
8. Starter 不可混用：sa-token-spring-boot-starter（Servlet）和 sa-token-reactor-spring-boot-starter（Reactor）不可同时引入同一项目。
9. 前后端分离需手动传 token：Cookie 模式自动注入；前后端分离（App/小程序）需后端返回 SaTokenInfo，前端塞 header（参数名即 tokenName，默认 satoken）。
10. 过滤器异常不进 @ExceptionHandler：SaServletFilter / SaReactorFilter 中抛出的异常不进入 Spring 全局异常处理器，必须通过 .setError() 处理。
11. Redis 前缀注意版本：SpringBoot 2.x 用 spring.redis.*，SpringBoot 3.x 用 spring.data.redis.*。配错导致连接失败。
12. JWT 三种模式功能差异大：Simple（推荐，支持踢人/Session）、Mixin（不支持踢人/顶人）、Stateless（无 Session，不支持踢人/active-timeout）。按需选择，不要盲目用 Stateless。

关键决策检查点（生成代码前必须确认）

以下场景存在多条技术路线，Agent 不可擅自替用户选择。须先简要说明选项差异，确认方向后再编码。

执行规则：

1. 检测到触发信号 → 先向用户提出确认问题，不要直接生成代码。
2. 用户未明确回答 → 使用「默认推荐」列的策略，但在输出中标注"未确认，已使用默认方案"。
3. 用户确认方向 → 按选择生成代码，不再追问。
4. 一个需求命中多个检查点 → 逐一确认，全部完成后一次性生成代码。

决策路由（全部本地，无在线 fetch）

多场景交叉优先级：当需求同时命中多个 references 时，按下表确定阅读顺序：

组合场景	先读	再读	原因
注解 + 路由拦截	04-annotation.md	05-interceptor-route.md	先确认注解依赖拦截器，再写路由规则
权限 + 注解	03-permission.md	04-annotation.md	先实现 StpInterface，再用注解校验
前后端分离 + 跨域	07-redis-frontsep.md	09-pitfalls.md §6	先确认 token 传递，再处理跨域
Redis + 分布式 Session	07-redis-frontsep.md	06-session.md	先集成 Redis，再理解 Session 模型
踢人/封禁 + 异常处理	08-api-stputil.md	09-pitfalls.md	先确认 API，再处理异常场景值
记住我 + 前后端分离	11-advanced.md §1	07-redis-frontsep.md	先确认记住我机制，再适配前后端分离
SSO + 前后端分离	12-sso-oauth2.md	07-redis-frontsep.md	先选 SSO 模式，再处理 token 传递
微服务 + JWT	13-micro-service.md	14-plugin.md §1	先确认网关架构，再选 JWT 模式
多账号 + JWT	11-advanced.md §6	14-plugin.md §1	先确认多账号体系，再集成 JWT
全局过滤器 + 路由拦截	11-advanced.md §11	05-interceptor-route.md	先理解过滤器 vs 拦截器，再写规则

使用流程

1. 确认 Sa-Token 适用性：看依赖 / StpUtil 使用 / SaInterceptor 注册。不适用 → 告知用户并建议退出；正常 → 继续。
2. 关键决策检查点：查上方「关键决策检查点」表，命中触发信号 → 先向用户确认方向，不要直接生成代码。
3. 定位 reference：查上方「决策路由」表，读对应文件。
4. 编码前看 antipattern：生成代码前必读 10-antipattern.md，对照常见错误。
5. 编码遵循强约束：先看 12 条核心强约束，再读 reference 给代码。
6. 遇异常先查排错：references/09-pitfalls.md。
7. 输出前自检（9 项）：
   • starter 坐标对应 SpringBoot 版本？（2.x / 3.x / 4.x）
   • 命中关键决策检查点？→ 已向用户确认方向（或使用默认方案并标注）
   • 用了 @SaCheck* 注解？→ 确认注册了 SaInterceptor
   • 前后端分离？→ 确认返回了 tokenValue，前端塞 header
   • 用了 SaSession？→ 确认没和 HttpSession 混用
   • 用了 Redis？→ 确认 SpringBoot 版本对应正确前缀（spring.redis vs spring.data.redis）
   • 用了踢人/封禁？→ 确认先 kickout 再 disable
   • 用了过滤器？→ 确认配置了 setError
   • 用了 JWT？→ 确认选对模式（Simple/Mixin/Stateless）

版本注意

• 依赖坐标 cn.dev33:sa-token-*，本地 references 基于 1.45.0 整理，1.40.x 及以上全线适用。
• 前向兼容：Sa-Token 核心 API 保持向后兼容。如遇新版本 API 签名变更，以官方 StpUtil 源码为准；本 skill 未覆盖的新增功能可参考 sa-token.cc 官方文档补充。
• v1.31.0+：StpUtil.login() 不再自动校验账号封禁，需显式 StpUtil.checkDisable()。
• v1.29.0+：StpUtil.renewTimeout(seconds) 可续期 token。
• Reactor 依赖（WebFlux/Gateway）与 Servlet 依赖不可共存。
• sa-token-jwt 显式依赖 hutool-jwt，hutool 5.8.13/5.8.14 存在类型转换问题，建议避开。