企业官网建设流程全解析

Sa-Token 源码仓库目录全解析：核心模块、整合层、插件体系与示例合集的代码地图

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token

Sa-Token 是一个开源、免费的 Java 权限认证框架，本仓库即其完整源码工程。本文以仓库目录为主线，逐层拆解每一个模块的职责定位、依赖关系与典型用法，帮助读者快速建立"从目录到能力"的源码导航：读完本文，你将掌握 Sa-Token 核心包与 SpringBoot/Solon/JFinal 等整合层、Redis/JSON/JWT/SSO/OAuth2 等插件层、几十个示例工程和测试工程的分布规律，能够在阅读源码、调试问题、按需集成时精准定位到对应模块。

一、仓库总览：一个多模块 Maven 工程如何组织

Sa-Token 采用标准的 Maven 多模块聚合工程结构，顶级 pom.xml 通过<modules>声明了全部一级模块，当前仓库快照版本为1.46.0（由revision属性统一管理）：

sa-token ├── sa-token-core // [核心] Sa-Token 核心模块 ├── sa-token-dependencies // [依赖] Sa-Token 依赖版本信息 ├── sa-token-special-dependencies // [依赖] Sa-Token 特殊依赖（SpringBoot2/3/4 版本隔离） ├── sa-token-bom // [核心] Sa-Token bom 包 ├── sa-token-starter // [整合] Sa-Token 与其它框架整合 ├── sa-token-plugin // [插件] Sa-Token 插件合集 ├── sa-token-demo // [示例] Sa-Token 示例合集 ├── sa-token-testing // [测试] Sa-Token 测试合集 ├── sa-token-doc // [文档] Sa-Token 开发文档 ├── sa-token-doc-new // [文档] Sa-Token 新版开发文档站 ├── pom.xml // [依赖] 顶级 pom 文件 ├── LICENSE // 开源协议 ├── mvn clean.bat // 一键 mvn clean 核心包+所有示例包 ├── mvn test.bat // 一键单元测试 ├── mvn-coverage.bat // 一键生成测试覆盖率 ├── preview-doc.bat // 一键预览开发文档 ├── preview-doc-new.bat // 一键预览新版开发文档 ├── update-log.md // 更新日志 └── README.md // 仓库自述文件

顶层模块在逻辑上可以划分为四个层次：

• 核心层：sa-token-core，框架全部鉴权逻辑的所在地；
• 依赖管理层：sa-token-dependencies、sa-token-special-dependencies、sa-token-bom，负责统一版本号与依赖隔离；
• 适配层：sa-token-starter（框架整合）与sa-token-plugin（能力插件）；
• 配套层：sa-token-demo（示例）、sa-token-testing（测试）、sa-token-doc/sa-token-doc-new（文档）。

需要说明的是，原目录介绍文档中列出的MEMO（内部备忘录、开发记录）目录在当前仓库快照中未出现，本仓库实际结构以 根目录清单 为准。

二、依赖管理层：版本号如何被统一管理

1. sa-token-dependencies：所有第三方依赖版本号集中地

sa-token-dependencies是一个纯pom类型模块（pom.xml），其核心职责是集中定义所有第三方依赖版本号，并放入<dependencyManagement>供全工程引用。在这里可以一次性看清 Sa-Token 的完整技术栈：

• JSON 序列化：jackson-databind 2.13.4.1、Jackson3（tools.jackson.core）、fastjson / fastjson2 2.0.64、Snack3、Snack4、Apache Fory JSON；
• Web 框架生态：Solon、JFinal、Jboot、LoveQQ-Boot；
• 缓存/Redis：Redisson 3.45.0、Redisx、Hutool Cache、Caffeine、commons-pool2；
• RPC 与安全：Dubbo、grpc-spring-boot-starter、jjwt、hutool-jwt；
• 测试工具链：JUnit Jupiter、Mockito、jedis-mock（内存版 Redis 模拟，用于测试）、slf4j-simple、snakeyaml。

该模块还统一管理了sa-token-test-support、sa-token-json-test-common、sa-token-http-test-common、sa-token-redis-dao-test-common等测试公共包的版本。顶层 pom.xml 通过<scope>import</scope>方式导入此模块的 dependencyManagement，使版本定义向所有子模块传导。

2. sa-token-special-dependencies：SpringBoot 2/3/4 版本隔离

sa-token-special-dependencies（pom.xml）下按 SpringBoot 大版本拆分出三个子模块，用于解决不同 SpringBoot 主版本间的依赖冲突：

• sa-token-spring-boot2-dependencies
• sa-token-spring-boot3-dependencies
• sa-token-spring-boot4-dependencies

