Sa-Token 开发助手

面向日常 Java 开发的 Sa-Token 编码助手。推荐 1.46.0+（最新稳定版），1.40.x 及以上全线适用。版本基准以本声明为准，references 不再重复标注；功能级版本差异已在文中以 v1.xx.0+ 标注。
采用完全本地自包含策略：所有知识沉淀于本地 references/，运行时不依赖任何外部文档站点。

版本与依赖

• 切勿同时引入 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 统一引入。

第 0 步：依赖探测与激活分支

任务涉及登录、注册、认证、鉴权、权限、token、会话、SSO、OAuth2 等编码——即使用户没提 Sa-Token——先检索项目依赖（在 pom.xml / build.gradle 中搜 sa-token、spring-security、shiro）：

何时使用本技能

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

关键决策检查点

以下 6 个场景存在多条技术路线，Agent 不可擅自替用户选择。

执行规则（机械判据，逐条执行）：

1. 拿到任务后、写任何代码前，先扫描用户消息与上下文是否命中下表「触发信号」列的关键词（逐字匹配）。
2. 命中任一检查点 → 本轮回复只做一件事：输出确认问题。禁止输出业务代码块、依赖坐标、配置片段。
3. 确认问题必须是选择题：列出候选方案（A/B/C）+ 标注推荐项 + 一句话理由。禁止开放式提问（如"你想怎么做认证？"）。
4. 用户未明确回答 → 使用「默认推荐」列策略，并在输出开头标注「未确认，已使用默认方案」。
5. 用户确认方向 → 按选择生成代码，不再重复追问。
6. 一个需求命中多个检查点 → 一次性列出全部确认问题，全部完成后才生成代码。

决策路由

核心强约束

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 是可选 token 风格，与有状态/无状态正交：有状态场景默认用 Sa-Token 原生 simple-uuid token 风格 + Redis 即可，无需引入 JWT；仅当用户要 JWT 自包含/可读格式时引入 sa-token-jwt（Simple 模式，JWT + Redis）。无状态场景必须 JWT（StpLogicJwtForStateless，不要 Redis，不支持踢人/active-timeout）。Mixin 才同时需要 JWT + Redis（登录数据内嵌 Token）。不要默认假设用 JWT。

使用流程

1. 确认适用性：先执行「第 0 步：依赖探测与激活分支」，再对照「何时使用本技能」；依赖缺失时主动询问是否引入 Sa-Token，不适用 → 告知用户并建议退出。
2. 关键决策检查点：逐字扫描 C1–C6 触发信号；命中 → 本轮只输出确认选择题，禁止生成代码。
3. 定位 reference：查「决策路由」表，读对应文件。
4. 编码前看 antipattern：对照 10-antipattern.md 常见错误。
5. 编码遵循强约束：先读 12 条核心强约束，再给代码。
6. 遇异常先查排错：references/09-pitfalls.md。
7. 输出前自检（二值核对，任一为「否」即违规，必须返工）：
   - C1–C6 已逐项扫描：命中的检查点均已确认，或已按执行规则 4 标注默认方案？
   - starter 对应 SpringBoot 版本，Servlet / Reactor 未混用？
   - @SaCheck* 使用处已注册 SaInterceptor？
   - 前后端分离场景已返回 tokenValue？
   - SaSession 未与 HttpSession 混用？
   - Redis 前缀对应 SpringBoot 版本？
   - 封禁流程已先 kickout 再 disable，登录前已 checkDisable？
   - 过滤器已配 .setError()？
   - JWT 仅在用户要 JWT 格式或无状态时引入（默认 simple-uuid）？

版本注意

• 前向兼容：新版本 API 签名变更以官方 StpUtil 源码为准，本 skill 未覆盖的新增功能参考 sa-token.com 官方文档。
• 1.46.0 升级必查：StpInterface.isDisabled 改 3 参（11-advanced.md §3.5）；allowLoginIdColon 默认禁 loginId 冒号（09-pitfalls.md §10）；JWT extraData 禁保留字段（14-plugin.md）。
• sa-token-jwt 显式依赖 hutool-jwt，hutool 5.8.13/5.8.14 存在类型转换问题，建议避开。