Sa-Token 微服务鉴权依赖引入详解网关与子服务为什么要分开引入 Starter【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token在微服务架构中使用 Sa-Token 时最常见的“低级错误”恰恰出在依赖引入环节网关和子服务引入了错误的 Starter、把 Sa-Token 依赖直接放在顶级父 pom 里、或在同一个项目里同时引入两个 Starter 导致项目无法启动。本文基于官方文档 Sa-Token 微服务依赖引入说明 与仓库源码讲清 Sa-Token 在微服务场景下的依赖选择规则、两个核心 Starter 的底层差异以及网关与子服务之间靠 Redis 同步会话数据所需的集成包帮助你在搭建网关鉴权 子服务校验的架构时一次配对环境依赖。核心原则网关和内部服务必须分开引入官方文档在强调依赖引入规则后依然在微服务章节专门再次重申这条原则原因是交流群中相当一部分疑难 bug排查到最后都源于依赖引入错误在微服务架构中使用 Sa-Token 时网关和内部服务要分开引入 Sa-Token 依赖不要直接在顶级父 pom 中引入 Sa-Token。这条原则背后的逻辑是网关与内部服务运行在完全不同的 Web 容器模型上Reactor 响应式 vs Servlet 阻塞式它们所需的 Starter 不同。如果在顶级父 pom 中统一引入某一个 Starter其传递依赖会污染所有子模块——例如给一个基于 WebFlux 的网关模块引入了 Servlet 体系的 Starter鉴权链路就会与容器模型错配表现为登录态时好时坏、Token 读取不到等难以定位的问题。因此每个微服务模块应当在自己的 pom 中按自身技术栈显式声明依赖。两个核心 Starter 与版本选择微服务场景下需要关注的依赖只有两个sa-token-spring-boot-starterServlet 体系和sa-token-reactor-spring-boot-starterReactor 响应式体系。Servlet 体系sa-token-spring-boot-starterMaven 方式!-- Sa-Token 权限认证在线文档https://sa-token.com -- dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version${sa.top.version}/version /dependencyGradle 方式// Sa-Token 权限认证在线文档https://sa-token.com implementation cn.dev33:sa-token-spring-boot-starter:${sa.top.version}按 SpringBoot 大版本选择对应 artifactIdSpringBoot 2.xsa-token-spring-boot-starterSpringBoot 3.xsa-token-spring-boot3-starterSpringBoot 4.xsa-token-spring-boot4-starterReactor 响应式体系sa-token-reactor-spring-boot-starterMaven 方式!-- Sa-Token 权限认证Reactor响应式集成在线文档https://sa-token.com -- dependency groupIdcn.dev33/groupId artifactIdsa-token-reactor-spring-boot-starter/artifactId version${sa.top.version}/version /dependencyGradle 方式// Sa-Token 权限认证Reactor响应式集成在线文档https://sa-token.com implementation cn.dev33:sa-token-reactor-spring-boot-starter:${sa.top.version}同样按 SpringBoot 大版本选择SpringBoot 2.xsa-token-reactor-spring-boot-starterSpringBoot 3.xsa-token-reactor-spring-boot3-starterSpringBoot 4.xsa-token-reactor-spring-boot4-starter当前仓库源码版本为1.46.0见根 pom.xml 中的revision1.46.0/revision引入时可将${sa.top.version}替换为你实际使用的版本号如需锁定整套 Sa-Token 依赖版本可配合仓库中的 sa-token-bom 统一托管。如何选择看你的服务基于什么模型该选哪个 Starter取决于服务所使用的底层 Web 模型服务角色典型技术栈引入依赖内部基础服务SpringBoot 默认 web 模块SpringMVC基于 Servlet 模型sa-token-spring-boot-starterServlet 模型网关Zuulsa-token-spring-boot-starterReactor 模型网关SpringCloud Gateway、ShenYu 等sa-token-reactor-spring-boot-starter并且注册全局过滤器两点补充说明理论上Zuul并不支持Spring Boot 3如果你用 Zuul 做 Servlet 模型网关应搭配 Spring Boot 2 体系使用。Servlet 环境下的完整集成流程见 在SpringBoot环境集成。基于 Reactor 模型的网关必须额外注册全局过滤器SaReactorFilter否则请求不会进入 Sa-Token 的鉴权链路。WebFlux/Gateway 环境的完整集成步骤见 在WebFlux环境集成微服务网关鉴权的整体方案见 微服务网关鉴权。红线同一个项目里绝不可同时引入两个 Starter官方文档明确警告切不可直接在一个项目里同时引入sa-token-spring-boot-starter和sa-token-reactor-spring-boot-starter否则会造成项目无法启动。从源码结构看这条红线的合理性是成立的。对比两个 Starter 的 pomsa-token-spring-boot-starter/pom.xml 依赖spring-boot-starter-webServlet 容器栈、sa-token-servlet、sa-token-spring-boot-webmvc-reactor-v2v3v4-common和sa-token-jacksonsa-token-reactor-spring-boot-starter/pom.xml 依赖sa-token-core、reactor-coreoptional、spring-weboptional并同时依赖同一个公共模块sa-token-spring-boot-webmvc-reactor-v2v3v4-common和sa-token-jackson。两个 Starter 会共同拉入同一套公共自动配置模块同时又各自携带 Servlet 与 WebFlux 两套容器栈的 Bean 定义。若在同一应用中叠加两套面向不同请求模型的鉴权组件Servlet 过滤器与 WebFilter会同时被装配Bean 冲突与容器错配将导致项目无法启动。因此选型必须在模块层面“二选一”而微服务架构天然满足这一点网关选一个、子服务选另一个各模块依赖互不干扰。源码透视两个 Starter 各自提供的全局过滤器两个 Starter 的差异最终落在它们各自提供的全局鉴权过滤器上。Servlet 模型SaServletFilterSaServletFilter.java 实现了标准javax.servlet.Filter接口类注释声明“默认优先级为 -100尽量保证在其它过滤器之前执行”通过Order(SaTokenConsts.ASSEMBLY_ORDER)指定。其核心字段包括includeList/excludeList拦截与放行路由清单通过addInclude(...)/addExclude(...)链式配置auth认证函数每次请求执行error认证函数发生异常时的异常处理函数beforeAuth前置函数在认证函数之前执行且不受 includeList 与 excludeList 限制所有路由请求都会进入。doFilter方法的执行逻辑是先执行beforeAuth再由SaRouter.match(includeList).notMatch(excludeList).check(...)按路由匹配执行auth捕获BackResultException时直接向响应写出结果并终止请求其余异常交由error函数处理后返回最后放行chain.doFilter。Reactor 模型SaReactorFilterSaReactorFilter.java 实现 Spring WebFlux 的WebFilter接口同样是Order(SaTokenConsts.ASSEMBLY_ORDER)优先级 -100字段与钩子函数设计与SaServletFilter完全对称。关键差异在于filter方法进入时先调用SaReactorSyncHolder.setContext(exchange)将ServerWebExchange绑定到上下文因为响应式链路是异步的后续鉴权 API 需要从当前线程安全地取到请求信息认证与异常处理逻辑与 Servlet 版一致finally中清理上下文最后返回chain.filter(exchange)。这也解释了文档中“Reactor 网关必须注册全局过滤器”的原因在 WebFlux/Gateway 环境中框架不会替你自动挂载过滤器需要显式注册一个SaReactorFilterBean。参考 在WebFlux环境集成 中的配置示例/** * [Sa-Token 权限认证] 全局配置类 */ Configuration public class SaTokenConfigure { /** * 注册 [Sa-Token全局过滤器] */ Bean public SaReactorFilter getSaReactorFilter() { return new SaReactorFilter() // 指定 [拦截路由] .addInclude(/**) /* 拦截所有path */ // 指定 [排除放行路由] .addExclude(/user/login) // 认证函数 每次访问执行 .setAuth(r - SaRouter.match(/user/**).check(r - StpUtil.checkLogin())); } }会话数据同步必须引入 Redis 集成包微服务架构中网关和内部服务是各自独立进程登录在网关完成、校验却在各子服务中发生。默认 Sa-Token 将会话数据保存在内存中重启即丢失且无法跨节点共享因此网关与子服务之间必须通过一个共享存储同步 Token 与会话数据——官方方案就是引入 Redis 集成包!-- Sa-Token 整合 RedisTemplate -- dependency groupIdcn.dev33/groupId artifactIdsa-token-redis-template/artifactId version${sa.top.version}/version /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependencyGradle 方式// Sa-Token 整合 RedisTemplate implementation cn.dev33:sa-token-redis-template:${sa.top.version} implementation org.apache.commons:commons-pool2从源码看sa-token-redis-template/pom.xml 只依赖sa-token-core与spring-boot-starter-data-redis实现类为 SaTokenDaoForRedisTemplate.java它实现了 Sa-Token 的 DAO 扩展接口把 Token-Session 等数据的读写从内存转接到 Rediscommons-pool2则用于提供 Redis 连接池。Redis 集成的完整背景内存模式的优缺点、其它缓存扩展方案见 Sa-Token 集成 Redis。一个重要的版本前提自v1.46.0起sa-token-redis-template/sa-token-redisson使用了 Redis 6.0 的SET KEEPTTL特性若 Redis 服务低于 6.0会报ERR syntax error。如果你的 Redis 版本较老需要先升级 Redis 或参考官方常见问题中的兼容方案。微服务依赖引入检查清单结合本文内容微服务接入 Sa-Token 前可逐项核对顶层 pom 不引 Sa-Token所有 Sa-Token 依赖只出现在各具体服务模块中网关与子服务分开声明。按模型二选一SpringMVC/Servlet 网关如 Zuul用sa-token-spring-boot-starterReactor 网关SpringCloud Gateway、ShenYu用sa-token-reactor-spring-boot-starter且后者必须注册SaReactorFilter全局过滤器。Boot 大版本对齐SpringBoot 3.x / 4.x 分别使用带3/4后缀的 Starter不要混用。同一项目不同时引入两个 Starter这是官方明确警告会导致项目无法启动的冲突组合。网关与所有子服务统一引入sa-token-redis-templatecommons-pool2并确认 Redis 6.0 环境保证登录态在网关和各子服务间通过 Redis 共享。完成以上配置后即可按 微服务网关鉴权 一文实现“网关统一鉴权 子服务校验 Token”的微服务鉴权架构。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考