前言：在微服务架构中，服务会被拆分为用户、订单、商品、支付、秒杀等数十个独立服务。如果客户端直接逐个调用微服务，会出现接口地址混乱、鉴权重复、限流分散、跨域难以统一管理、日志散乱等一系列问题。

API网关就是微服务系统的统一入口、流量门户、调度中枢，所有客户端请求统一经过网关，再由网关转发至对应微服务。

一、微服务网关技术背景与发展历程

1.1 为什么需要网关？

单体架构无网关概念，所有请求直接访问单体应用。但微服务拆分后，架构痛点全面暴露：

• 客户端需要维护大量微服务接口地址，对接成本极高；

• 每个服务单独实现鉴权、限流、跨域、日志，代码冗余且规范不统一；

• 无法统一管控流量，无法实现灰度发布、路由分发、黑名单拦截；

• 服务暴露公网，安全风险高，没有统一的请求过滤机制。

网关的核心价值：统一入口、统一管控、剥离公共非业务能力，让微服务只专注业务逻辑。

1.2 网关技术演进（Zuul → Gateway）

1.2.1 第一代网关：Zuul1.x

基于 Servlet 阻塞模型，同步阻塞架构，每一个请求占用一个线程，高并发场景下线程阻塞、吞吐量低、性能瓶颈严重，无法适配电商大促、秒杀等高流量场景，目前已逐步淘汰。

1.2.2 第二代网关：Spring Cloud Gateway

Spring 官方推出的新一代微服务网关，基于 SpringBoot、WebFlux、Reactor 响应式编程实现，非阻塞、异步高并发，完美适配云原生、高流量微服务架构，是目前 Spring Cloud / Alibaba 体系的唯一主流网关。

1.3 技术发展趋势

目前微服务网关已经从单纯的路由转发，演进为全链路流量治理平台，支持动态路由、限流熔断、统一鉴权、灰度发布、链路追踪、请求重写、负载均衡、安全防护等全方位能力，成为微服务架构不可或缺的核心基础设施。

二、Spring Cloud Gateway 核心原理

2.1 核心定位

Spring Cloud Gateway 是一款基于响应式编程的非阻塞 API 网关，用于微服务请求统一路由、过滤、管控，一句话总结：所有请求统一进门、统一处理、精准转发、统一响应。

2.2 三大核心组件（底层核心）

2.2.1 Route（路由）

网关最基础单元，包含 路由ID、目标服务地址、断言规则、过滤器。作用：定义一条完整的请求转发规则，匹配成功则执行转发。

2.2.2 Predicate（断言）

请求匹配条件，支持路径、请求方式、请求头、请求参数、时间、IP 等多种匹配规则。只有所有断言全部匹配成功，当前路由才会生效。

2.2.3 Filter（过滤器）

请求拦截增强器，分为 前置过滤器（Pre）、后置过滤器（Post）。前置可实现鉴权、限流、参数校验、跨域处理；后置可实现响应封装、日志记录、响应头修改。

2.3 完整执行流程

客户端发起请求 → 进入 Gateway 统一入口 → 路由断言匹配 → 匹配成功进入过滤器链（Pre前置处理） → 负载均衡转发至目标微服务 → 微服务处理完成响应 → 进入后置过滤器（Post收尾处理） → 返回客户端。

三、Spring Cloud Gateway 优缺点详解

3.1 核心优点

• 高性能高并发：基于 WebFlux 响应式非阻塞模型，无线程阻塞，吞吐量远高于 Zuul，适配秒杀、大促高流量场景。

• 原生整合 Spring 生态：无缝对接 Nacos、OpenFeign、Sentinel、Seata，适配全套 Spring Cloud Alibaba 微服务体系。

• 灵活的路由断言机制：支持路径、请求头、参数、IP、时间等多维匹配，满足复杂业务路由场景。

• 丰富的过滤器拓展：内置大量通用过滤器，同时支持自定义全局过滤器，拓展性极强。

