murraco/spring-boot-jwt：一个把刷新令牌做成有状态的 Spring Boot 认证示例
该项目围绕「murraco/spring-boot-jwt」构建，面向真实业务场景提供可复用的开源实践方案，支持稳定落地与可扩展的项目实践。
秒懂
- 它是什么？
- 这个项目用 Spring Boot 和 Spring Security 实现 JWT 认证，核心设计是短时无状态访问令牌加上可撤销的有状态刷新令牌。它适合作为学习模板，但生产部署前需要你自己补齐安全细节。
- 适合谁用？
- 这个项目适合两类人：一是刚接触 Spring Security 和 JWT 的开发者，想通过一个完整可跑的示例理解令牌认证的流程；二是需要一个极简起点、愿意自己动手加固的团队。不适合直接用于生产环境，因为文档没有提及刷新令牌的存储方式、密钥管理策略或异常处理细节，这些都需要你根据实际部署环境补齐。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 15 天前。
- 用什么语言写的？
- 主要是 Java（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题，给谁用
这个项目解决的是 Spring Boot 应用里最常见的认证需求：用户登录后，客户端拿一个访问令牌访问受保护接口，令牌过期后再用刷新令牌换新的。它把 JWT 的标准流程用 Spring Security 实现了一遍，目标读者是那些想抄作业而不是从零搭框架的 Java 开发者。仓库里没有复杂的业务逻辑，只有一个认证服务加 MySQL 存储，适合作为学习材料或者新项目的第一版骨架。如果你已经熟悉 Spring Security 的过滤器链和 JWT 的签名机制，这个项目提供的东西可能偏基础，但它的刷新令牌设计值得一看。
令牌设计：短命访问令牌加有状态刷新令牌
项目在 README 里明确表态：访问令牌完全无状态，不能撤销，所以故意让它短命；刷新令牌则是有状态的，可以撤销。这个取舍很直接。普通 API 请求只验证访问令牌的签名，不查数据库，吞吐量不受影响。只有刷新令牌过期或者需要撤销时，才去碰数据库。这种设计避免了纯无状态 JWT 的经典痛点：你无法让一个已经签发的令牌立刻失效。代价是刷新令牌必须存储在服务端，这就引入了数据库查询和令牌轮换的逻辑。README 里提到的 trade-off 清单，比如 XSS 风险、访问令牌携带过期权限、文件下载 API 难做，都是 JWT 方案的共性，这个项目没有回避。
认证流程的骨架：从登录到刷新
根据 README 的描述，流程大概是这样的：用户提交凭证，服务端验证后签发一个访问令牌和一个刷新令牌。访问令牌放在 Authorization 头的 Bearer schema 里，格式是 Authorization: Bearer <token>。刷新令牌则用于后续换取新的访问令牌，并且会轮换，旧刷新令牌失效。因为刷新令牌是有状态的，所以服务端能主动撤销它，比如用户登出或者检测到滥用。这个流程没有在 README 里给出完整的时序图，但从描述可以推断，登录接口、刷新接口和受保护资源接口是三个核心端点。项目没有提到令牌的具体过期时间配置，你需要自己看代码确认。
运行方式：克隆、配置、启动
这是一个标准的 Maven 项目，语言是 Java，构建工具是 Maven。要跑起来，你需要先克隆仓库，然后确保本地有 MySQL 实例。项目依赖 Spring Boot 和 Spring Security，数据库配置应该在 application.properties 或 application.yml 里，具体键名 README 没有列出，但通常包括 spring.datasource.url、spring.datasource.username 和 spring.datasource.password。启动命令是 mvn spring-boot:run，或者打包成 jar 后 java -jar 运行。CI 配置在 .github/workflows/ci.yml 里，说明项目至少能通过自动化构建。但 README 没有提供任何 curl 示例或 Postman 集合，你得自己根据代码里的控制器路径来测试。
真正的局限：文档薄，安全细节靠猜
这个项目最大的问题是文档太薄。README 花了大量篇幅介绍 JWT 是什么，却几乎没有说明自己的实现细节。比如刷新令牌存储在 MySQL 的哪张表，字段是什么，如何轮换，这些都没有写。密钥是硬编码在配置文件里还是从环境变量读取，也不得而知。生产环境里，密钥管理、令牌过期策略、异常处理都是关键决策，这里全部留白。另外，README 提到访问令牌不能撤销，所以如果用户被禁用，他手上的访问令牌在过期前依然有效，这是设计使然，但你需要知道这个边界。如果你期望一个开箱即用的安全方案，这个项目会让你失望。
替代方案：从无状态到有状态的谱系
与这个项目形成对比的是完全无状态的 JWT 方案，比如 jjwt 库配合 Spring Security 的经典写法，那种方案里刷新令牌也是无状态的，撤销只能靠黑名单或者干脆不撤销。另一种替代是 Spring Authorization Server，它把 OAuth2 和 JWT 的整套流程标准化，刷新令牌的管理更规范，但学习曲线陡峭。murraco/spring-boot-jwt 选择了中间路线：访问令牌无状态，刷新令牌有状态。这个折中比纯无状态更实用，因为撤销能力是真实需求，但又比 Spring Authorization Server 轻量得多。差别在于，前者需要你自己维护刷新令牌的存储和轮换逻辑，后者已经帮你做好了。
维护与许可证：MIT 下的自由与责任
项目使用 MIT 许可证，意味着你可以自由使用、修改和分发，甚至闭源商用，只要保留版权声明。但仓库没有列出最近的发布版本，也没有说明维护状态，所以你不能指望它频繁更新。依赖的 Spring Boot 版本可能已经过时，你需要自己升级。升级 Spring Security 的版本可能带来破坏性变更，尤其是过滤器链的配置方式。作为示例项目，它的代码量不大，维护成本主要集中在依赖升级和安全隐患修复上。如果你把它用作生产代码，请把许可证声明保留在源码里，并做好自己长期维护的准备。
编辑结论
这个项目适合两类人：一是刚接触 Spring Security 和 JWT 的开发者，想通过一个完整可跑的示例理解令牌认证的流程；二是需要一个极简起点、愿意自己动手加固的团队。不适合直接用于生产环境，因为文档没有提及刷新令牌的存储方式、密钥管理策略或异常处理细节，这些都需要你根据实际部署环境补齐。在采用前，先确认三件事：数据库表结构是否与你的用户模型兼容，刷新令牌的持久化是否满足你的撤销需求，以及 CI 流程中是否覆盖了安全相关的测试。最终判断：这是一个教学价值大于生产价值的示例，它的有状态刷新令牌设计是亮点，但其余部分需要你自行雕琢。
社区笔记