Spring Cloud Gateway统一鉴权与Redis分布式限流实践

先讲个背景。去年我在一家电商平台类公司主导微服务改造，服务拆到十几个的时候，出了一个特别尴尬的问题：登录鉴权和接口限流这两种横切逻辑，每个服务都自己维护了一套。有的用拦截器，有的用注解，还有的直接写在控制器里，先查用户再查权限，代码风格五花八门。重复代码倒也算了，最要命的是标准不统一，安全评审的时候，大家谁也说不清到底哪些接口还在裸奔。

后来我们把这两件事统一收口到网关层入口，用 Spring Cloud Gateway 做统一网关，用 JWT 做无状态鉴权，再用 Redis 做分布式限流，问题一下子清爽多了。这篇文章就把这套方案的完整落地过程记录下来，包括方案为什么要这么选、过滤器代码怎么组织、限流参数怎么定、实际踩过哪些坑，给正在做类似改造的同学一个可以直接参考的版本。不管你之前有没有接触过 Spring Cloud Gateway，只要对微服务网关有需求，这篇都适用。

1. 为什么把限流和鉴权统一放到网关层

1.1 横切逻辑散落在业务服务里的三个代价

拆微服务的时候，大家习惯按业务边界切分，用户服务、订单服务、支付服务各管一摊。但登录校验、权限控制、限流降级这类横切逻辑不属于任何一个业务域，放进业务服务里就会连续付出三种代价。

第一个代价是重复建设。每个服务都要写一遍 JWT 解析、白名单判断、异常返回，这些东西跟业务本身一点关系都没有，纯粹是重复劳动。第二个代价是标准不一致，也是最危险的。有人校验了 Token，有人忘了校验，有人把密钥硬编码在代码里，有人从配置中心读取，一旦某个服务漏了校验，它上面的所有接口就等于对全网开放。第三个代价是维护成本高。密钥要轮换的时候，十几个服务挨个改配置、发版本、验证，改完还要担心是否有服务没改到位。

网关层天然是流量的统一入口，把这些逻辑集中到这里之后，业务服务只需要关心自己的业务参数，安全策略的调整只改网关一处。Spring Cloud Gateway 基于 Spring WebFlux 和 Netty，全链路非阻塞，作为入口处理高并发场景比传统 Servlet 网关更合适，这也是我们选它的直接原因。有人担心网关层会引入额外跳转延迟，实测在机房内网条件下，单次转发增加的开销在零点几毫秒级别，相对于统一治理带来的收益，这点成本完全值得。

1.2 JWT 无状态鉴权为什么适合网关

鉴权方案无非两大流派：基于 Session，或者基于 Token。Session 方案在微服务里要解决会话共享问题，要么把 Session 丢进 Redis，要么做黏性会话，节点多了以后排查问题非常头疼。JWT 的优势在于无状态，Token 本身自包含，网关只需要拿共享密钥验签，不需要访问 Session 存储，天然适配 WebFlux 这种响应式模型，不会因为要查会话而阻塞事件循环线程。

JWT 由三部分组成：Header 和 Payload 是 Base64URL 编码的 JSON，Signature 是对前两部分的签名。网关验签通过，即代表内容没有被篡改，再配合 exp 过期时间字段做有效期判断，一套完整的校验逻辑就齐了。签名算法常用 HS256 和 RS256，前者是对称密钥，后者是非对称。内部系统用 HS256 配合统一管理的密钥就够用了；如果未来要开放给外部系统使用，建议上 RS256，网关只保留公钥验签。我们的场景是内部服务间调用，所以选了 HS256。

1.3 限流为什么选 Redis 这套组合

限流方案我对比过三类。第一类是本地限流，比如 Guava 的 RateLimiter，实现简单，但它只对单实例生效，网关一扩展成多实例，每台机器的计数是独立的，总流量变成机器数的倍数，限流就形同虚设。第二类是功能完整的限流组件，比如 Sentinel，功能很强，支持各种规则和可视化控制台，但对一个中小团队来说，引入它意味着多维护一套控制台和规则体系，负担不小。

第三类就是 Redis 这套组合。Redis 本来就是微服务标配，用 Redis 加 Lua 脚本实现令牌桶，跨实例生效，计数共享，而且 Lua 脚本在 Redis 端原子执行，不会出现并发扣减超卖的问题。Spring Cloud Gateway 内置了 RedisRateLimiter，也就是 RequestRateLimiter 过滤器，封装好了令牌桶的核心逻辑，我们只需要实现一个 KeyResolver，告诉它按什么维度来做限流。选 Redis 方案，本质上是选了一条最省事、又具备生产可用性的路线。