• 支持动态路由：可结合 Nacos 配置中心实现路由动态刷新，无需重启网关服务。

• 内置负载均衡：原生整合微服务负载均衡，自动分发请求至多实例服务节点。

• 轻量化低侵入：配置简洁、依赖少、启动快，适配微服务轻量化部署。

3.2 核心缺点

• 学习成本较高：基于响应式编程，区别于传统 Servlet 编程，新手理解门槛高。

• 调试难度大：异步非阻塞链路，请求链路追踪、问题排查比传统 Servlet 复杂。

• 不兼容 Servlet 部分组件：无法使用传统 Servlet Filter、拦截器，必须使用 Gateway 专属过滤器。

• 高可用依赖集群部署：单网关存在单点故障，生产环境必须搭建网关集群。

四、Spring Cloud Gateway 完整实战落地

基于前文 Nacos + OpenFeign 微服务环境，搭建 Gateway 网关服务，实现统一路由转发、过滤器拦截、负载均衡。

4.1 核心依赖引入

新建 gateway 网关服务，引入网关、Nacos 注册中心依赖，无需引入 Web 依赖（WebFlux 已内置）。

<!-- 网关核心依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

<!-- Nacos注册中心 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<!-- 【必须】新一代负载均衡（替代旧Ribbon） -->
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

<!-- 【重点！Gateway4.x想要识别lb:// 必须引入】 -->
<!-- 熔断模块内置 ReactiveLoadBalancerClientFilter，激活lb协议解析 -->
<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-starter-circuitbreaker-reactor-resilience4j</artifactId>
</dependency>

4.2 启动类配置

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

4.3 基础路由配置（YAML方式，生产常用）

