← 课程目录 🚀 从零到一
📐 学习维度 阶段4 · 第18章 安全框架 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

18.3 Sa-Token:轻量级认证授权框架

审校 2026-09-25 · 素材来源:Sa-Token官方文档与会话笔记(脱敏改写)
📑 本篇章节导航 (共8节,点击直达)
架构:StpLogic 门面一把梭注解与路由双模式会话三种模式与多端互踢SSO 单点登录:三套模式与 Spring Security 怎么选踩坑清单面试怎么问一句话总结

18.2 把 Spring Security 的过滤器链拆完,结论很诚实:它功能全但门槛高——想写个登录,先得理解 Manager/Provider/DetailsService 三件套。Sa-Token(一个国产轻量级 Java 认证授权框架,把登录、权限、踢人、SSO 做成一行的 API 风格)走另一条路:把 80% 场景的常见需求封装成直白的方法调用,让「写登录」回归写业务的感觉。这一篇看它的架构与用法,以及什么时候该用它替掉 Security。

架构:StpLogic 门面一把梭

Sa-Token 的核心是 StpLogic(面向某一类账号体系的逻辑门面,持有登录、权限、会话的全部 API)——默认实例 StpUtil 就是它的静态入口。所有操作都是一行:


StpUtil.login(10001);                     // 登录:为用户10001发token
StpUtil.getLoginId();                     // 当前请求是谁(从token反解)
StpUtil.checkLogin();                     // 未登录则抛异常
StpUtil.checkPermission("order:write");   // 无权限则抛异常
StpUtil.kickout(10001);                   // 踢人下线
StpUtil.logout();                         // 注销

没有过滤器链要配、没有 Provider 要实现——登录态的存取被抽象到 SaTokenDao(令牌与会话的存储接口,默认内存,可换 Redis):登录时生成 token 写入 Dao 并塞进响应,请求时拦截器从 Cookie/Header 取 token 查 Dao 反解出用户。这正好落在 18.1 的理论坐标上:token 本身只是个钥匙串,状态在服务端存储里——所以 Sa-Token 能天然支持踢人、顶人下线,这是纯 JWT 做不到的。

权限数据从哪来?实现 StpInterface(权限与角色的数据源接口)两个方法:


@Component
public class StpInterfaceImpl implements StpInterface {
    @Override
    public List<String> getPermissionList(Object loginId,
            String loginType) {
        return roleMapper.findPerms(Long.valueOf(loginId.toString()));
    }
    @Override
    public List<String> getRoleList(Object loginId,
            String loginType) {
        return roleMapper.findRoles(Long.valueOf(loginId.toString()));
    }
}

StpUtil.checkPermission 内部就是查它——权限模型(RBAC:用户-角色-权限三张表)由你自己的表决定,框架只问「这个人有什么权限」,不规定你怎么存。

注解与路由双模式

鉴权有两种挂法。注解式:方法或类上标注,AOP 在调用前校验:


@SaCheckLogin
@SaCheckRole("admin")
@SaCheckPermission(value = {"order:write", "order:read"},
                   mode = SaMode.OR)
@PostMapping("/order")
public Result createOrder(@RequestBody OrderDTO dto) {
    return Result.ok(orderService.create(dto));
}

路由式:注册拦截器后按路径统一配置——粗门禁走路由、房间钥匙走注解,和 18.2 的两层哲学一致:


@Bean
public SaInterceptor saInterceptor() {
    return new SaInterceptor(handler -> {
        SaRouter.match("/order/**")
                .notMatch("/order/view")
                .check(r -> StpUtil.checkPermission("order:write"));
    });
}

注意注解式要求开启 AOP 代理(SaAnnotationInterceptor 或 @EnableAspectJAutoProxy),漏了会出现「注解写了但不生效」的经典排障题——本质还是 13.3 的代理机制。

会话三种模式与多端互踢

Sa-Token 把「会话」分了三层,这是它设计里最值得学的一刀:

三层的分野让多端登录策略成了一行配置:maxLoginCount = 5(同账号最多 5 个设备同时在线,超过按 maxTryTimes 顶掉最旧的)。isShare = false 则每次登录都发新 token——「同端互踢」「多端共存」这些产品经理张口就来的需求,在这里是配置项而不是开发量。

会话时效有两个旋钮要分清:timeout(token 有效期,默认 30 天)和 active-timeout(活跃过期:多久不操作就失效,默认关)。两者叠加的逻辑是「token 没过期且最近活跃过」才放行——配合 auto-renew=true(每次请求自动续期 timeout),形成「滑动窗口」式有效期:常用用户永不过期、挂机用户到期掉线。还有 token 风格:默认 uuid 已够随机,token-style=随机64位 更极端,但千万别选自增 id——可被遍历伪造。这些参数在 yaml 的 sa-token: 前缀下一层配齐,对照官方配置项文档过一遍十分钟,比出事后翻源码舒服。

SSO 单点登录:三套模式

18.1 留的钩子在这兑现。Sa-Token 的 SSO(单点登录:一处登录全系统通用)分三种模式,按系统复杂度递增:

同域无中间件(模式一):多个系统同在一个父域名下,Cookie 天然共享,登录态直接互认——最简单,也最受域名约束。同 Redis 无中间件(模式二):各系统连同一个 Redis,ticket 校验走共享存储——跨域了,但要求系统能共享 Dao。跨 Redis 走认证中心(模式三):独立的 SSO-Server 统一登录发 ticket,各 SSO-Client 拿 ticket 换用户信息——这是标准的中心化答案,解决「认证中心与业务系统存储隔离」的最终形态。选型口径:能低模式不高模式,模式三的运维成本是前两者的数倍。

与 Spring Security 怎么选

两个框架的对比本质是两种哲学:

维度Spring SecuritySa-Token
定位全功能安全体系认证授权聚焦
上手成本高(概念链长)低(API 直白)
过滤器链完整可定制轻量拦截器
OAuth2 资源服务器原生完善需组合扩展
社区生态国际主流国内活跃

选型三句话:重安全体系、要 OAuth2/OIDC 全家桶、国际团队协作——Spring Security,它是最完整的答案;国内业务系统、要快速上线、踢人/多端/SSO 是刚需——Sa-Token,它的 API 密度让你一天搭完登录体系。还有一条工程判断:Sa-Token 的简单来自约定,「约定优于配置」的另一面是深度定制时要翻它的源码——好在它源码量只有 Security 的零头,翻得动。

踩坑清单

面试怎么问

一句话总结

Sa-Token 用「门面 API + 可替换存储」把认证授权打回一行代码的直觉:login/check/kickout 直球命名、三层会话承接多端登录、三套 SSO 模式按隔离度对号入座——当 Spring Security 的概念链成本贵过你的实际业务复杂度时,它就是那个务实好用的选择。