这是 Sa-Token 能同时支持 SpringBoot 2/3/4 的关键工程手段：把随主版本变化的依赖定义隔离在独立 POM 中，各 starter 只需引用对应版本即可，避免相互污染。

3. sa-token-bom：面向使用方的统一依赖清单

sa-token-bom（pom.xml）是发布到 Maven 中央仓库的 BOM 包，面向框架使用者。它在<dependencyManagement>中列出了所有 Sa-Token 自研制品（sa-token-core、全部 starter、全部 plugin）并统一版本为${revision}，因此使用方只需在项目中导入该 BOM，即可省略所有 Sa-Token 依赖的版本号。仓库内专门提供了 sa-token-demo-bom-import 示例工程演示导入方式。

三、核心层：sa-token-core 的内部结构

sa-token-core是整个框架的心脏，不含任何 Web 容器耦合，全部代码位于cn.dev33.satoken包下（源码目录），按功能划分为数十个包：

• stp：核心 API 层，包括开发者最常使用的StpUtil（StpUtil.java）、StpLogic、StpInterface以及登录参数模型SaLoginModel/SaLoginConfig等；
• dao：数据持久层抽象，定义SaTokenDao接口及 timedcache 定时缓存实现；
• config：全局配置SaTokenConfig，对应application.yml中的sa-token配置项；
• context：上下文抽象层，解耦不同 Web 容器对 Request/Response 的差异；
• session：Session 会话模型与存储；
• listener：全局事件监听器；
• annotation与annotation/handler：@SaCheckLogin、@SaCheckPermission等注解及其处理器；
• filter/router：路由匹配、过滤器相关实现；
• exception：NotLoginException、NotPermissionException、NotRoleException等全套异常体系；
• json/serializer：序列化抽象与默认实现，供插件按需替换；
• strategy与fun：策略扩展点与函数式接口，是 Sa-Token 高度可定制的底座；
• secure、same、temp、httpauth、log、application、model、util、error、plugin等：分别承载安全工具（TOTP 等）、同源校验、临时 Token、HTTP Basic/Digest 认证、日志、应用信息、模型、工具类、错误码与插件机制。

从源码结构看，sa-token-core刻意保持"零框架依赖"，所有对 SpringBoot、Servlet 的适配都下沉到sa-token-starter，这保证了核心逻辑可被任意框架复用。核心模块自身也携带了 104 个测试文件（测试目录），直接以纯 Java 方式验证鉴权核心逻辑。

四、整合层：sa-token-starter 各子模块职责

sa-token-starter（目录）承担"与其它框架整合"的职责，按容器和框架分为三层：

1. Servlet 容器适配

• sa-token-servlet：整合 Servlet 容器的实现类包（javax 命名空间）；
• sa-token-jakarta-servlet：整合 Jakarta-Servlet 容器的实现类包（适配 SpringBoot 3/4 与 Tomcat 10+）。

2. SpringBoot 集成 starter

• sa-token-spring-boot-starter：整合 SpringBoot2 的快速集成包（开箱即用）；
• sa-token-spring-boot3-starter：整合 SpringBoot3 的快速集成包；
• sa-token-spring-boot4-starter：整合 SpringBoot4 的快速集成包；
• sa-token-spring-boot-webmvc-v3v4-common：SpringBoot WebMvc 公共包（3/4）；
• sa-token-spring-boot-webmvc-reactor-v2v3v4-common：SpringBoot WebMvc + Reactor 公共包（2/3/4）。

3. 响应式（Reactive / WebFlux）支持

• sa-token-reactor-spring-boot-starter：整合 SpringBoot2 Reactor 响应式编程；
• sa-token-reactor-spring-boot3-starter：整合 SpringBoot3 Reactor；
• sa-token-reactor-spring-boot4-starter：整合 SpringBoot4 Reactor；
• sa-token-spring-boot-reactor-v3v4-common：SpringBoot Reactor 公共包（3/4）。

4. 其它 Web 框架整合

• sa-token-solon-plugin：整合 Solon 框架；
• sa-token-jfinal-plugin：整合 JFinal 框架；
• sa-token-jboot-plugin：整合 JBoot 框架；
• sa-token-loveqq-boot-starter：整合 LoveQQ-Boot 框架。

选择原则很简单：用哪个框架就引入对应的 starter 模块，核心逻辑全部来自sa-token-core，starter 只负责把 Sa-Token 注册进对应框架的请求生命周期中。

五、插件层：sa-token-plugin 五大能力族

sa-token-plugin（目录）承载框架的扩展能力，按用途可归纳为五大族：

1. JSON 序列化插件（任选其一引入）

针对不同 JSON 库提供统一接入，仓库均提供对应示例与测试：