实现：访问网关 /api/echo/** 自动转发至 nacos-provider 服务，支持负载均衡。

server:
  port: 8888 # 网关统一端口
spring:
  application:
    name: cloud-gateway
    cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos
    gateway:
      routes:
        # 路由1：转发至服务提供者
        - id: order-route # 路由唯一ID，不可重复
          uri: lb://service-order # lb代表开启负载均衡，指向Nacos服务名,路径不能用_,lb服务器不识别该下划线
          predicates:
            # 路径断言：匹配 /api/echo/任意路径
            - Path=/api/order/**
          filters:
            # 路径截取：去掉第一层前缀 /api
            - StripPrefix=1
            # 添加自定义请求头
            - AddRequestHeader=gateway-source,cloud-gateway
        - id: config-route # 路由唯一ID，不可重复
          uri: lb://nacos-demo # lb代表开启负载均衡，指向Nacos服务名
#          uri: http://127.0.0.1:8084
          predicates:
            # 路径断言：匹配 /api/echo/任意路径
            - Path=/api/config/**
          filters:
            # 路径截取：去掉第一层前缀 /api/config
            - StripPrefix=2
            # 添加自定义请求头
            - AddRequestHeader=gateway-source,cloud-gateway

4.4 动态路由配置（Java代码方式，灵活拓展）

适用于复杂动态路由场景，通过代码构建路由规则，灵活度更高。

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayRouteConfig {

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder){
        return builder.routes()
                // 匹配路径 /api/config/** 转发至nacos-provider
                .route("config-route",r->r.path("/api/config/**")
                        .filters(f->f.stripPrefix(1))
                        .uri("lb://nacos-provider"))
                .build();
    }
}

4.5 自定义全局过滤器（统一拦截实战）

实现网关统一拦截逻辑：请求日志打印、简单鉴权校验，所有路由全局生效。

import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Mono;

@Configuration
public class GlobalAuthFilter {

    @Bean
    public GlobalFilter authFilter(){
        return (exchange, chain) -> {
            // 前置过滤器：打印请求路径
            String path = exchange.getRequest().getPath().value();
            System.out.println("网关拦截请求路径：" + path);

            // 简单鉴权模拟：无token直接拦截
            String token = exchange.getRequest().getHeaders().getFirst("token");
            if(token == null || "".equals(token)){
                // 响应401未授权
                exchange.getResponse().setStatusCode(org.springframework.http.HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            }

            // 后置过滤器：请求结束后执行
            return chain.filter(exchange)
                    .then(Mono.fromRunnable(() -> System.out.println("请求处理完成：" + path)));
        };
    }
}

4.6 统一跨域配置（生产必备）

解决微服务前端跨域问题，网关统一处理，无需每个服务配置跨域。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.reactive.CorsWebFilter;
import org.springframework.web.cors.reactive.UrlBasedCorsConfigurationSource;
import java.util.Collections;

@Configuration
public class CorsConfig {
    @Bean
    public CorsWebFilter corsWebFilter(){
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration corsConfiguration = new CorsConfiguration();
        // 允许跨域请求头、请求方式、携带cookie
        corsConfiguration.setAllowedHeaders(Collections.singletonList("*"));
        corsConfiguration.setAllowedMethods(Collections.singletonList("*"));
        corsConfiguration.setAllowedOriginPatterns(Collections.singletonList("*"));
        corsConfiguration.setAllowCredentials(true);
        source.registerCorsConfiguration("/**",corsConfiguration);
        return new CorsWebFilter(source);
    }
}

4.7 功能验证

启动 Nacos、网关服务、服务提供者，访问地址：http://localhost:8888/api/echo/test，请求经过网关转发，成功调用微服务接口，同时触发全局过滤器日志打印，跨域正常放行。

4.8 高阶实战：Gateway + Nacos 动态路由实时刷新（生产核心能力）

默认情况下，Gateway 静态路由（YAML/代码硬编码）需要重启网关服务才能更新路由规则，无法适配线上动态扩容、服务上下线、灰度路由变更场景。结合 Nacos 配置中心 可实现路由配置热更新、实时刷新、无需重启服务，是生产环境网关必备高阶能力。

4.8.1 动态路由核心原理

Gateway 原生支持配置动态刷新机制，结合 Nacos 配置中心长轮询监听能力，整体流程如下：

1. 网关启动时，从 Nacos 配置中心拉取网关路由配置并加载至本地路由容器；

2. 网关客户端持续长轮询监听 Nacos 配置变更；

3. 运维在 Nacos 控制台修改路由规则、新增/删除路由；

4. Nacos 推送变更事件至网关，网关自动重新加载路由、刷新路由上下文；

5. 全程无需重启网关、无业务中断、实时生效。

4.8.2 引入必备依赖

基于现有网关项目，新增 Nacos 配置中心依赖（动态刷新核心依赖）：

<!-- Nacos配置中心：支撑动态路由刷新 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

4.8.3 网关核心配置改造

新建 bootstrap.yml 优先级配置文件（必须使用bootstrap，保证启动优先加载Nacos配置），配置Nacos地址、命名空间、配置刷新规则：

spring:
  application:
    name: cloud-gateway
  cloud:
    nacos:
      # Nacos配置中心地址
      config:
        server-addr: localhost:8848
        namespace: public
        group: DEFAULT_GROUP
        # 指定网关路由配置的DataID
        data-id: cloud-gateway-route.yml
        file-extension: yml
        # 开启自动刷新（核心配置）
        refresh-enabled: true

SpringBoot3 + Spring Cloud Alibaba 2023.x 已经废弃 bootstrap.yml 默认支持！

Spring Cloud 2022.0.0 (Boot3.0) 开始，官方移除了 bootstrap.yml 自动加载机制，不再默认支持。 以前 Boot2 微服务经典套路：bootstrap.yml 放 Nacos 配置中心地址，现在换方案：spring.config.import，将之前bootstrap.yml的配置写入到application.yml文件，并添加

spring:
  config:
    import: optional:nacos:${spring.application.name}.yaml

4.8.4 Nacos控制台配置动态路由规则

登录 Nacos 控制台 → 配置管理 → 新建配置，参数严格对应上述配置：

• Data ID：cloud-gateway-route.yml

• Group：DEFAULT_GROUP

• 配置格式：YAML

配置内容（动态路由规则，可随时在线修改）：

spring:
  cloud:
    gateway:
      routes:
        - id: dynamic-provider-route
          uri: lb://nacos-provider
          predicates:
            - Path=/dynamic/echo/**
          filters:
            - StripPrefix=1
            - AddRequestHeader=gateway-dynamic, nacos-hot-refresh

4.8.5 开启网关动态刷新注解

在网关启动类添加 @RefreshScope 注解，开启配置动态刷新能力，监听路由配置变更：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.context.config.annotation.RefreshScope;

@SpringBootApplication
@EnableDiscoveryClient
@RefreshScope // 开启配置动态热刷新（核心注解）
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

4.8.6 关闭本地静态路由（可选）

为统一路由管理，建议注释掉项目本地 YAML/代码硬编码的静态路由，所有路由统一托管在 Nacos 控制台，实现集中管控、动态运维。

4.8.7 动态路由刷新测试

1. 重启网关服务，加载 Nacos 远程动态路由；

2. 访问测试地址：http://localhost:8888/dynamic/echo/动态路由测试，请求正常转发生效；

3. 进入 Nacos 控制台，修改路由路径、新增路由、删除路由配置，点击发布；

4. 无需重启网关，立即访问新路由地址，配置实时生效，旧路由自动失效。

4.8.8 动态路由优缺点与生产场景

核心优点：

• 路由配置统一中心化管理，无需修改代码、无需重启服务；

• 支持线上动态扩缩容、路由切换、灰度发布、紧急拦截；

• 支持配置版本回溯，误改路由可一键恢复，降低线上风险。

少量缺点：

• 强依赖Nacos配置中心，Nacos故障会导致路由加载异常；

• 频繁变更路由需做好权限管控，防止误操作引发线上故障。

生产适用场景：电商大促临时路由调整、服务灰度上线、紧急流量拦截、微服务动态扩容、多环境路由快速切换。

4.8.9 生产必备：Nacos 动态路由版本回溯实战

线上频繁修改网关动态路由，极易出现配置改错、路由失效、转发异常等问题，Nacos 原生提供配置版本回溯能力，无需重启网关、无需改代码，一键恢复历史正常路由配置，是线上故障兜底核心方案。

版本回溯核心原理

Nacos 会自动记录每一次配置发布的版本记录、操作人、操作时间、配置差异，形成版本快照。网关动态路由监听配置变更，回溯版本后，Nacos 推送历史配置快照，网关实时加载旧路由规则，实现秒级故障恢复。

版本回溯操作步骤

1. 进入 Nacos 控制台 → 配置管理 → 配置列表，找到网关路由配置 cloud-gateway-route.yml；

2. 点击右侧历史版本，可查看所有发布记录、版本号、修改内容差异；

3. 选择线上稳定、正常的历史版本，点击回滚并确认发布；

4. 网关自动监听配置变更，实时回滚路由规则，无需重启、秒级恢复。

版本回溯生产价值

• 快速修复路由配置错误导致的线上访问异常、接口404、转发错误；

• 无需运维排查代码、无需重启服务，最大限度减少故障时长；

• 可追溯所有路由变更记录，便于故障复盘、责任追溯、版本管控。

4.8.10 高阶实战：Gateway + Nacos 灰度路由（金丝雀发布）

灰度发布（金丝雀发布）是生产迭代核心能力：不全量更新服务，仅让少量用户访问新版本服务，验证无误后再全量上线，规避大面积线上故障。基于 Nacos 动态路由 + Gateway 断言过滤器，可实现精准灰度路由。

灰度路由核心原理

网关作为统一流量入口，通过自定义请求头、用户ID、IP、参数等断言规则区分灰度流量，将指定小流量转发至新版本服务实例，普通流量继续访问旧版本实例，实现流量灰度分流、无损迭代。

实战场景说明

现有服务：nacos-provider（旧版本 V1），新部署灰度服务实例（V2），实现：gray=true携带请求头 的请求走灰度V2服务，其余请求正常走V1旧服务。

Nacos 灰度动态路由配置

修改 cloud-gateway-route.yml，新增灰度路由规则，灰度路由优先级高于普通路由：

spring:
  cloud:
    gateway:
      routes:
        # 灰度路由（高优先级）
        - id: gray-provider-route
          uri: lb://nacos-provider # 同一个服务名，多实例灰度
          predicates:
            - Path=/dynamic/echo/**
            # 灰度核心断言：匹配请求头 gray=true
            - Header=gray,true
          filters:
            - StripPrefix=1
            - AddRequestHeader=env,gray-version

        # 正式普通路由（低优先级）
        - id: dynamic-provider-route
          uri: lb://nacos-provider
          predicates:
            - Path=/dynamic/echo/**
          filters:
            - StripPrefix=1
            - AddRequestHeader=env,official-version

灰度负载均衡适配（核心配置）

在网关 bootstrap.yml 开启 Nacos 权重负载均衡，适配多实例灰度权重分流：

spring:
  cloud:
    loadbalancer:
      nacos:
        enabled: true # 开启Nacos权重负载均衡

自定义灰度规则拓展（按需选用）

除请求头灰度外，生产常用精准灰度规则，可直接替换断言条件：

• IP灰度：- After=2025-01-01T00:00:00+08:00[Asia/Shanghai] 搭配 IP 白名单匹配内网测试IP；

• 用户ID灰度：自定义过滤器拦截指定uid段用户分流至灰度服务；

• 参数灰度：- Query=version,gray 匹配请求参数灰度标识。

灰度功能测试

1. 部署新旧两个版本的 nacos-provider 服务，注册到同一Nacos服务列表；

2. Nacos发布上述灰度路由配置，网关实时热刷新生效；

3. 携带灰度请求头访问：Header: gray=true，请求转发至灰度V2实例；

4. 无请求头正常访问，请求走正式V1实例，灰度分流成功。

灰度路由优缺点与生产场景

优点：

• 流量精准隔离，小范围验证新版本功能，规避全量发布风险；

• 依托动态路由实现，无需重启网关、无需停机更新；

• 规则灵活可配，支持请求头、IP、用户、参数多维灰度。

缺点：

• 多版本服务共存，增加运维复杂度；

• 路由优先级需要严格把控，避免规则覆盖失效。

生产场景：版本迭代上线、电商大促功能更新、接口重构升级、线上功能灰度测试、无损业务迭代。

五、Spring Cloud Gateway 适用场景

结合网关特性与微服务架构，总结精准落地场景：

• 微服务统一入口管控：多服务聚合场景，统一请求入口，隐藏后端服务地址，提升安全性。

• 统一公共能力处理：统一鉴权、统一跨域、统一日志、统一参数校验，剥离业务无关公共逻辑。

• 高并发流量场景：电商秒杀、大促、直播流量等高并发场景，依托非阻塞高性能架构承载海量请求。

• 流量治理场景：接口限流、熔断降级、灰度发布、IP黑名单、请求重写、路由分流。

• 多环境路由隔离：结合 Nacos 实现开发、测试、生产环境路由隔离，动态切换服务版本。

• 前端对接场景：前后端分离项目，前端仅对接网关统一地址，无需维护多服务接口地址。

六、全文总结

1. 网关是微服务架构的流量大门，彻底解决微服务请求散乱、公共逻辑冗余、流量无法管控的核心痛点，是微服务架构的必备组件。

2. Spring Cloud Gateway 替代老旧 Zuul，凭借响应式非阻塞、高并发、高拓展、生态适配强的优势，成为 Spring Cloud Alibaba 体系唯一主流网关。

3. 核心工作模式：断言匹配路由 + 过滤器增强处理 + 负载均衡转发，支持 YAML 配置与代码动态配置双模式，适配简单与复杂业务场景。

4. 生产落地核心：统一入口、统一鉴权、统一跨域、流量限流、动态路由、集群高可用，全方位实现微服务流量标准化治理。