先说结论

网关应该只做三件"横切"的事:统一鉴权、统一限流、流量调度(灰度),业务逻辑全部下沉到服务。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 取值适用场景坑点
按 IPRemoteAddress开放接口防刷NAT 大出口误伤真实用户
按用户解析 token 得到的用户 ID登录后的业务接口未登录流量需要另一档兜底
按接口请求路径 + 方法保护重接口、慢接口粒度粗时互相挤占配额
按租户/API KeyHeader 里的租户标识开放平台配额要与商务协议对齐

被限流的请求返回 429,这个状态码要让前端与调用方显式处理,否则限流会被当成故障放大告警。规范做法是响应体带上"稍后重试"的语义与重试提示,让调用方做退避,而不是无限重连。

实现细节上,令牌桶的 Lua 脚本在一次调用里完成"计算应发令牌 + 扣减 + 返回结果",Redis 单线程模型保证脚本原子执行,多个网关实例共享同一个配额不会竞态超发。代价是限流依赖 Redis 的可用性——Redis 不可用时网关的行为要显式决策:fail-open(放行,保可用)还是 fail-fast(拒绝,保下游),默认值未必符合业务预期,必须写进设计文档。

灰度发布:路由断言组合

灰度思路是把"带标记的流量"路由到新版本实例:

  • 按用户/设备标记:Header 断言匹配灰度标记(如 X-Gray: true),命中的走 lb://order-service-gray,其余走稳定版;
  • 按权重:Weight 断言按分组权重分流,适合全量铺开前的放量节奏;
  • 标记的注入通常就在鉴权过滤器里完成:从 JWT 解出灰度名单用户后写入 header,路由断言据此分流——鉴权与灰度在同一个过滤器链上天然衔接,这也是把灰度标记放进 token 而不是请求参数的理由:外部请求无法伪造灰度身份。

灰度的验收手段要提前设计:灰度实例打独立日志标记、监控按实例分组出曲线,放量节奏才会"看得见"。灰度期必须有回滚预案——路由断言改回稳定版是秒级操作,比回滚代码快得多;预案里写清触发放量回退的指标阈值(错误率、RT)与负责人,放量才不是赌博。

网关设计的三个反模式

三个反模式的共同病根是"网关的身份认知错位"——把它当业务服务、当安全边界、当容量出口来用。网关真正的定位是薄而快的策略执行点:所有策略必须配置化、秒级生效,任何需要写代码才能改的"策略"都不该放在网关里。

  1. 网关里写业务逻辑(拼装报文、算价格),导致网关频繁发版、成为全公司发布瓶颈——网关的发布节奏应该是月级的,出现周级发布说明职责越界;
  2. 过滤器链过长且 getOrder 混乱,鉴权排在限流之后,白白消耗限流配额,慢过滤器还拖累全站延迟;
  3. 全局限流只按 IP,NAT 出口后的大客户被误伤——限流维度必须与业务语义对齐,IP 只配做兜底维度。

一句话收尾:网关是流量入口的闸门:鉴权管安全,限流管容量,灰度管风险,三者都以过滤器 + 路由断言实现。

生产案例

某开放平台上线后,运营陆续收到大客户投诉"高峰期接口频繁失败",监控侧则显示大量 429。排查发现网关当时只配了按 IP 的全局限流,而这家大客户的办公网走统一 NAT 出口,几百个真实用户共享一个 IP,令牌桶按 IP 计数自然天天打满。修复没有简单调大配额——调大等于放弃防护——而是改成双层限流:登录流量按用户 ID 维度限流(每个真实用户独立配额),未登录与异常流量保留按 IP 的兜底层,并对 429 响应补充了重试提示头。上线后大客户投诉清零,开放接口的恶意刷量同时被兜底层拦住。这个案例沉淀的规约是:限流维度上线路前必须回答"同一个 key 后面站着几个人",答不出来就说明维度选错了。

检查清单

  • 过滤器链顺序明确:鉴权在限流之前,getOrder 数值有统一的规划表
  • 鉴权失败快速返回,白名单外置为可配置集合
  • 下游服务对外部传入的身份头做了剥离或网段校验,不无条件信任 X-User-Id
  • 限流维度与业务语义对齐:登录流量按用户,未登录按 IP 兜底
  • 429 响应带了重试语义,前端与调用方有对应的退避处理
  • 灰度标记由网关从 token 注入,路由断言只认网关注入的头
  • 网关里没有业务逻辑,发布频率保持在月级
  • 令牌桶的 replenishRate 与下游真实容量对齐过,不是拍脑袋数字