← 课程目录 🚀 从零到一
📐 学习维度 阶段7 · 第28章 开源项目源码精读 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

28.5.1 Sa-Token 权限认证:StpLogic 核心设计与门面模式

审校 2026-09-26 · 素材来源:zcode会话《项目权限框架架构与设计模式分析》(项目源码分析)
📑 本篇章节导航 (共6节,点击直达)
场景:一行登录代码的底气类比:餐厅的前台与后厨最小可跑示例原理拆解:三层门面 + 十步登录踩坑清单面试怎么问

接手一个老项目,登录逻辑散落在五个 Filter 里,改一处崩三处。Sa-Token 的答案是一行 StpUtil.login(id)。这篇拆开它最核心的 StpLogic,看这一行背后发生了什么。

前置阅读:18.3 入门过 Sa-Token 用法。这篇拆 StpLogic 源码,看门面模式怎么撑起整套 API。

场景:一行登录代码的底气

你新写一个接口,想加登录校验。Spring Security 要配 FilterChain、写 UserDetailsService、懂 SecurityContext。Sa-Token 只要:


StpUtil.login(10001);          // 登录
StpUtil.checkLogin();          // 校验
StpUtil.getPermissionList();   // 拿权限

没有 Subject,没有 Realm,没有 Filter 链。敢这么设计,是因为它把复杂度全收进了 StpLogic 这一个类,对外只露静态门面。

类比:餐厅的前台与后厨

StpUtil 是前台点餐员,只接单不做事。StpLogic 是后厨,切配炒装一条龙。SaManager 是商场物业,管水电煤气(全局组件)。

你换后厨(自定义登录逻辑)、换食材仓库(换 Redis 存储),前台菜单一个字不用改。这就是门面模式(Facade,把复杂子系统收拢成一个简单入口)的价值。

最小可跑示例


<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>1.44.0</version>
</dependency>

@RestController
public class LoginController {
    @PostMapping("/login")
    public String login(@RequestParam String name, @RequestParam String pwd) {
        if ("{{DEMO_USER}}".equals(name) && checkPwd(pwd)) {
            StpUtil.login(10001);
            return StpUtil.getTokenValue();
        }
        throw new RuntimeException("账号或密码错误");
    }

    @GetMapping("/me")
    public String me() {
        StpUtil.checkLogin();
        return "user:" + StpUtil.getLoginId();
    }
}

默认 token 风格是 uuid,请求时带上 satoken: <token> 头即可通过校验。

原理拆解:三层门面 + 十步登录

第一层:StpUtil 静态门面。 它几乎没有逻辑,全部委托给内部的 StpLogic 实例。所以它能同时存在 StpUtil、StpUserUtil、StpAdminUtil——每个 loginType 一套门面,多账号体系天然隔离,不用像 Shiro 那样配多 Realm。

第二层:SaManager 组件容器。 它持有 config、dao、stpInterface、context 等十多个全局组件,每个 getter 都是 volatile + synchronized 双重检查锁懒加载单例(SaManager.java:115 附近),线程安全又不浪费启动时间。

第三层:StpLogic 模板方法。 login(id) 只有一步:createLoginSession()。这个方法(StpLogic.java:484 起)定义了十步标准流程:

1. 校验参数、检查账号封禁状态

2. 生成 token(策略可换:uuid / random-32 / tik 六种风格)

3. 创建或续期 Account-Session

4. 记录终端信息(device)

5. 存 token 与账号 id 的映射

6. 写活跃时间

7. 续期 Token-Session

8. 广播登录事件

9. 检查最大登录数(决定顶替还是共享 token)

10. 返回 token

这是模板方法模式(Template Method,父类定流程骨架、子类按需覆盖某几步)。JWT 三种集成模式就是靠 override 其中的个别步骤实现的。

会话双模型是理解这一切的钥匙:

一个账号多端登录,就是一棵 Account-Session 挂多个 Token-Session 的树。踢人下线、顶人下线,本质就是剪掉树上某个枝。

