Sa-Token 全局对象与常用方法完全指南SaManager、SaHolder、SaFoxUtil 等核心工具类实战解析【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本文以 Sa-Token 文档 sa-token-doc/more/common-action.md 为主体系统讲解框架中高频使用的全局类与方法全局组件管理器 SaManager、上下文持有类 SaHolder、路由匹配工具 SaRouter、内部工具类 SaFoxUtil、配置文件工厂 SaTokenConfigFactory以及 SpringMVC / Reactor 环境下的工具类。读完本文你将掌握在任意代码位置获取配置、DAO、上下文、请求响应对象的能力理解 Sa-Token 全局组件的注册与懒加载机制并能在非 IOC 环境下手动装配配置为自定义扩展插件打下基础。一、SaManager全局组件统一管理器SaManager负责管理 Sa-Token 所有全局组件是框架的总控台。无论是获取全局配置、数据持久化对象还是权限认证接口、上下文对象都可以通过它快速拿到。其实现位于 sa-token-core/src/main/java/cn/dev33/satoken/SaManager.java。1.1 组件获取与设置速查SaManager.getConfig(); // 获取全局配置对象 SaManager.setConfig(config); // 设置全局配置对象 SaManager.getSaTokenDao(); // 获取数据持久化对象 SaManager.setSaTokenDao(saTokenDao); // 设置数据持久化对象 SaManager.getStpInterface(); // 获取权限认证对象 SaManager.setStpInterface(stpInterface); // 设置权限认证对象 SaManager.getSaTokenContext(); // 获取 SaTokenContext 上下文处理对象 SaManager.setSaTokenContext(saTokenContext); // 设置 SaTokenContext 上下文处理对象 SaManager.getSaTempTemplate(); // 获取临时令牌认证模块对象 SaManager.setSaTempTemplate(saTempTemplate); // 设置临时令牌认证模块对象 SaManager.getSaJsonTemplate(); // 获取 JSON 转换器 Bean SaManager.setSaJsonTemplate(saJsonTemplate); // 设置 JSON 转换器 Bean SaManager.getSaHttpTemplate(); // 获取 Http 请求处理 Bean详见 [HTTP 请求扩展](https://link.gitcode.com/i/7bc25821d34ab1ca2f925adb3e6553f2) SaManager.setSaHttpTemplate(saHttpTemplate); // 设置 Http 请求处理 Bean SaManager.getSaSerializerTemplate(); // 获取序列化器 Bean SaManager.setSaSerializerTemplate(saSerializerTemplate); // 设置序列化器 Bean SaManager.getSaSameTemplate(); // 获取 Same-Token 模块 Bean SaManager.setSaSameTemplate(saSameTemplate); // 设置 Same-Token 模块 Bean SaManager.getSaTotpTemplate(); // 获取 TOTP 模块 Bean SaManager.setSaTotpTemplate(totpTemplate); // 设置 TOTP 模块 Bean SaManager.getLog(); // 获取日志输出对象 SaManager.setLog(log); // 设置日志输出对象 SaManager.getStpLogic(type); // 获取指定账号类型的 StpLogic 对象获取不到时自动创建并返回 SaManager.getStpLogic(type, false); // 获取指定账号类型的 StpLogic 对象获取不到时抛出异常 SaManager.putStpLogic(stpLogic); // 向全局集合中 put 一个 StpLogic1.2 源码级机制懒加载与组件替换从源码可以看到SaManager 中的组件几乎都遵循双重检查锁DCL懒加载模式。例如getSaTokenDao()在首次调用且尚未设置时会同步创建默认实现SaTokenDaoDefaultImpl并缓存// SaManager.java 源码节选 public static SaTokenDao getSaTokenDao() { if (saTokenDao null) { synchronized (SaManager.class) { if (saTokenDao null) { setSaTokenDaoMethod(new SaTokenDaoDefaultImpl()); } } } return saTokenDao; }这解释了为什么不配置也能直接运行所有组件都有内置默认实现SaTokenDaoDefaultImpl、StpInterfaceDefaultImpl、SaTokenContextForThreadLocal、SaJsonTemplateDefaultImpl、SaHttpTemplateDefaultImpl、SaSerializerTemplateForJson、SaLogForConsole等。值得注意的细节set 方法会触发全局事件setSaTokenDao、setStpInterface、setSaTokenContext等 setter 在赋值后都会调用SaTokenEventCenter.doRegisterComponent(...)向全局事件中心广播组件已注册方便监听器感知框架状态变化。DAO 的生命周期管理setSaTokenDaoMethod在替换旧 DAO 前会先调用旧对象的destroy()再对新对象调用init()保证内存/连接资源被正确释放与初始化。setConfig 的副作用setConfig会打印 banner、自动判定彩色日志isColorLog、广播doSetConfig事件并提前触发一次StpUtil.getLoginType()以尽早初始化默认 StpLogic。1.3 多账号体系下的 StpLogic 管理Sa-Token 支持多账号体系每个账号类型loginType对应一个StpLogic。getStpLogic(type)的第二个参数控制获取不到时的行为SaManager.getStpLogic(user)获取不到时自动创建并返回线程安全见源码中的 synchronized 二次检查SaManager.getStpLogic(user, false)获取不到时抛出异常用于严格校验 loginType 拼写或 StpUtil 是否已初始化异常码为SaErrorCode.CODE_10002提示未能获取对应StpLogic。源码注释还给出了两种修复自定义 StpUtil 未初始化的方案一是从main方法里调用一次触发类加载二是给自定义 StpUtil 类加上Component注解让容器启动时自动扫描初始化。1.4 侦听器与参数签名模块的获取文档特别强调两类特殊组件的获取方式侦听器注册请使用SaTokenEventCenter.registerListener(listener)通过事件中心统一管理参数签名模块请使用SaSignManager.getSaSignTemplate()详见 参数签名 章节。这两者不走SaManager的常规 getter而是各自拥有独立的管理类。二、SaHolder当前环境上下文快速入口SaHolder是 Sa-Token 的上下文持有类位于 sa-token-core/src/main/java/cn/dev33/satoken/context/SaHolder.java。它是对SaManager.getSaTokenContext()的便捷封装让你在任何位置包括非 Controller 的 Service、工具类都能快速拿到当前请求环境相关对象SaHolder.getContext(); // 获取当前请求的 SaTokenContext SaHolder.getRequest(); // 获取当前请求的 [Request] 对象 SaHolder.getResponse(); // 获取当前请求的 [Response] 对象 SaHolder.getStorage(); // 获取当前请求的 [Storage] 对象 SaHolder.getApplication(); // 获取全局 SaApplication 对象从源码看getRequest()、getResponse()、getStorage()均委托给SaManager.getSaTokenContext()获取的SaTokenContext实例而getApplication()直接返回全局单例SaApplication.defaultInstance。返回的SaRequest、SaResponse、SaStorage都是框架定义的抽象包装对象位于cn.dev33.satoken.context.model包屏蔽了底层 Servlet / WebFlux / Solon / JFinal 等不同容器的差异——这正是 Sa-Token 能无缝适配多种 Web 环境的基石。借助这些包装对象你可以统一地读写请求头、Cookie、请求体无需关心底层容器 API。三、SaRouter路由匹配鉴权工具SaRouter是路由匹配工具类用于基于 URL 匹配的拦截式鉴权。实现位于 sa-token-core/src/main/java/cn/dev33/satoken/router/SaRouter.java。典型用法是在全局过滤器或拦截器中按路径规则放行/拦截SaRouter.match(/**).notMatch(/user/login, /user/register).check(r - StpUtil.checkLogin());它支持match匹配、notMatch排除、check校验函数等链式 API也支持多账号体系配合match后执行StpUtil.checkLogin()或指定StpLogic。完整的路由鉴权体系含匹配规则语法、通配符、黑白名单、多模块校验请参见 路由拦截式鉴权本文不再展开。四、SaFoxUtil框架内部工具类SaFoxUtil是 Sa-Token 的内部工具类位于 sa-token-core/src/main/java/cn/dev33/satoken/util/SaFoxUtil.java包含字符串、集合、日期、URL 等一系列高频工具方法日常开发中同样可以直接复用。4.1 常用方法速查表方法说明SaFoxUtil.printSaToken()打印 Sa-Token 版本字符画bannerSaFoxUtil.getRandomString(8)生成指定长度的随机字符串SaFoxUtil.isEmpty(str)判断字符串是否为 null 或空字符串SaFoxUtil.isNotEmpty(str)判断字符串是否既非 null 也非空字符串SaFoxUtil.equals(a, b)比较两个对象是否相等SaFoxUtil.getMarking28()以当前时间戳和随机 int 数字拼接一个随机字符串SaFoxUtil.formatDate(date)将日期格式化为yyyy-MM-dd HH:mm:ss字符串SaFoxUtil.searchList(dataList, prefix, keyword, start, size, sortType)从集合中查询数据支持前缀过滤、关键字、分页、排序SaFoxUtil.searchList(dataList, start, size, sortType)从集合中查询数据简化版SaFoxUtil.vagueMatch(patt, str)字符串模糊匹配SaFoxUtil.getValueByType(obj, cs)将指定值转化为指定类型SaFoxUtil.joinParam(url, parameStr)在 url 上拼接 kv 参数并返回SaFoxUtil.joinParam(url, key, value)在 url 上拼接单个 kv 参数并返回SaFoxUtil.joinSharpParam(url, parameStr)在 url 上拼接锚参数#SaFoxUtil.joinSharpParam(url, key, value)在 url 上拼接单个锚参数SaFoxUtil.arrayJoin(arr)将数组所有元素用逗号拼接在一起SaFoxUtil.isUrl(str)使用正则判断一个字符串是否为 URLSaFoxUtil.encodeUrl(str)URL 编码SaFoxUtil.decoderUrl(str)URL 解码SaFoxUtil.convertStringToList(str)将字符串按逗号分隔符转化为字符串集合SaFoxUtil.convertListToString(list)将集合按逗号连接成一个字符串SaFoxUtil.convertStringToArray(str)String 转 Array按逗号切割SaFoxUtil.convertArrayToString(arr)Array 转 String按逗号切割SaFoxUtil.emptyList()返回一个空集合SaFoxUtil.toList(... strs)String 数组可变参数转集合4.2 部分方法的源码细节模糊匹配vagueMatch内部支持*通配符匹配Sa-Token 的路由匹配、接口地址匹配等场景底层都复用了该方法是实现/user/*这类路径规则的核心逻辑。类型转换getValueByTypeSaTokenConfigFactory在读取 properties 文件后正是通过该方法把字符串值反射转换为目标字段类型int、boolean、long 等它是配置字符串 → 配置对象链路中的关键一环。URL 拼接joinParam/joinSharpParam会自动识别 url 中是否已包含?或正确决定新参数的拼接分隔符joinSharpParam则专门处理#锚点后的参数常用于单页应用H5场景。搜索searchList第一个重载支持prefix前缀过滤与keyword关键字模糊匹配以及start/size分页和sortType排序方式适合在内存中实现简单的关键词搜索 分页。五、SaTokenConfigFactory非 IOC 环境下的配置工厂SaTokenConfigFactory是配置对象工厂类位于 sa-token-core/src/main/java/cn/dev33/satoken/config/SaTokenConfigFactory.java。它的作用是根据 properties 配置文件创建SaTokenConfig配置对象。源码注释明确说明只有在非 IOC非 Spring 等容器环境下你才会用到此类——在 Spring Boot 项目中配置通常由 starter 自动读取application.yml完成装配无需手动调用。5.1 使用步骤第一步在项目根目录classpath 下创建配置文件sa-token.properties# token 名称 (同时也是 cookie 名称) tokenNamesatoken # token 有效期单位秒 默认30天-1 代表永久有效 timeout2592000 # token 最低活跃频率单位秒如果 token 超过此时间没有访问系统就会被冻结默认-1 代表不限制永不冻结 activeTimeout-1 # 是否允许同一账号多地同时登录 为 true 时允许一起登录, 为 false 时新登录挤掉旧登录 isConcurrenttrue # 在多人登录同一账号时是否共用一个 token 为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token isSharefalse # token 风格默认可取值uuid、simple-uuid、random-32、random-64、random-128、tik tokenStyleuuid # 是否输出操作日志 isLogfalse第二步使用代码读取配置并注入 SaManager// 设置配置文件地址默认即为 sa-token.properties可省略 SaTokenConfigFactory.configPath sa-token.properties; // 获取配置信息到 config 对象 SaTokenConfig config SaTokenConfigFactory.createConfig(); // 注入到 SaManager 中 SaManager.setConfig(config);5.2 源码级原理从源码可以看到createConfig()的实现分三步readPropToMap(path)通过ClassLoader.getResourceAsStream从 classpath 加载配置文件并读入MapString, String若文件不存在返回null不会抛异常配置项将全部保持默认值initPropByMap(map, new SaTokenConfig())遍历SaTokenConfig类的所有字段按字段名在 Map 中取值有配置则通过反射field.set(...)赋值无配置则跳过返回填充好的配置对象。这个过程说明sa-token.properties中的键名与SaTokenConfig类的字段名一一对应如tokenName、timeout、activeTimeout、isConcurrent、isShare、tokenStyle、isLog等。加载失败时会抛出带CODE_10021错误码的SaTokenException属性反射赋值失败时抛出带CODE_10022错误码的异常。setConfig注入后还会触发 banner 打印、日志颜色判定与全局事件广播见上文 SaManager 机制。另外createConfig()还有一个重载createConfig(String path)支持在运行时动态指定任意路径的配置文件。六、SpringMVCUtilServlet 环境下的原生对象获取SpringMVCUtil是 SpringMVC 场景的操作工具类位于sa-token-spring-boot-starter模块实现见 sa-token-starter/sa-token-spring-boot-starter/src/main/java/cn/dev33/satoken/spring/SpringMVCUtil.java在 Spring Boot 3/4 场景下对应 sa-token-spring-boot-webmvc-v3v4-common 中的同类SpringMVCUtil.getRequest(); // 获取本次请求的 request 对象原生 HttpServletRequest SpringMVCUtil.getResponse(); // 获取本次请求的 response 对象原生 HttpServletResponse SpringMVCUtil.isWeb(); // 判断当前是否处于 Web 上下文中注意这里返回的是原生HttpServletRequest/HttpServletResponse而非 Sa-Token 包装后的SaRequest/SaResponse。如果你需要跨容器Servlet / WebFlux / Solon 等的统一抽象 API应优先使用SaHolder.getRequest()/SaHolder.getResponse()如果你明确处于 SpringMVC 环境、需要调用原生 Servlet API则用SpringMVCUtil。isWeb()常用于判断当前线程是否处于 Web 请求上下文中避免在非 Web 场景如定时任务误用请求对象。七、SaReactorHolder SaReactorSyncHolderWebFlux 响应式场景工具当 Sa-Token 集成 ReactorSpring WebFlux时可通过这两个类操作ServerWebExchange。它们位于sa-token-reactor-spring-boot-starter模块实现见 sa-token-starter/sa-token-reactor-spring-boot-starter/src/main/java/cn/dev33/satoken/reactor/context/SaReactorHolder.java 与 SaReactorSyncHolder.java。7.1 SaReactorHolder响应式方式// 异步方式获取 ServerWebExchange 对象 SaReactorHolder.getMonoExchange().map(e - { System.out.println(e); return e; }); // 在 Mono 链中调用 Sa-Token 同步 API返回 MonoRController 中需 return return SaReactorHolder.sync(() - { StpUtil.checkLogin(); return SaResult.ok(); });getMonoExchange()返回MonoServerWebExchange适合在响应式链中拿到当前请求对象sync(...)是响应式世界的桥接器WebFlux 是响应式异步的而 Sa-Token 的 API 大多是同步的直接调用可能丢失上下文或导致线程切换后取不到ServerWebExchange。sync负责把同步逻辑封装进Mono保证在正确的上下文中执行StpUtil系列同步 APIController 中需要return该 Mono 才能生效。7.2 SaReactorSyncHolder同步方式WebFilter 等场景// 同步方式WebFilter 等场景 SaReactorSyncHolder.setContext(exchange); // 写入当前请求的 ServerWebExchange SaReactorSyncHolder.getExchange(); // 获取当前请求的 ServerWebExchange SaReactorSyncHolder.clearContext(); // 清除当前上下文 SaReactorSyncHolder.setContext(exchange, () - {}); // 在指定 exchange 上下文中执行代码块并返回结果setContext(exchange)/getExchange()/clearContext()对应 ThreadLocal 的写、读、清用于在WebFilter 等同步非响应式回调场景中临时挂载、获取与清理当前请求的ServerWebExchangesetContext(exchange, () - {})接受一个函数式参数在指定的 exchange 上下文中执行代码块并返回结果执行完毕后自动清理上下文避免 ThreadLocal 泄漏——在 WebFlux 这类线程复用的环境中用完清理上下文是必须养成的习惯。7.3 两个类的分工总结场景推荐类特点响应式链内Mono/Flux 中SaReactorHolder返回Mono可.map()链式处理sync()包裹同步鉴权逻辑同步回调WebFilter、拦截器等SaReactorSyncHolderThreadLocal 读写当前 exchange支持执行代码块自动清理八、总结如何选择正确的全局工具类需求使用哪个类获取/替换全局配置、DAO、权限接口、上下文等组件SaManager获取当前请求的 Request / Response / Storage / Application 抽象对象SaHolder基于 URL 做拦截式鉴权SaRouter字符串、集合、URL、日期等通用工具SaFoxUtil非 IOC 环境下从 properties 手动构建配置SaTokenConfigFactorySpringMVC 环境获取原生 Servlet 对象SpringMVCUtilWebFlux 响应式环境操作 ServerWebExchangeSaReactorHolder/SaReactorSyncHolder掌握这些全局类就等于拿到了 Sa-Token 的总钥匙无论是阅读框架源码、排查鉴权问题还是自定义扩展如替换 DAO 实现、注入自定义序列化器、注册全局监听器都能从SaManager与SaHolder出发迅速定位到对应组件。更多扩展方向可参考 HTTP 请求扩展、参数签名 与 路由拦截式鉴权 等章节。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考