• sa-token-jackson（Jackson 2）、sa-token-jackson3（Jackson 3）
• sa-token-fastjson、sa-token-fastjson2
• sa-token-fory-json（Apache Fory JSON）
• sa-token-snack3、sa-token-snack4
• sa-token-serializer-features：序列化实现的通用扩展包

2. 缓存 / Redis 插件

• sa-token-redis-template：整合 Spring Data RedisTemplate；
• sa-token-redis-template-jdk-serializer：RedisTemplate + JDK 序列化算法；
• sa-token-redis-jackson：RedisTemplate + Jackson 序列化算法；
• sa-token-redisson与sa-token-redisson-spring-boot-starter：整合 Redisson；
• sa-token-redisx：整合 Noear Redisx；
• sa-token-hutool-timed-cache、sa-token-caffeine：基于内存的本地缓存插件；
• sa-token-alone-redis、sa-token-alone-redisson、sa-token-alone-redis-by-spring-boot4：独立 Redis 插件，实现"权限缓存与业务缓存分离"。

3. RPC 鉴权与状态传递

• sa-token-dubbo、sa-token-dubbo3：Dubbo / Dubbo3 调用鉴权与登录状态传递；
• sa-token-grpc：gRPC 调用鉴权与状态传递。

4. 登录认证与安全扩展

• sa-token-jwt：基于 jjwt 的 JWT 登录认证；
• sa-token-temp-jwt：基于 jjwt 的临时 Token；
• sa-token-sso：SSO 单点登录；
• sa-token-oauth2：OAuth2.0 统一认证；
• sa-token-apikey：API Key 秘钥授权；
• sa-token-sign：API 参数签名；
• sa-token-quick-login：快速注入登录页插件。

5. 模板引擎标签与 HTTP 客户端

• sa-token-thymeleaf、sa-token-freemarker：为模板引擎提供 Sa-Token 自定义标签方言，前端可直接用#标签做权限判断；
• sa-token-spring-aop：SpringAOP 注解鉴权增强；
• sa-token-spring-el：SpringEL 表达式注解鉴权；
• sa-token-forest、sa-token-okhttps、sa-token-rest-template、sa-token-rest-client：多种 HTTP 请求处理器接入。

所有插件版本均被 sa-token-bom 统一管理，用户无需手写版本号。

六、示例层：sa-token-demo 的导航价值

sa-token-demo是最大的目录，几乎为每一个插件和框架组合都提供了可运行的示例工程，是"照着抄"的最佳参考。按主题分组如下：

Redis 集成类：sa-token-demo-alone-redis、sa-token-demo-alone-redis-cluster（集群模式）、sa-token-demo-alone-redis-sb4、sa-token-demo-alone-redisson、sa-token-demo-alone-redisson-cluster、sa-token-demo-alone-redisson-sb3、sa-token-demo-alone-redisson-sb4、sa-token-demo-springboot-redis、sa-token-demo-springboot3-redis、sa-token-demo-springboot4-redis、sa-token-demo-springboot-redisson、sa-token-demo-solon-redisson。

登录认证类：sa-token-demo-jwt（JWT 登录）、sa-token-demo-quick-login与sa-token-demo-quick-login-sb3（快速登录页）、sa-token-demo-apikey（API Key）、sa-token-demo-remember-me（"记住我"模式，含 page_project 前端 与 server 后端）、sa-token-demo-device-lock（设备锁登录，含后端与 h5 前端）。

SSO 单点登录类：sa-token-demo-sso下包含sa-token-demo-sso-server（认证中心）、模式一/二/三客户端（sa-token-demo-sso1-client、sa-token-demo-sso2-client、sa-token-demo-sso3-client）、SpringBoot4 版（sa-token-demo-sso3-client--sb4）、无 SDK 纯手动对接版（sa-token-demo-sso3-client-nosdk）、ReSdk 重写对接版（sa-token-demo-sso3-client-resdk）、匿名应用接入版（sa-token-demo-sso3-client-anon），以及前后端分离的 h5 / Vue2 / Vue3 前端工程；Solon 版则统一放在sa-token-demo-sso-for-solon下。

OAuth2 类：sa-token-demo-oauth2下包含sa-token-demo-oauth2-server（服务端）、sa-token-demo-oauth2-client（客户端）及对应 h5 前端测试页。

RPC 与异步类：sa-token-demo-dubbo（含 dubbo/dubbo3 的 consumer/provider 四端）、sa-token-demo-grpc（client/server）、sa-token-demo-async、sa-token-demo-sse。

响应式与长连接类：sa-token-demo-webflux、sa-token-demo-webflux-springboot3、sa-token-demo-webflux-springboot4、sa-token-demo-websocket、sa-token-demo-websocket-spring。