2. 环境准备与基础配置

2.1 版本别踩激进组合，Boot 2.7 加 Cloud 2021 稳妥

网关工程对版本匹配的要求比普通业务服务更高，因为 Spring Cloud Gateway 的版本跟 Spring Boot、Spring Cloud 的版本是强绑定的，乱配很容易在启动时直接报错。我这边长期稳定使用的组合如下。

我这次按组合 A 来讲，因为存量微服务大多还是 JDK 8。核心依赖就四个：gateway、reactive 的 redis、JJWT 的三件套。

<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis-reactive</artifactId> </dependency> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-api</artifactId> <version>0.11.5</version> </dependency> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-impl</artifactId> <version>0.11.5</version> <scope>runtime</scope> </dependency> <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt-jackson</artifactId> <version>0.11.5</version> <scope>runtime</scope> </dependency>

这里有一个非常关键的红线：网关工程绝对不要引入 spring-boot-starter-web，因为 Gateway 是 WebFlux 的 Netty 模型，引入 Spring MVC 的 Tomcat 后，两个容器会打架，导致路由无法访问或者端口冲突。也别为了图方便把网关和业务接口写在同一个工程里，网关专注转发和横切逻辑，业务服务独立部署，这个边界要保持住。

2.2 最基础的三块配置

网关配置可以拆成三块：Redis 连接、路由转发、默认过滤器。下面这份 YAML 是整个方案的骨架，后面 JWT 和限流都会挂到这个骨架上。

spring: application: name: gateway-service redis: host: 127.0.0.1 port: 6379 timeout: 500ms lettuce: pool: max-active: 16 max-idle: 8 cloud: gateway: default-filters: - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 10 redis-rate-limiter.burstCapacity: 20 redis-rate-limiter.requestedTokens: 1 key-resolver: "#{@userKeyResolver}" routes: - id: user-service uri: lb://user-service predicates: - Path=/api/user/** filters: - StripPrefix=1 - id: order-service uri: lb://order-service predicates: - Path=/api/order/** filters: - StripPrefix=1

default-filters 的作用是让指定的过滤器对网关上所有路由生效，RequestRateLimiter 就是我们要的限流过滤器。key-resolver 用的是 SpEL 表达式，指定一个 Bean 名，这个 Bean 就是限流维度的解析器，后面第 4 节细说。这里先提醒一句：表达式里的 #{@xxx} 一个字符都不能少，写成纯字符串或者少了花括号，启动时要么报错，要么限流直接不生效。

2.3 路由和服务发现的联动

上面的 uri 写的是 lb://user-service，这个前缀是 LoadBalancer 的缩写，意思是按服务名从注册中心拿实例列表，再做负载均衡。要让它跑起来，需要引入服务发现组件，Nacos、Eureka 都行，并在配置里标注好注册中心地址。有了这一层，网关就不关心实例 IP 和端口的变化了，服务扩缩容、上下线都对网关透明。

StripPrefix=1 是为了把第一段前缀剥掉再转发。比如外部请求路径是 /api/user/info，转发给 user-service 时变成 /info，业务服务里就不需要额外加一层多余的 context-path 处理。这里的规则要根据你业务服务自己定义的接口前缀来调整，没有绝对标准，关键是前后端、网关、下游三层对这个前缀的约定要一致，否则会出现 404 排查半天。

3. JWT 鉴权过滤器的完整实现

3.1 JWT 校验的三个核心环节

用 JWT 做鉴权，网关这边要做的其实是三个环节：把请求头里的 Token 取出来，验签确认没被篡改，再检查过期时间并把身份信息透传给下游。取 Token 这一步要处理几种异常情况，没带 Authorization 头、带了但前缀不是 Bearer、前缀后没跟内容，这些都不能直接放行。

验签用的是 JJWT 的 parser 操作，它会自动完成签名算法匹配、密钥校验、过期时间校验。过期会抛出 ExpiredJwtException，签名不合法、数据被篡改会抛出 JwtException，格式错误会抛 IllegalArgumentException。把这些异常分类处理，返回给前端的信息才有区分度，前端才好决定是跳登录页还是提示重试。

3.2 鉴权过滤器核心代码：解析、校验、透传一步到位

我选择实现 GlobalFilter 接口，把它做成一个全局过滤器。这样它会在网关处理任何路由之前先执行，统一完成校验，不存在哪个路由漏配过滤器的问题。

