spring-boot-jwt：從 README 拆解功能、流程與限制
此專案圍繞「murraco/spring-boot-jwt」建置，面向真實業務場景，提供可重複使用、可持續維運的開源實作。
秒懂
- 它是什麼？
- JWT auth service using Spring Boot, Spring Security and MySQL。本文依 murraco/spring-boot-jwt 的 README 整理實際入口、資料流、限制與檢查重點。
- 適合誰用？
- 適合需要 spring-boot-jwt 所處理工作、且能依 murraco/spring-boot-jwt README.md 準備環境與輸入的人；不適合把文件沒有承諾的相容性或效能當成既定事實。採用前先在固定環境執行 README 的安裝、最小範例與測試命令，逐項查看輸出檔、日誌、錯誤返回和權限需求，再按 MIT 檢查使用與分發方式。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 15 天前。
- 用什麼語言寫的？
- 主要是 Java（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
README 定義的問題與邊界：一個帶開發 H2 設定的 Spring Boot 3.5 JWT 服務 0
儲存庫中繼資料將其描述為使用 Spring Boot、Spring Security 和 MySQL 的 JWT 認證服務。README 的技術棧列表顯示 Java 17、Spring Boot 3.5、MySQL、JWT、重新整理權杖和 SpringDoc OpenAPI。預設的開發設定使用記憶體中的 H2 資料庫（test_db）並啟用 H2 主控台；MySQL 的 URL 只出現在註解範例裡。專案目標是 Spring Boot 3.5.x、Java 17+、Spring Security 6、Jakarta EE 命名空間、JJWT 0.12.x 和 SpringDoc。撰寫本文時，儲存庫有 1,686 個星標和 651 個 fork，還有一個未關閉的問題。（本文第 0 個素材切面。）（spring-boot-jwt 素材段落 0-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 0。README 將「README 定義的問題與邊界」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 0-1）
# Spring Boot JWT（spring-boot-jwt 素材段落 0-2）
[](https://github.com/murraco/spring-boot-jwt/actions/workflows/ci.yml)（spring-boot-jwt 素材段落 0-3）
A JWT authentication service 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 0-4）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 0-5）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 6。README 將「README 定義的問題與邊界」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 0-6）
e HMAC algorithm) or a public/private key pair using RSA.（spring-boot-jwt 素材段落 0-7）
Let's explain some concepts of this definition further.（spring-boot-jwt 素材段落 0-8）
Co 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 0-9）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 0-10）
從入口到實際產物：存取權杖與重新整理權杖的流程 1
此 API 實作存取權杖加重新整理權杖的模式。透過 POST /users/signin 登入會回傳 JSON 物件，包含 accessToken、refreshToken、tokenType 和 expiresIn。存取權杖是短時無狀態 JWT，在每次請求中作為 Authorization: Bearer <token> 傳送；重新整理權杖是長期有效的不透明隨機字串，儲存在伺服器端，僅用於取得新的存取權杖。/users/signin、/users/signup、/users/refresh 和 /users/logout 是公開端點，其餘端點都需要有效存取權杖。ROLE_ADMIN 和 ROLE_CLIENT 等角色透過控制器方法上的 @PreAuthorize 強制執行。README 中的序列圖展示登入、受保護請求與重新整理輪換。（本文第 1 個素材切面。）（spring-boot-jwt 素材段落 1-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 1。README 將「從入口到實際產物」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 1-1）
built with Spring Boot and Spring Security, using short-lived access tokens paired with rotating, revocable refresh tok 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 1-2）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 1-3）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 7。README 將「從入口到實際產物」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 1-4）
mpact: Because of their smaller size, JWTs can be sent through a URL, POST parameter, or inside an HTTP header. Additi 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 1-5）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 1-6）
核心資料或元件的連接方式：重新整理權杖設計：不透明、雜湊、單次使用 2
重新整理權杖由 SecureRandom 產生 256 位元隨機數，Base64url 編碼，不攜帶任何聲明；它們的意義只指向資料庫中的對應列。只有 SHA-256 雜湊被儲存在 RefreshToken.tokenHash 中，因此資料庫洩漏不會直接暴露可用權杖。每次重新整理都會消耗目前權杖並回傳新權杖；如果再次出現已消耗的權杖，服務會撤銷該使用者的所有重新整理權杖並拒絕請求，強制重新登入。README 也指出取捨：較短的 JWT_EXPIRE_MS 會縮小被盜存取權杖的有效窗口，但會增加重新整理往返次數。存取權杖本身在過期前無法撤銷。（本文第 2 個素材切面。）（spring-boot-jwt 素材段落 2-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 2。README 將「核心資料或元件的連接方式」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 2-1）
ens.（spring-boot-jwt 素材段落 2-2）
## Stack（spring-boot-jwt 素材段落 2-3）
## Introduction (https://jwt.io)（spring-boot-jwt 素材段落 2-4）
Just to throw some background in, we have a wonderful introduction, co 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 2-5）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 2-6）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 8。README 將「核心資料或元件的連接方式」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 2-7）
onally, the smaller size means transmission is fast.（spring-boot-jwt 素材段落 2-8）
Self-contained: The payload contains all the required informat 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 2-9）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 2-10）
部署與日常操作的摩擦點：安全套件中的核心類別 3
JwtTokenFilter 對除四個未認證端點之外的所有 API 路徑生效，這四個端點透過 shouldNotFilter 跳過而不是簡單 permitAll；原因在於重新整理過期工作階段的使用者通常仍會附帶過期的 Authorization 標頭，而過濾器會直接拒絕無效權杖。該過濾器透過 JwtTokenProvider 解析並驗證權杖，後者負責驗證簽章並擷取身分與授權聲明。RefreshTokenService 管理 issue、rotate、revoke 和 deleteAllForUser；rotate 上標註了 dontRollbackOn = CustomException，這樣重放權杖觸發的例外不會撤銷已經執行的撤銷操作。MyUserDetails 實作 UserDetailsService，WebSecurityConfig 定義 SecurityFilterChain，包含無狀態工作階段、停用 CSRF、requestMatchers，以及將 JWT 過濾器加到 UsernamePasswordAuthenticationFilter 之前。（本文第 3 個素材切面。）（spring-boot-jwt 素材段落 3-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 3。README 將「部署與日常操作的摩擦點」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 3-1）
urtesy of jwt.io! Let’s take a look:（spring-boot-jwt 素材段落 3-2）
### What is JSON Web Token?（spring-boot-jwt 素材段落 3-3）
JSON Web Token (JWT) is an open standard (RFC 751 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 3-4）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 3-5）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 9。README 將「部署與日常操作的摩擦點」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 3-6）
ion about the user, avoiding the need to query the database more than once.（spring-boot-jwt 素材段落 3-7）
### When should you use JSON Web Tokens?（spring-boot-jwt 素材段落 3-8）
H 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 3-9）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 3-10）
用專案命令建立可觀察檢查：執行示範與生產設定 4
README 的設定步驟要求 JDK 17 或更新版本，以及 Maven 3.6.3+，或者使用自帶的 mvnw 包裝器。克隆並執行 mvn install 後，執行 mvn spring-boot:run 會在 8080 埠啟動應用程式。Swagger UI 位於 http://localhost:8080/swagger-ui.html，OpenAPI JSON 位於 /v3/api-docs。啟動時會以冪等方式建立兩個示範使用者：admin/admin123456 和 client/client123456。設定透過環境變數控制：JWT_SECRET（預設 secret-key，僅開發用）、JWT_EXPIRE_MS（預設 300000，五分鐘）和 JWT_REFRESH_EXPIRE_MS（預設 604800000，七天）。README 指出生產環境應設定足夠長的隨機金鑰、停用 H2 主控台並使用真實資料庫。Docker 指令為 docker build -t spring-boot-jwt . 和 docker run -p 8080:8080 spring-boot-jwt。（本文第 4 個素材切面。）（spring-boot-jwt 素材段落 4-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 4。README 將「用專案命令建立可觀察檢查」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 4-1）
9) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 4-2）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 4-3）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 10。README 將「用專案命令建立可觀察檢查」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 4-4）
ere are some scenarios where JSON Web Tokens are useful:（spring-boot-jwt 素材段落 4-5）
Authentication: This is the most common scenario for using 這段內容應與專案的實際檔案和輸出一起閱讀：在 murraco/spring-boot-jwt 專案目錄執行 README.md 列出的安裝或測試命令，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 4-6）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 4-7）
授權、版本與適用情境：測試以及重新整理處理的破壞性變更 5
測試使用 ./mvnw test 執行。UserControllerTest 是基於 @SpringBootTest 和 MockMvc 的整合風格測試，涵蓋登入/註冊、角色保護端點、重新整理輪換、重放權杖拒絕、偵測到重複使用後撤銷整個權杖家族、登出，以及在 Authorization 標頭攜帶失效存取權杖時重新整理。README 也記錄了現有 fork 會遇到的破壞性變更：登入和註冊現在回傳 JSON 權杖對而不是裸字串；GET /users/refresh 被移除，替換為 POST /users/refresh，它接受重新整理權杖且不需要存取權杖；新增 POST /users/logout 用於撤銷重新整理權杖。從 Spring Boot 2.x 升級需要將 javax.* 替換為 jakarta.*、採用 SecurityFilterChain、用 SpringDoc 替換 Springfox、升級到 JJWT 0.12+，並執行在 JDK 17+ 上。（本文第 5 個素材切面。）（spring-boot-jwt 素材段落 5-0）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 5。README 將「授權、版本與適用情境」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 5-1）
This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with th 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 5-2）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 5-3）
這一節把 murraco/spring-boot-jwt 放回它自己的文件脈絡，檢查序號為 11。README 將「授權、版本與適用情境」連到具體的 spring-boot-jwt 工作流程，但文件未說明的作業系統、效能數字、相容版本與權限條件，不能由名稱或同類工具經驗補出結論。素材中明確列出的能力，是本文可以採用的事實範圍。（spring-boot-jwt 素材段落 5-4）
JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, serv 這段內容應與專案的實際檔案和輸出一起閱讀：檢查 murraco/spring-boot-jwt 的 README.md、spring-boot-jwt 設定與命令輸出，記下輸入、產物、錯誤訊息與程序是否正常結束。這個檢查針對 spring-boot-jwt 的入口，不是抽象地測量一個開源專案。（spring-boot-jwt 素材段落 5-5）
對使用者而言，判斷重點是 murraco/spring-boot-jwt 能否在預定環境完成 README 所示的單一任務，以及失敗時是否有可追查的日誌或設定。若要放進既有流程，先把 spring-boot-jwt 的版本、依賴和資料邊界寫進測試案例，再決定是否擴大使用。（spring-boot-jwt 素材段落 5-6）
編輯結論
適合需要 spring-boot-jwt 所處理工作、且能依 murraco/spring-boot-jwt README.md 準備環境與輸入的人；不適合把文件沒有承諾的相容性或效能當成既定事實。採用前先在固定環境執行 README 的安裝、最小範例與測試命令，逐項查看輸出檔、日誌、錯誤返回和權限需求，再按 MIT 檢查使用與分發方式。
社群筆記