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）：

何時使用本技能

檢查點：判定為「不適用」→ 告知使用者當前問題不在 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 許可權認證開發很有幫助，文件結構清晰、內容全面，核心約束和常見錯誤總結實用，能有效避免踩坑，版本差異說明也很細緻。不過複雜場景的解釋有時不夠直接，搜尋定位特定問題不夠便捷，整體易用性還有提升空間。總體是個好幫手，但使用體驗可以做得更好。