先说结论
网关应该只做三件"横切"的事:统一鉴权、统一限流、流量调度(灰度),业务逻辑全部下沉到服务。Spring Cloud Gateway 里对应的抓手是 GlobalFilter(全局过滤器链)、内置 RequestRateLimiter 过滤器(Redis + Lua 令牌桶)、Header/Weight 路由断言。三件事共同的实现原则:过滤器链要短,失败要快速返回。网关是所有流量的必经之路,它在过滤器里多花的每一毫秒都会乘以全站 QPS,所以"网关薄、服务厚"不是风格偏好,而是延迟预算的硬约束。
统一鉴权:GlobalFilter 模式
JWT 鉴权的标准写法:白名单放行,其余校验 token,通过后把用户信息透传给下游:
@Component
public class AuthGlobalFilter implements GlobalFilter, Ordered {
private static final Set<String> WHITE_LIST = Set.of("/login", "/register");
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
String path = exchange.getRequest().getPath().value();
if (WHITE_LIST.stream().anyMatch(path::startsWith)) {
return chain.filter(exchange); // 白名单直接放行,不解析 token
}
String token = exchange.getRequest().getHeaders().getFirst("Authorization");
if (token == null || !JwtUtil.verify(token)) {
exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
return exchange.getResponse().setComplete(); // 快速失败,不进业务
}
ServerHttpRequest mutated = exchange.getRequest().mutate()
.header("X-User-Id", JwtUtil.getUserId(token)) // 下游只信任网关注入的头
.header("X-Gray", grayFlagOf(token)) // 灰度标记也在这里一并注入
.build();
return chain.filter(exchange.mutate().request(mutated).build());
}
@Override
public int getOrder() { return -100; } // 越小越靠前,鉴权应排在限流之前
}
把鉴权放在限流之前有一个实际理由:未通过鉴权的请求不应消耗限流配额,否则攻击流量能把正常用户的令牌桶吃光。白名单要维护成可配置的集合而不是写死在代码里——每次加一个免登录接口都要发版网关,是典型的网关过重信号。
安全要点:下游服务必须剔除外部传入的 X-User-Id 等头。先看错误写法:
// 错误写法:下游无条件信任请求头里的用户身份
@GetMapping("/me")
public UserVO me(@RequestHeader("X-User-Id") Long userId) {
// 灾难:外部请求可伪造 X-User-Id 冒充任意用户,
// 只要能绕过网关直连服务端口(内网误连、跳板机实验都可能发生)
return userService.me(userId);
}
// 正确写法:下游入口统一过滤,只信任可信网段的身份头
@Component
public class TrustedHeaderFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain chain)
throws ServletException, IOException {
if (!trustedNetworks.contains(request.getRemoteAddr())) {
// 非可信网段(即外部直连)的请求,剥掉一切身份头
stripIdentityHeaders(request); // 移除 X-User-Id、X-Gray 等
}
chain.doFilter(request, response);
}
}
双保险更稳:网关侧在转发前清理一遍同名外部头,下游再做网段校验——任何一层被绕过,另一层还能兜住。
JWT 无状态的另一面是"签发后无法撤销":踢人、封号、改密码之后,旧 token 在过期前依然有效。网关侧的通行做法是维护一个短 TTL 的黑名单(Redis),鉴权过滤器在校验签名后查一次名单;名单条目的 TTL 与 token 剩余寿命对齐,过期自动失效,查询成本可控。需要更强实时性时再上网关侧的会话校验,把无状态换成有状态的代价要算清楚。
统一限流:Redis 令牌桶
Gateway 内置的 redis-rate-limiter 基于 Redis + Lua 实现令牌桶,Lua 脚本保证"取令牌"在分布式环境下原子执行,多网关实例共享同一个配额:
spring:
cloud:
gateway:
routes:
- id: order-route
uri: lb://order-service
predicates:
- Path=/orders/**
filters:
- name: RequestRateLimiter
args:
redis-rate-limiter.replenishRate: 100 # 每秒补充令牌数 = 稳态 QPS
redis-rate-limiter.burstCapacity: 200 # 桶容量(允许突发上限)
redis-rate-limiter.requestedTokens: 1 # 每次请求消耗令牌数
key-resolver: "#{@ipKeyResolver}" # 按谁限流
KeyResolver 决定限流维度——按 IP、按用户还是按接口,需注册为 Bean。维度选错是限流误伤的第一根因:
@Bean
public KeyResolver ipKeyResolver() {
return exchange -> Mono.just(
Optional.ofNullable(exchange.getRequest().getRemoteAddress())
.map(a -> a.getAddress().getHostAddress())
.orElse("unknown"));
}
| 限流维度 | KeyResolver 取值 | 适用场景 | 坑点 |
|---|---|---|---|
| 按 IP | RemoteAddress | 开放接口防刷 | NAT 大出口误伤真实用户 |
| 按用户 | 解析 token 得到的用户 ID | 登录后的业务接口 | 未登录流量需要另一档兜底 |
| 按接口 | 请求路径 + 方法 | 保护重接口、慢接口 | 粒度粗时互相挤占配额 |
| 按租户/API Key | Header 里的租户标识 | 开放平台 | 配额要与商务协议对齐 |
被限流的请求返回 429,这个状态码要让前端与调用方显式处理,否则限流会被当成故障放大告警。规范做法是响应体带上"稍后重试"的语义与重试提示,让调用方做退避,而不是无限重连。
实现细节上,令牌桶的 Lua 脚本在一次调用里完成"计算应发令牌 + 扣减 + 返回结果",Redis 单线程模型保证脚本原子执行,多个网关实例共享同一个配额不会竞态超发。代价是限流依赖 Redis 的可用性——Redis 不可用时网关的行为要显式决策:fail-open(放行,保可用)还是 fail-fast(拒绝,保下游),默认值未必符合业务预期,必须写进设计文档。
灰度发布:路由断言组合
灰度思路是把"带标记的流量"路由到新版本实例:
- 按用户/设备标记:
Header断言匹配灰度标记(如X-Gray: true),命中的走lb://order-service-gray,其余走稳定版; - 按权重:
Weight断言按分组权重分流,适合全量铺开前的放量节奏; - 标记的注入通常就在鉴权过滤器里完成:从 JWT 解出灰度名单用户后写入 header,路由断言据此分流——鉴权与灰度在同一个过滤器链上天然衔接,这也是把灰度标记放进 token 而不是请求参数的理由:外部请求无法伪造灰度身份。
灰度的验收手段要提前设计:灰度实例打独立日志标记、监控按实例分组出曲线,放量节奏才会"看得见"。灰度期必须有回滚预案——路由断言改回稳定版是秒级操作,比回滚代码快得多;预案里写清触发放量回退的指标阈值(错误率、RT)与负责人,放量才不是赌博。
网关设计的三个反模式
三个反模式的共同病根是"网关的身份认知错位"——把它当业务服务、当安全边界、当容量出口来用。网关真正的定位是薄而快的策略执行点:所有策略必须配置化、秒级生效,任何需要写代码才能改的"策略"都不该放在网关里。
- 网关里写业务逻辑(拼装报文、算价格),导致网关频繁发版、成为全公司发布瓶颈——网关的发布节奏应该是月级的,出现周级发布说明职责越界;
- 过滤器链过长且
getOrder混乱,鉴权排在限流之后,白白消耗限流配额,慢过滤器还拖累全站延迟; - 全局限流只按 IP,NAT 出口后的大客户被误伤——限流维度必须与业务语义对齐,IP 只配做兜底维度。
一句话收尾:网关是流量入口的闸门:鉴权管安全,限流管容量,灰度管风险,三者都以过滤器 + 路由断言实现。
生产案例
某开放平台上线后,运营陆续收到大客户投诉"高峰期接口频繁失败",监控侧则显示大量 429。排查发现网关当时只配了按 IP 的全局限流,而这家大客户的办公网走统一 NAT 出口,几百个真实用户共享一个 IP,令牌桶按 IP 计数自然天天打满。修复没有简单调大配额——调大等于放弃防护——而是改成双层限流:登录流量按用户 ID 维度限流(每个真实用户独立配额),未登录与异常流量保留按 IP 的兜底层,并对 429 响应补充了重试提示头。上线后大客户投诉清零,开放接口的恶意刷量同时被兜底层拦住。这个案例沉淀的规约是:限流维度上线路前必须回答"同一个 key 后面站着几个人",答不出来就说明维度选错了。
检查清单
- 过滤器链顺序明确:鉴权在限流之前,getOrder 数值有统一的规划表
- 鉴权失败快速返回,白名单外置为可配置集合
- 下游服务对外部传入的身份头做了剥离或网段校验,不无条件信任 X-User-Id
- 限流维度与业务语义对齐:登录流量按用户,未登录按 IP 兜底
- 429 响应带了重试语义,前端与调用方有对应的退避处理
- 灰度标记由网关从 token 注入,路由断言只认网关注入的头
- 网关里没有业务逻辑,发布频率保持在月级
- 令牌桶的 replenishRate 与下游真实容量对齐过,不是拍脑袋数字