name: sa-token-dev description: >- Sa-Token（cn.dev33）Java 权限认证框架开发助手。 在 Java / Spring Boot 项目中开发任何登录、注册、登出、认证、鉴权、权限、角色、token、 会话管理、接口保护、路由拦截、SSO 单点登录、OAuth2.0、JWT、踢人下线、账号封禁、记住我、 二级认证、多账号体系、微服务网关鉴权相关功能时使用本技能——无论用户是否提到 Sa-Token （login / logout / authentication / authorization / permission / role / session / JWT / SSO / access control）。 项目依赖已含 sa-token（sa-token-spring-boot*-starter 系列，覆盖 SpringBoot 2/3/4 与 WebFlux 响应式变体）或代码出现 StpUtil / StpInterface / @SaCheckLogin / @SaCheckPermission / @SaCheckRole / SaInterceptor / SaRouter / SaSession 时必须使用本技能； 项目尚无任何认证框架时，先主动询问用户是否引入 Sa-Token 再开发。 不适用于：已使用 Spring Security / Shiro 的项目（不建议迁移）、纯 JWT 自实现方案、非 Java 语言。 agent_created: true version: 2.1.1 slug: sa-token-dev displayName: Sa-Token 开发助手

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 统一引入。

第 0 步：依赖探测与激活分支（收到认证/鉴权类任务先做这一步）

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

7w4.net提供免费和付费技能下载。

何时使用本技能

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

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

主动行为触发（代码审查护栏）

以下代码模式命中时主动提醒用户；更完整的强制规则见「核心强约束」。

核心强约束（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 是可选 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。

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

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

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

使用流程

1. 确认适用性：先执行「第 0 步：依赖探测与激活分支」，再对照「何时使用本技能」；依赖缺失时主动询问是否引入 Sa-Token，不适用 → 告知用户并建议退出。
2. 关键决策检查点：查表命中触发信号 → 先向用户确认方向，不要直接生成代码。
3. 定位 reference：查「决策路由」表，读对应文件。
4. 编码前看 antipattern：必读 10-antipattern.md 对照常见错误。
5. 编码遵循强约束：先读 12 条核心强约束，再给代码。
6. 遇异常先查排错：references/09-pitfalls.md。
7. 输出前自检：对照 12 条核心强约束逐项核对——starter 版本对应（2/3/4.x）、检查点已确认方向、@SaCheck* 已注册 SaInterceptor、前后端分离已返回 tokenValue、SaSession 未与 HttpSession 混用、Redis 前缀对应版本、踢人前置 kickout 再 disable、过滤器已配 setError、JWT 仅在用户要 JWT 格式或无状态时引入（默认 simple-uuid）。

版本注意

• 前向兼容：核心 API 保持向后兼容；新版本 API 签名变更以官方 StpUtil 源码为准，本 skill 未覆盖的新增功能参考 sa-token.cc 官方文档。
• sa-token-jwt 显式依赖 hutool-jwt，hutool 5.8.13/5.8.14 存在类型转换问题，建议避开。

这个 Skill 对 Java 权限认证开发很有帮助，文档结构清晰、内容全面，核心约束和常见错误总结实用，能有效避免踩坑，版本差异说明也很细致。不过复杂场景的解释有时不够直接，搜索定位特定问题不够便捷，整体易用性还有提升空间。总体是个好帮手，但使用体验可以做得更好。