策略模式(Strategy,把算法封装成可替换的函数对象)体现在 SaStrategy:createToken、autoRenew、routeMatcher 等关键算法都是公共字段函数式接口,业务方一行 SaStrategy.instance.setCreateToken(...) 就能换掉,不需要继承任何类。用策略对象替代继承体系,是它"灵活但 API 简单"的根本原因。

注解校验走 SaAnnotationStrategy,内部是一个 Map<注解Class, 处理器> 的注册表:@SaCheckLogin、@SaCheckPermission、@SaCheckRole、@SaCheckSafe 各有处理器,也能注册自定义注解。这算责任链的变体——注册表分派,而非串行传递。

事件广播贯穿整个流程。login 成功的最后一步不是返回 token,而是调用 SaTokenEventCenter 广播事件。观察者模式(Observer,一处状态变化、所有订阅者收到通知)在这里落地:SaTokenListener 接口有十三个回调,覆盖登录、注销、踢下线、封禁、续期、组件注册。业务上最常见的两个用法:登录成功后写审计日志,踢人时推 WebSocket 通知前端跳到提示页。

上下文适配是它跨框架的秘密。core 层完全不 import HttpServletRequest,而是定义了 SaTokenContext 加 SaRequest、SaResponse、SaStorage 四个抽象。各 starter 提供 Servlet、WebFlux、Solon 版实现,SaHolder 静态门面按当前环境桥接到真实请求对象。这是适配器模式(Adapter,用中间抽象抹平不同接口的差异):同一套核心代码,跑在 SpringBoot2、SpringBoot3、WebFlux、Solon、JFinal 上都不用改。

再把整体架构立起来看。Sa-Token 是三层加插件化:core 只放抽象与默认实现,零依赖任何 Web 框架;starter 负责各框架适配;三十多个插件(redis、jwt、sso、oauth2、dubbo、sign 等)按需引入。它能同时伺候这么多环境,靠的就是"core 定契约、插件给实现"这一条纪律。

token 的生成与校验也值得单独说。生成走策略 createToken,默认 uuid,还提供 random-32/64/128 和 tik 等六种风格;generateUniqueToken 策略负责防冲突重试——生成后先查 Dao 确认没被占用,撞了就重来。校验走 getLoginIdNotHandle 一条链:取请求里的 token、查映射得到 loginId、检查封禁与过期。整个链条每一步都可能被 JWT 子类覆盖替换,这正是模板方法加策略的组合威力。

默认内存实现是个 LinkedHashMap 加定时清理:SaTokenDaoDefaultImpl 用带过期语义的 Map 存数据,启动一个线程周期性扫描过期键。它只该出现在 demo 和单测里,生产环境必须换 Redis 实现——这不是可选项,是上线的硬前提。

对比 Shiro 和 Spring Security,差异可以用一句话概括:传统框架把复杂度暴露给使用者(Filter 链、Realm、SecurityManager 一堆前置概念),Sa-Token 把复杂度藏进 StpLogic 三千行里,只留一个静态门面。代价是黑盒更深,出了怪问题必须读源码;收益是百分之九十的场景一行代码搞定。

踩坑清单

面试怎么问

「Sa-Token 和 Spring Security 的核心区别?」——答:Security 是 Filter 链加 SecurityContext 的重型模型;Sa-Token 用静态门面 StpUtil 加可热插拔的策略对象,把复杂度收进 StpLogic 模板方法里,API 简单但扩展点一个不少。

「Sa-Token 的多账号体系怎么实现?」——答:每个 loginType 一个独立 StpLogic 实例加独立门面类,token、Session、配置全部按 loginType 隔离,天然支持用户端和管理端并存。

「踢人下线在会话模型上怎么理解?」——答:Account-Session 是树干,每个 Token-Session 是树枝,踢人就是删掉指定 token 的映射和 Session 节点。