
Sa-Token 自定義 Token 風格完全指南六種內置樣式與 createToken 策略重寫實戰【免費下載鏈接】Sa-Token? 開源、免費、一站式 Java 權限認證框架讓鑒權變得簡單、優雅—— 登錄認證、權限認證、分布式 Session 會話、微服務網關鑒權、SSO 單點登錄、OAuth2.0 統一認證、jwt 集成、API Key 秘鑰授權、API 參數簽名項目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本篇技術指南聚焦 Sa-Token 權限認證框架的 Token 生成風格定制默認情況下框架以 UUID 作為登錄憑證而你只需一行配置即可切換為隨機字符串、tik 風格等內置樣式甚至可以重寫框架策略類SaStrategy的createToken算法實現完全自定義的 Token 生成規則。讀完本文你將掌握sa-token.token-style全部取值及其背后的源碼實現、配置文件的三種寫法以及一套可直接復制運行的自定義 Token 生成策略并理解改了不生效這類問題的根因。一、Token 在 Sa-Token 中的角色與生成時機Sa-Token 是輕量級 Java 權限認證框架其核心模型是登錄成功后由框架生成一段不透明字符串即 Token返回給前端前端后續請求攜帶該 Token框架據此識別登錄身份。因此Token 的生成算法直接決定了憑證的形態、長度與安全特征。從源碼調用鏈看StpUtil.login(...)最終會走到StpLogic的createTokenValue方法public String createTokenValue(Object loginId, String deviceType, long timeout, MapString, Object extraData) { return SaStrategy.instance.createToken.apply(loginId, loginType); }即Token 的實際生成邏輯被抽象為SaStrategy.instance.createToken這個策略函數框架內置了基于tokenStyle配置的默認實現也允許開發者整體替換。這條調用鏈定義于 StpLogic.java理解它是掌握本文全部內容的前提。二、內置 Token 風格六種取值一覽Sa-Token 默認的 Token 生成策略是 uuid 風格模樣類似于623368f0-ae5e-4475-a53f-93e4225f16ae。如果對這種風格不滿意只需在配置文件里設置sa-token.token-style風格類型即可切換內置六種取值如下對應原文完整示例值// 1. token-styleuuid —— uuid風格 (默認風格) 623368f0-ae5e-4475-a53f-93e4225f16ae // 2. token-stylesimple-uuid —— 同上uuid風格, 只不過去掉了中劃線 6fd4221395024b5f87edd34bc3258ee8 // 3. token-stylerandom-32 —— 隨機32位字符串 qEjyPsEA1Bkc9dr8YP6okFr5umCZNR6W // 4. token-stylerandom-64 —— 隨機64位字符串 v4ueNLEpPwMtmOPMBtOOeIQsvP8z9gkMgIVibTUVjkrNrlfra5CGwQkViDjO8jcc // 5. token-stylerandom-128 —— 隨機128位字符串 nojYPmcEtrFEaN0Otpssa8I8jpk8FO53UcMZkCP9qyoHaDbKS6dxoRPky9c6QlftQ0pdzxRGXsKZmUSrPeZBOD6kJFfmfgiRyUmYWcj4WU4SSP2ilakWN1HYnIuX0Olj // 6. token-styletik —— tik風格 gr_SwoIN0MC1ewxHX_vfCW3BothWDZMMtx__各風格特性歸納如下token-style 取值說明長度字符構成uuidUUID 標準格式含 4 個中劃線默認風格3616 進制字符 -simple-uuidUUID 去掉中劃線的緊湊形態3216 進制字符random-32隨機 32 位字符串32大小寫字母 數字random-64隨機 64 位字符串64大小寫字母 數字random-128隨機 128 位字符串128大小寫字母 數字tik形如xx_xxxxxxxxxxxxxx_xxxxxxxxxxxxxxxx__的分段風格34三段隨機串 _連接符其中 tik 風格在源碼中的拼裝規則為2 位隨機串 _ 14 位隨機串 _ 16 位隨機串 __即2_14_16結構見 SaStrategy.java。1. 三種配置寫法token-style屬于SaTokenConfig配置項可通過 yml、properties 或 Java 代碼任意一種方式設置# application.yml sa-token: token-style: random-32# application.properties sa-token.token-stylerandom-32// Java 代碼方式例如在配置類中 SaManager.getConfig().setTokenStyle(random-32);該配置項在 SaTokenConfig.java 中定義默認值為uuid完整配置清單可參考 配置文件說明。2. 內置風格的底層實現SaStrategy的默認createToken實現是一個基于tokenStyle的 switch 分支見 SaStrategy.javapublic SaCreateTokenFunction createToken (loginId, loginType) - { // 根據配置的tokenStyle生成不同風格的token String tokenStyle SaManager.getStpLogic(loginType).getConfigOrGlobal().getTokenStyle(); switch (tokenStyle) { case SaTokenConsts.TOKEN_STYLE_UUID: // uuid return UUID.randomUUID().toString(); case SaTokenConsts.TOKEN_STYLE_SIMPLE_UUID: // 簡單uuid (不帶下劃線) return UUID.randomUUID().toString().replaceAll(-, ); case SaTokenConsts.TOKEN_STYLE_RANDOM_32: // 32位隨機字符串 return SaFoxUtil.getRandomString(32); case SaTokenConsts.TOKEN_STYLE_RANDOM_64: // 64位隨機字符串 return SaFoxUtil.getRandomString(64); case SaTokenConsts.TOKEN_STYLE_RANDOM_128: // 128位隨機字符串 return SaFoxUtil.getRandomString(128); case SaTokenConsts.TOKEN_STYLE_TIK: // tik風格 (2_14_16) return SaFoxUtil.getRandomString(2) _ SaFoxUtil.getRandomString(14) _ SaFoxUtil.getRandomString(16) __; default: // 默認還是uuid SaManager.getLog().warn(配置的 tokenStyle 值無效{}僅允許以下取值: uuid、simple-uuid、random-32、random-64、random-128、tik, tokenStyle); return UUID.randomUUID().toString(); } };風格名稱常量統一定義在 SaTokenConsts.javaTOKEN_STYLE_UUID、TOKEN_STYLE_SIMPLE_UUID、TOKEN_STYLE_RANDOM_32、TOKEN_STYLE_RANDOM_64、TOKEN_STYLE_RANDOM_128、TOKEN_STYLE_TIK常量與配置字符串一一對應。3. 隨機串的強度基于 CSPRNG三種 random 風格與 tik 風格都依賴工具方法SaFoxUtil.getRandomString(length)見 SaFoxUtil.java。其實現從 62 個字符大小寫字母 數字的字符池中逐位取樣隨機源使用SecureRandom即密碼學安全偽隨機數生成器CSPRNG線程安全且可靜態共享源碼第 45-46 行聲明。這意味著即使換成隨機字符串風格Token 依然具備足夠的不可預測性可用于登錄憑證場景。4. 無效配置值的回退行為從上述 switch 的default分支可以看出一個容易被忽略的行為當token-style被設置為合法值之外的字符串時框架不會拋異常而是打印一條 warn 日志并回退到 uuid 風格。這一行為同時被單元測試覆蓋見 SaStrategyTest.java測試逐一切換六種風格并斷言長度/形態如simpleUuid長度為 32 且不含-、tik以__結尾最后設置invalid-style斷言回退結果仍包含-即 UUID。如果你想用測試來驗證自己的配置是否生效這是現成的參考用例。三、自定義 Token 生成策略重寫 SaStrategy.createToken如果以上六種風格都不是你喜歡的類型Sa-Token 允許完全自定義 Token 生成策略——只需重寫策略類SaStrategy的createToken算法即可。這是框架策略模式能力的體現SaStrategy統一定義了框架內關鍵邏輯算法創建 Token、創建 Session、路由匹配、CORS 處理等全部支持按需替換。1. 參考步驟配置類中重寫第一步在SaTokenConfigure配置類中添加代碼Configuration public class SaTokenConfigure { /** * 重寫 Sa-Token 框架內部算法策略 */ PostConstruct public void rewriteSaStrategy() { // 重寫 Token 生成策略 SaStrategy.instance.createToken (loginId, loginType) - { return SaFoxUtil.getRandomString(60); // 隨機60位長度字符串 }; } }第二步再次調用StpUtil.login(10001)方法進行登錄觀察其生成的 token 樣式gfuPSwZsnUhwgz08GTCH4wOgasWtc3odP4HLwXJ7NDGOximTvT4OlW19zeLH如上例所示重寫后登錄得到的 Token 是 60 位隨機字符串說明自定義策略已生效。2. 策略函數的簽名與等價寫法createToken是一個函數式接口SaCreateTokenFunction簽名接收兩個參數loginId當前登錄的賬號 idloginType賬號類型多賬號體系下區分登錄場景如login、admin。除了直接對字段賦值框架還提供了setCreateToken連綴式方法二者等價且setXxx返回SaStrategy自身便于鏈式調用多個重寫見 SaStrategy.javaSaStrategy.instance .setCreateToken((loginId, loginType) - SaFoxUtil.getRandomString(60)) .setCreateSession((sessionId) - new SaSession(sessionId));注意SaStrategy是全局單例public static final SaStrategy instance重寫策略會影響整個應用的 Token 生成行為請確保在應用啟動早期如PostConstruct完成重寫。3. 登錄參數對生成結果的影響自定義策略雖然接管了生成算法但唯一性校驗與最大重試次數仍由框架負責。在StpLogic中登錄流程會先經過generateUniqueToken包裝見 StpLogic.javareturn SaStrategy.instance.generateUniqueToken.execute( token, maxTryTimes, () - createTokenValue(...), token - ...);generateUniqueToken的默認實現見 SaStrategy.java會循環生成 Token → 若maxTryTimes -1直接返回不校驗唯一性→ 否則查庫確認 Token 未被占用才返回 → 循環maxTryTimes次仍未成功則拋出SaTokenException生成算法過于簡單或資源池已耗盡。maxTryTimes默認值為 12見 SaTokenConfig.java因此即使自定義算法出現小概率重復框架也會自動重試保證唯一你可以放心自定義。4. 踩坑提示改完不生效::: warning 更改了 token 生成策略但是不生效 把 Redis 中的舊數據清除掉再試試 :::原因在于Sa-Token 采用Token 即 key的存儲模型登錄后 Token 會被寫入 Sa-Token 的持久化層內存 Map 或 Redis舊 Token 只要未過期就一直有效。因此切換風格/策略只影響之后新創建的 Token想讓改動立即全局生效需要清除存儲中的舊數據如清空 Redis 中相關 key、重啟內存模式的應用前端同時丟棄本地緩存的舊 TokenCookie/LocalStorage/Header若使用 Redis 集成還需確認序列化層如 sa-token-redis-jackson、sa-token-redisson與你的緩存淘汰策略避免舊 key 殘留。四、源碼級問答進一步理解 Token 風格機制Q1token-style 配置在哪讀取SaStrategy默認實現通過SaManager.getStpLogic(loginType).getConfigOrGlobal().getTokenStyle()讀取即優先取該loginType的獨立配置取不到再回退到全局配置支持多賬號體系下不同登錄類型使用不同 Token 風格。Q2自定義策略能拿到登錄上下文嗎可以。createToken的入參loginId、loginType正是當前登錄上下文的關鍵信息你可以基于它們做差異化生成例如不同loginType返回不同長度或不同前綴的 Token。Q3Token 風格與 token-prefix 是什么關系二者職責不同token-style決定 Token本體的生成形態而token-prefix是提交 Token 時約定的固定前綴如Bearer xxxx與 token 本身無關。前者控制生成什么樣后者控制怎么提交/識別。Q4換成短隨機串安全嗎random-3232 位、62 字符集理論空間為 62^32配合generateUniqueToken的唯一性校驗在常規業務場景下足夠安全若對安全性有更高要求可選用random-64/random-128或按上文方案自定義更長更復雜的算法。五、總結本文完整覆蓋了 Sa-Token Token 風格的三個層次開箱即用六種內置風格一行配置切換、深度定制重寫SaStrategy.instance.createToken算法、原理透底switch 分發、CSPRNG 隨機源、generateUniqueToken唯一性兜底、無效值回退與舊數據緩存問題。從 SaStrategy.java 到 StpLogic.java再到 SaStrategyTest.java 中的測試用例一條完整的配置 → 策略 → 生成 → 校驗鏈路清晰可查。無論你的訴求是換個好看的 Token 格式還是接入公司統一的安全隨機串規范本文的配置與代碼均可直接復制落地。【免費下載鏈接】Sa-Token? 開源、免費、一站式 Java 權限認證框架讓鑒權變得簡單、優雅—— 登錄認證、權限認證、分布式 Session 會話、微服務網關鑒權、SSO 單點登錄、OAuth2.0 統一認證、jwt 集成、API Key 秘鑰授權、API 參數簽名項目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token創作聲明:本文部分內容由AI輔助生成(AIGC),僅供參考