@Component public class JwtAuthGlobalFilter implements GlobalFilter, Ordered { private static final String SECRET = "abcdefghijklmnopqrstuvwxyz0123456789"; private final SecretKey secretKey = Keys.hmacShaKeyFor(SECRET.getBytes(StandardCharsets.UTF_8)); private static final List<String> WHITE_LIST = List.of( "/api/auth/login", "/api/auth/register", "/actuator/**" ); private final PathMatcher pathMatcher = new AntPathMatcher(); @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { // 1. 白名单直接放行 String path = exchange.getRequest().getURI().getPath(); for (String pattern : WHITE_LIST) { if (pathMatcher.match(pattern, path)) { return chain.filter(exchange); } } // 2. CORS 预检请求放行 if (HttpMethod.OPTIONS.equals(exchange.getRequest().getMethod())) { return chain.filter(exchange); } // 3. 校验 Authorization 头 String header = exchange.getRequest().getHeaders().getFirst(HttpHeaders.AUTHORIZATION); if (!StringUtils.hasText(header) || !header.startsWith("Bearer ")) { return writeError(exchange, "未携带认证Token或格式错误"); } String token = header.substring(7); try { Claims claims = Jwts.parserBuilder() .setSigningKey(secretKey) .build() .parseClaimsJws(token) .getBody(); String userId = claims.get("userId", String.class); String username = claims.get("username", String.class); // 4. 删除自定义头后重新写入，防止客户端伪造身份 ServerHttpRequest newRequest = exchange.getRequest().mutate() .headers(h -> { h.remove("X-User-Id"); h.remove("X-Username"); h.remove(HttpHeaders.AUTHORIZATION); }) .header("X-User-Id", userId) .header("X-Username", username) .build(); return chain.filter(exchange.mutate().request(newRequest).build()); } catch (ExpiredJwtException e) { return writeError(exchange, "Token已过期"); } catch (JwtException | IllegalArgumentException e) { return writeError(exchange, "Token无效"); } } @Override public int getOrder() { return -100; } }

这段代码里有几个细节值得讲一下。第一，白名单用 AntPathMatcher 匹配，支持 /actuator/** 这种通配符，比字符串 equals 灵活得多。第二，我先把 X-User-Id、X-Username 从请求头里删掉再写入，防止外部客户端伪造身份头直接骗过下游，这个细节很多同学容易漏。第三，下游服务会看到请求头里的 Authorization 已经被移除，这能避免 Token 在内部链路中继续传播，降低泄漏风险。

getOrder() 返回 -100 是为了让这个过滤器比内置过滤器更早执行，关于顺序的坑在第 5 节详细说。

3.3 白名单与预检请求怎么放行

登录、注册、健康检查这类接口本身没有 Token 或者不需要鉴权，必须放在白名单里。白名单放在代码里最省事，但生产环境我更推荐放到配置中心，因为新增一个放行路径不用重新发版。白名单配置和 PathMatcher 结合使用，能同时支持精确路径和通配符路径。

CORS 预检请求也必须在鉴权之前放行。浏览器跨域时会先发一个 OPTIONS 请求探路，这个请求不会带 Authorization 头，如果不放行会被当成未认证拒绝，前端页面所有跨域请求都会失败。放行预检请求不等于放开跨域，真正的 CORS 响应头要由网关统一配置。

3.4 Token 失效后的统一返回

鉴权失败时，直接抛异常让框架处理，返回的内容可能不统一。我在过滤器里写了一个 writeError 工具方法，把所有鉴权失败统一封装成 JSON 格式返回。

private Mono<Void> writeError(ServerWebExchange exchange, String message) { ServerHttpResponse response = exchange.getResponse(); response.setStatusCode(HttpStatus.UNAUTHORIZED); response.getHeaders().setContentType(MediaType.APPLICATION_JSON); byte[] bytes = ("{\"code\":401,\"message\":\"" + message + "\"}") .getBytes(StandardCharsets.UTF_8); return response.writeWith(Mono.just(response.bufferFactory().wrap(bytes))); }

前端拿到 401 后统一跳转登录页，拿到 403 再提示无权限。把 code 和 message 做成固定的 JSON 结构，前端对接起来就不需要逐个接口特殊处理。

4. 基于 Redis 的分布式限流落地

4.1 RedisRateLimiter 与令牌桶的实现逻辑

Spring Cloud Gateway 自带的 RedisRateLimiter 就是令牌桶的具体实现。令牌桶的思想可以这样理解：桶里有令牌，请求来了拿走一个令牌就放行；桶空了就拒绝。同时有一个匀速补充令牌的过程，补充速度就是恒定速率，桶的容量决定最多能积攒多少令牌，也就是能扛住多大的突发流量。

RateLimiter 在 Redis 里维护的是令牌数和上次补充时间两个关键数据。每次请求过来执行一段 Lua 脚本，脚本在 Redis 端完成“按时间差补充令牌、判断令牌是否够用、扣减令牌”这一整套操作。Lua 脚本原子执行，不会出现两个并发请求同时判断为“还有令牌”然后都放行的超卖问题。这也是为什么一定要用 Redis 而不是普通缓存，普通缓存读取、扣减、写回三步之间存在竞态窗口。

令牌相关的 key 会按请求维度生成，里面带着限流 ID。在 Redis Cluster 环境下，同一用户的限流 key 会因为 ID 里的花括号而落在同一个 slot，不会有跨 slot 操作的报错。这一点能保证 Redis 从单机切换到集群时，限流逻辑不需要改动。

4.2 KeyResolver 的粒度决定限流的公平性

KeyResolver 决定了“按谁限流”。最常见的三个维度是用户 ID、客户端 IP、接口路径加 IP。按用户 ID 限流最公平，每个用户独立计数，一个人刷爆不影响其他人，但要先完成 JWT 鉴权才能拿到用户 ID。按 IP 限流实现简单，但在 NAT 环境下，一个出口 IP 背后可能是整个公司几百个人，会出现“一个人把全公司流量打满”的误伤。按接口路径加 IP 适合对单个热点接口做精细管控。

我这里的实现是优先取用户 ID，取不到再回退到客户端 IP，两者结合。

@Configuration public class RateLimitConfig { @Bean public KeyResolver userKeyResolver() { return exchange -> { String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id"); if (StringUtils.hasText(userId)) { return Mono.just(userId); } String ip = exchange.getRequest().getRemoteAddress() == null ? "anonymous" : exchange.getRequest().getRemoteAddress().getAddress().getHostAddress(); return Mono.just(ip); }; } }

这里有个容易踩的坑：KeyResolver 如果返回空内容，限流过滤器就拿不到 key，这个维度的限流完全失效。所以匿名请求一定要有个兜底值，我统一用“anonymous”或真实 IP。另外，X-Forwarded-For 这个头是可以伪造的，从它取 IP 做限流会被攻击者轻易绕过，建议优先取 ServerWebExchange 里 getRemoteAddress 拿到的真实连接地址，或者配合网关部署层的可信代理配置来取。

4.3 replenishRate 和 burstCapacity 怎么定才合理

限流参数有三个：replenishRate 是令牌补充速率，也就是平均每秒放行多少个请求；burstCapacity 是桶容量，也就是瞬时能扛住的峰值流量；requestedTokens 是每个请求消耗几个令牌，默认 1。

参数不能拍脑袋定，我这里给一个可行的计算路径。先对下游服务做一轮压力测试，找到单实例能稳定扛住的 QPS，假设是 120。网关可能把流量均匀分给 3 个下游实例，那网关总入口理论上最多放到 360，但实际要留安全垫，我一般取下游总承载能力的 70% 到 80%，也就是约 250。replenishRate 就设为 250，这是长时段平均闸门。burstCapacity 看业务是否允许突发，允许的话设成 350，不允许就设成跟 replenishRate 相同。

requestedTokens 平时保持 1 就行。它有个特殊用途是放大消耗，比如某个接口内部要同步调三个下游服务，这样的请求对下游的冲击是普通请求的三倍，你可以把它设成 3，让限流自动对这个重量级接口加权，不需要单独再开一个限流规则。

4.4 限流触发后的 429 响应与告警

RequestRateLimiter 真正触发限流时，会抛出一个 429 的 ResponseStatusException。如果不去处理，默认返回的是框架的异常页面，内容不够友好。我自定义了一个异常处理器，把所有限流失败统一转成标准 JSON 返回，同时带上 Retry-After 响应头，告诉客户端隔多久再重试。

@Component @Order(-1) public class RateLimitErrorHandler implements ErrorWebExceptionHandler { @Override public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) { if (ex instanceof ResponseStatusException rse && rse.getStatusCode() == HttpStatus.TOO_MANY_REQUESTS) { ServerHttpResponse response = exchange.getResponse(); response.setStatusCode(HttpStatus.TOO_MANY_REQUESTS); response.getHeaders().setContentType(MediaType.APPLICATION_JSON); response.getHeaders().set("Retry-After", "1"); byte[] bytes = "{\"code\":429,\"message\":\"请求过于频繁，请稍后再试\"}" .getBytes(StandardCharsets.UTF_8); return response.writeWith(Mono.just(response.bufferFactory().wrap(bytes))); } return Mono.error(ex); } }

这个处理器需要注意 @Order(-1)，让它优先于框架默认的异常处理器执行，否则会被默认逻辑抢先接管。除了返回 429，还要在日志里把限流触发的用户 ID 或者 IP、路径、时间记录下来。限流一旦频繁触发，往往说明有异常流量或者参数设置过严，日志是事后排查的唯一依据。

5. 实操中踩过的坑与排查思路

5.1 鉴权和限流的执行顺序怎么保证

Spring Cloud Gateway 的过滤器执行顺序一直是个让人头疼的点。全局过滤器 GlobalFilter 会被包装成 GatewayFilter 参与排序，优先级由 getOrder 决定，数值越小越靠前。default-filters 里配置的 RequestRateLimiter 是一个普通 GatewayFilter，默认 order 是 0。

所以 JwtAuthGlobalFilter 只要把 getOrder() 设成负数，比如 -100，就能保证先鉴权后限流。这么排的意义在于：限流是按用户维度做的，必须先解析出用户 ID 才能决定把请求塞进哪个桶。如果你把 JWT 过滤器的 order 设成了 0 或正数，限流执行时 X-User-Id 还没写入请求头，KeyResolver 拿不到用户 ID，全部都回退到 IP 维度，限流效果跟你预期会差很远。

进阶的做法是再加一层 IP 维度的前置限流，order 比 JWT 过滤器更靠前，用于挡住大规模无差别攻击。因为 JWT 验签本身消耗 CPU，攻击者用大量 IP 打过来时，如果不先做一层粗粒度限流，网关资源会被签名校验耗尽。IP 层粗限、用户层细限，这个组合在生产环境很常见。

5.2 CORS 预检和鉴权过滤器打架

我们项目的前端是独立域名部署，跨域问题必须解决。网关作为统一入口，CORS 要在网关层配置，下游业务服务再配 @CrossOrigin 已经没用了，因为浏览器访问的是网关的域名，响应头必须由网关来加。

我用的是 Spring Cloud Gateway 的 globalcors 配置。同时鉴权过滤器里对 OPTIONS 请求直接放行，否则预检请求会因为不带 Authorization 头被 401 拦掉。配置跨域时注意 allowedOriginPatterns 用通配符，allowedMethods 要包含 OPTIONS，allowedHeaders 要包含 Authorization 和 Content-Type，缺一个都会导致前端实际请求失败。这类问题特别容易在联调阶段突然出现，排查时先看响应头里有没有 Access-Control-Allow-Origin，一步就能定位。

5.3 限流不生效或误杀的五种典型情况

限流上线后，我们遇到过几次“配置了但没有效果”或者“效果明显过头”的情况，整理成一张速查表，排查时对照着看。

最典型的还是 key-resolver 表达式写错。SpEL 是#{@userKeyResolver}，有人多加了引号，有人写成userKeyResolver，结果 Bean 根本没注入，KeyResolver 返回空，限流直接静默失效。这类问题不像报错那么显眼，日志里没有任何异常，只有流量打进来之后才有感觉。所以上线前一定要用 redis-cli 看一下限流 key 是否真的在生成。

redis-cli --scan --pattern 'request_rate_limiter.*'

5.4 性能开销与稳定性建议

这套方案每个请求会多出两部分开销：一次 Redis 的 Lua 脚本执行，以及一次 JWT 验签。Redis 在局域网内单次往返大概零点几毫秒，JWT 验签是纯内存计算，几微秒量级。在普通配置的单实例网关上，开启鉴权加限流后，吞吐从裸转发的几千 QPS 掉一些，但仍然能保持在千 QPS 级别，具体的数值取决于机器性能和下游响应耗时。对这个量级来说，开销完全可接受。

稳定性的两个建议。Redis 一定要配哨兵或集群，它一旦挂掉，网关的限流过滤器会跟着抛异常，直接影响所有请求。JWT 密钥要放在配置中心，不要写死在代码里，轮换密钥只需要改配置发布，不需要重新打包网关。如果业务有强制登出需求，标准 JWT 是无状态吊销不了的，可以额外维护一个 Redis 黑名单，在鉴权过滤器里查一次，代价是一次额外读取，按需开启即可。

最后说一点个人体会。这套组合被大量生产环境验证过，本身不复杂，但很多同学上来就写代码，结果栽在版本冲突、过滤器顺序、KeyResolver 这三类问题上。我的建议是先花半小时把网关的过滤器执行模型搞清楚，再动手写代码；限流参数宁可从保守值开始，压测后再慢慢放宽。

如果你也在做网关改造，建议的验证顺序是：先跑通路由转发，再叠加 JWT 鉴权，最后再上限流，每一步都单独压测验证。这样出了问题，你能明确是哪一层引入的。网关这一层一旦跑偏，所有业务服务都会跟着遭殃，稳一点比炫技重要。