1. 项目背景与核心价值在微服务架构中网关作为系统流量的统一入口承担着路由转发和权限控制的双重职责。传统方案中开发者常采用Spring Security进行鉴权但其配置复杂度高、学习曲线陡峭。而Sa-Token作为轻量级Java权限认证框架以注解式鉴权为核心特色仅需简单配置即可实现完善的登录认证体系。本方案将SpringCloud Gateway与Sa-Token深度整合打造了一套开箱即用的微服务鉴权解决方案。实际开发中我们经常遇到这样的场景商品服务、订单服务等业务模块需要统一的登录验证但又不希望每个服务重复实现鉴权逻辑。通过网关层集成Sa-Token可以实现一次登录全链通行的效果。当用户访问/product/1接口时网关会自动校验登录状态未登录用户将收到401响应而合法请求则会携带令牌透传到下游服务。2. 技术栈选型解析2.1 SpringCloud Gateway优势作为SpringCloud官方推荐的第二代网关相比Zuul1.x具有明显性能优势基于Netty的非阻塞IO模型支持长连接内置负载均衡器支持集成Ribbon支持WebSocket协议更灵活的路由断言(Predicate)和过滤器(Filter)机制关键配置示例spring: cloud: gateway: routes: - id: product-service uri: lb://shop-product predicates: - Path/product-serv/** filters: - StripPrefix12.2 Sa-Token核心特性对比传统Shiro、Spring SecuritySa-Token具有以下差异化优势注解鉴权SaCheckLogin、SaCheckRole等注解直接标注在Controller方法上分布式会话默认集成Redis存储令牌天然支持分布式环境踢人下线支持账号互斥登录、指定令牌强制失效无侵入设计与业务代码解耦不需要继承特定父类登录接口典型实现RestController RequestMapping(/user) public class AuthController { PostMapping(/doLogin) public SaResult doLogin(String username, String password) { if(zhang.equals(username) 123456.equals(password)){ StpUtil.login(10001); return SaResult.ok(登录成功); } return SaResult.error(登录失败); } }3. 完整实现步骤3.1 认证中心搭建创建shop-auth模块引入关键依赖dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置Redis连接application.ymlsa-token: token-name: satoken timeout: 86400 activity-timeout: -1 is-concurrent: true is-share: true实现登录接口SaCheckLogin GetMapping(/info) public SaResult getInfo() { return SaResult.data(StpUtil.getTokenInfo()); }3.2 网关层集成添加全局过滤器Component public class SaTokenFilter implements GlobalFilter { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String path exchange.getRequest().getURI().getPath(); // 放行登录接口 if(path.contains(/auth/user/doLogin)){ return chain.filter(exchange); } // 其他接口校验登录状态 try { StpUtil.checkLogin(); return chain.filter(exchange); } catch (NotLoginException e) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } } }配置路由规则routes: - id: auth-service uri: lb://shop-auth predicates: - Path/auth/** filters: - StripPrefix13.3 业务服务保护在商品服务Controller添加注解RestController RequestMapping(/product) public class ProductController { SaCheckLogin GetMapping(/{id}) public Product getById(PathVariable Long id) { return productService.getById(id); } }4. 实战问题排查指南4.1 常见异常处理异常现象可能原因解决方案502 Bad Gateway网关到微服务网络不通检查nacos服务注册状态401 UnauthorizedToken校验失败确认Redis连接正常403 Forbidden权限不足检查SaCheckRole注解配置4.2 性能优化建议令牌存储优化对于高频访问接口可启用本地缓存SaCheckLogin(type StpUtil.TYPE)限流配置在网关层添加RequestRateLimiter过滤器filters: - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 100 redis-rate-limiter.burstCapacity: 200会话超时策略根据业务场景设置合理的activity-timeoutsa-token: activity-timeout: 1800 # 30分钟无操作失效5. 进阶扩展方向单点登录(SSO)集成RestController RequestMapping(/sso) public class SsoController { GetMapping(/checkLogin) public Object checkLogin(String token) { return SaSsoUtil.checkLogin(token); } }与Spring Security共存方案通过Order控制过滤器顺序使用Sa-Token处理登录认证保留Spring Security的权限模型灰度发布支持spring: cloud: gateway: routes: - id: canary-product uri: lb://shop-product-canary predicates: - Path/product/** - Headerversion, canary实际部署中发现当Redis集群出现网络波动时可能导致令牌校验延迟升高。这时可以通过两种方式缓解配置lettuce连接池参数提高重试能力启用二级缓存将常用令牌暂存本地Caffeine缓存在电商秒杀场景中我们还需要特别注意分布式锁的使用。Sa-Token提供的分布式锁API可以这样使用StpUtil.getLock(seckill_ productId).lock(); try { // 扣减库存逻辑 } finally { StpUtil.getLock(seckill_ productId).unlock(); }
1. 项目背景与核心价值在微服务架构中网关作为系统流量的统一入口承担着路由转发和权限控制的双重职责。传统方案中开发者常采用Spring Security进行鉴权但其配置复杂度高、学习曲线陡峭。而Sa-Token作为轻量级Java权限认证框架以注解式鉴权为核心特色仅需简单配置即可实现完善的登录认证体系。本方案将SpringCloud Gateway与Sa-Token深度整合打造了一套开箱即用的微服务鉴权解决方案。实际开发中我们经常遇到这样的场景商品服务、订单服务等业务模块需要统一的登录验证但又不希望每个服务重复实现鉴权逻辑。通过网关层集成Sa-Token可以实现一次登录全链通行的效果。当用户访问/product/1接口时网关会自动校验登录状态未登录用户将收到401响应而合法请求则会携带令牌透传到下游服务。2. 技术栈选型解析2.1 SpringCloud Gateway优势作为SpringCloud官方推荐的第二代网关相比Zuul1.x具有明显性能优势基于Netty的非阻塞IO模型支持长连接内置负载均衡器支持集成Ribbon支持WebSocket协议更灵活的路由断言(Predicate)和过滤器(Filter)机制关键配置示例spring: cloud: gateway: routes: - id: product-service uri: lb://shop-product predicates: - Path/product-serv/** filters: - StripPrefix12.2 Sa-Token核心特性对比传统Shiro、Spring SecuritySa-Token具有以下差异化优势注解鉴权SaCheckLogin、SaCheckRole等注解直接标注在Controller方法上分布式会话默认集成Redis存储令牌天然支持分布式环境踢人下线支持账号互斥登录、指定令牌强制失效无侵入设计与业务代码解耦不需要继承特定父类登录接口典型实现RestController RequestMapping(/user) public class AuthController { PostMapping(/doLogin) public SaResult doLogin(String username, String password) { if(zhang.equals(username) 123456.equals(password)){ StpUtil.login(10001); return SaResult.ok(登录成功); } return SaResult.error(登录失败); } }3. 完整实现步骤3.1 认证中心搭建创建shop-auth模块引入关键依赖dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency配置Redis连接application.ymlsa-token: token-name: satoken timeout: 86400 activity-timeout: -1 is-concurrent: true is-share: true实现登录接口SaCheckLogin GetMapping(/info) public SaResult getInfo() { return SaResult.data(StpUtil.getTokenInfo()); }3.2 网关层集成添加全局过滤器Component public class SaTokenFilter implements GlobalFilter { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String path exchange.getRequest().getURI().getPath(); // 放行登录接口 if(path.contains(/auth/user/doLogin)){ return chain.filter(exchange); } // 其他接口校验登录状态 try { StpUtil.checkLogin(); return chain.filter(exchange); } catch (NotLoginException e) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } } }配置路由规则routes: - id: auth-service uri: lb://shop-auth predicates: - Path/auth/** filters: - StripPrefix13.3 业务服务保护在商品服务Controller添加注解RestController RequestMapping(/product) public class ProductController { SaCheckLogin GetMapping(/{id}) public Product getById(PathVariable Long id) { return productService.getById(id); } }4. 实战问题排查指南4.1 常见异常处理异常现象可能原因解决方案502 Bad Gateway网关到微服务网络不通检查nacos服务注册状态401 UnauthorizedToken校验失败确认Redis连接正常403 Forbidden权限不足检查SaCheckRole注解配置4.2 性能优化建议令牌存储优化对于高频访问接口可启用本地缓存SaCheckLogin(type StpUtil.TYPE)限流配置在网关层添加RequestRateLimiter过滤器filters: - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 100 redis-rate-limiter.burstCapacity: 200会话超时策略根据业务场景设置合理的activity-timeoutsa-token: activity-timeout: 1800 # 30分钟无操作失效5. 进阶扩展方向单点登录(SSO)集成RestController RequestMapping(/sso) public class SsoController { GetMapping(/checkLogin) public Object checkLogin(String token) { return SaSsoUtil.checkLogin(token); } }与Spring Security共存方案通过Order控制过滤器顺序使用Sa-Token处理登录认证保留Spring Security的权限模型灰度发布支持spring: cloud: gateway: routes: - id: canary-product uri: lb://shop-product-canary predicates: - Path/product/** - Headerversion, canary实际部署中发现当Redis集群出现网络波动时可能导致令牌校验延迟升高。这时可以通过两种方式缓解配置lettuce连接池参数提高重试能力启用二级缓存将常用令牌暂存本地Caffeine缓存在电商秒杀场景中我们还需要特别注意分布式锁的使用。Sa-Token提供的分布式锁API可以这样使用StpUtil.getLock(seckill_ productId).lock(); try { // 扣减库存逻辑 } finally { StpUtil.getLock(seckill_ productId).unlock(); }