模板引擎类：sa-token-demo-thymeleaf、sa-token-demo-freemarker、sa-token-demo-beetl。

框架集成类：sa-token-demo-springboot、sa-token-demo-springboot-low-version（SpringBoot2 低版本）、sa-token-demo-solon、sa-token-demo-jfinal、sa-token-demo-loveqq-boot、sa-token-demo-ssm（SSM 传统整合）。

工程实践类：sa-token-demo-case（各模块综合示例）、sa-token-demo-first-run（源码首次运行引导，强制引入 apikey、sso、oauth2、sign、jwt 等可选模块）、sa-token-demo-bug-reproduce（Issue/Bug 复现沙盒）、sa-token-demo-json-typing-security（JSON 多态反序列化白名单回归，Spring Boot + Jackson）与sa-token-demo-json-typing-security-for-solon（Solon + Snack4 版）、sa-token-demo-test（整合测试项目）、sa-token-demo-bom-import（BOM 导入示例）、sa-token-demo-hutool-timed-cache与sa-token-demo-caffeine（本地缓存示例）。

其中 sa-token-demo-first-run 对源码学习者尤其有价值：它在本地install时强制把所有可选模块引入一次，确保一键编译通过后再进入单模块学习。sa-token-demo/sa-token-demo-case则是阅读各模块 API 用法的速查工程。

七、测试层：sa-token-testing 与核心单测

• sa-token-core/src/test：核心模块自带的 104 个单元测试文件，零外部框架依赖即可运行；
• sa-token-testing（目录）：面向整合场景的测试合集，包括sa-token-test-support（测试支撑包）、sa-token-json-test-common、sa-token-http-test-common、sa-token-redis-dao-test-common等公共测试夹具，以及覆盖 SpringBoot2/3/4、Reactor、Dubbo/Dubbo3、gRPC、JFinal、Jboot、Solon、LoveQQ、OAuth2、SSO 的sa-token-integration-*系列、sa-token-alone-redis-template-boot2（独立 Redis 测试）和sa-token-coverage（覆盖率汇总模块）。

关于测试执行，顶级 pom.xml 中默认skipTests=true且jacoco.skip=true，即日常mvn package/mvn install不会跑单测与覆盖率；需要跑测试时使用mvn test -DskipTests=false，需要覆盖率时运行仓库根目录的mvn-coverage.bat。全工程默认携带 JUnit Jupiter（scope=test），各子模块无需重复声明。

八、文档层与根目录辅助文件

• sa-token-doc（目录）：Sa-Token 开发文档主体，按arch（架构）、use（使用）、up（进阶）、fun（功能）、plugin（插件）、sso（SSO）、oauth2（OAuth2）、api（API）、micro（微服务）、start（开始）、more（更多）等分区组织。其中 arch/data-structure.md 与本文同属架构系列，建议配合阅读——它从"token -> loginId 映射"等数据结构角度讲解框架内部存储设计；
• sa-token-doc-new（目录）：新版文档站工程，docs/下为 Markdown 源文件，public/下为静态资源；
• 根目录批处理脚本：mvn clean.bat（一键 clean 核心包与所有示例包）、mvn test.bat（一键单元测试）、mvn-coverage.bat（覆盖率）、preview-doc.bat（预览旧版文档）、preview-doc-new.bat（预览新版文档）；
• 根目录其它文件：README.md及多语言 README、LICENSE（Apache 2.0）、SECURITY.md、update-log.md（版本更新日志）。

九、生态仓库与延伸阅读

在原文档末尾还列出了 Sa-Token 生态下的其它相关仓库，可作为延伸学习资源（均可通过 sa-tokens 组织检索到）：集成 Sa-Token 的优秀开源案例收集（Awesome-Sa-Token）、Sa-Token 的 Rust 与 Go 语言版本、Sa-Token 技术点学习笔记（Sa-Token-Study）、各种登录方式示例集合（Sa-Token-Login-Demos）、文档图片资源仓库（sa-token-doc-big-file）、第三方插件合集（sa-token-three-plugin）、跨域场景示例（sa-token-demo-cross），以及 Java 权限认证框架功能测试/对比/迁移项目（auth-framework-function-test）。

回到本仓库，建议的阅读路线是：先用sa-token-demo-first-run跑通整个工程，再以sa-token-demo-springboot为最小可运行样本观察 starter 的装配，随后进入sa-token-core的stp、dao、config三个包理解核心鉴权模型，最后按需深入sa-token-plugin与sa-token-testing。以目录为地图，Sa-Token 的源码便不再庞杂。

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token