第43篇：微服务网关：Spring Cloud Gateway，统一接口入口

专栏：Spring Cloud 微服务实战全套教程

在微服务架构中，我们会将单体应用拆分为用户服务、订单服务、商品服务、支付服务等多个独立微服务。服务数量增多后，会出现诸多问题：客户端需要维护多个服务接口地址、接口权限重复校验、无法统一限流管控、请求链路杂乱难以运维。

为解决以上痛点，API网关 成为微服务架构的核心门面组件，而 Spring Cloud Gateway 是Spring Cloud官方推出的新一代网关框架，替代了老旧的Zuul网关，具备高性能、异步非阻塞、功能丰富、适配微服务生态等优势。

本文将从零讲解Spring Cloud Gateway核心原理、核心组件、配置方式，结合过滤器、Sentinel限流熔断，完成一套可落地的微服务网关实战方案。

一、微服务网关核心作用

网关是所有微服务的统一入口、流量大门，所有客户端请求（前端、第三方接口）必须先经过网关，再由网关转发至对应微服务，核心能力分为四大类：

1.1 统一入口，收口流量

屏蔽后端微服务的真实地址与部署结构，客户端仅需对接网关一个地址，无需维护多个服务接口，简化客户端调用逻辑，同时隐藏后端服务细节，提升架构安全性。

1.2 路由转发，负载均衡

根据请求路径、请求方式、请求参数等规则，精准将请求转发到对应的微服务实例，同时整合Spring Cloud负载均衡机制，实现多实例流量分发，提升服务可用性。

1.3 统一权限控制

在网关层统一完成Token校验、权限拦截、身份认证，无需在每个微服务重复开发鉴权逻辑，实现权限逻辑统一维护、统一升级。

1.4 限流熔断、流量防护

整合Sentinel、Resilience4j等组件，在网关层实现全局限流、接口限流、熔断降级、流量整形，避免流量洪击、服务雪崩，保护后端微服务集群稳定运行。

额外拓展能力

日志统一打印、请求响应加密解密、跨域统一处理、接口监控统计、灰度发布等，所有通用流量处理逻辑均可下沉到网关层实现。

二、Spring Cloud Gateway 核心概念

Spring Cloud Gateway 的核心架构由 Route（路由）、Predicate（断言）、Filter（过滤器） 三大核心组件组成，所有网关功能均基于这三者实现。

2.1 Route 路由（核心单元）

路由是网关最基础的转发单元，是一套完整的请求转发规则。每一个路由包含4个核心属性：

• id：路由唯一标识，自定义命名，保证全局唯一

• uri：请求转发的目标地址，支持静态地址和服务注册中心地址（lb://服务名）

• predicates：断言规则，请求匹配所有断言后才会触发该路由

• filters：过滤器集合，对匹配的请求/响应进行预处理、后处理

2.2 Predicate 断言（匹配规则）

断言是请求匹配条件，Spring Cloud Gateway内置十余种断言工厂，用于匹配HTTP请求的各类属性，只有请求满足所有断言条件，才会命中当前路由。常用内置断言如下：

断言类型	匹配规则	配置示例
Path	匹配请求路径	- Path=/order/**
Method	匹配请求方式	- Method=GET,POST
Header	匹配请求头参数	- Header=token,.*
Query	匹配请求参数	- Query=userId
After	匹配请求时间	- After=2025-01-01T00:00:00+08:00Asia/Shanghai

2.3 Filter 过滤器（逻辑处理）

过滤器用于对命中路由的请求、响应进行加工处理，分为前置过滤器（请求转发前执行）和后置过滤器（请求响应后执行），是网关实现鉴权、限流、日志、参数修改的核心。

过滤器整体分为两大类：局部过滤器 （仅对当前路由生效）、全局过滤器（对所有路由生效）。

三、网关路由配置实战（静态+动态路由）

接下来通过实战演示两种主流路由配置方式：静态路由（配置文件硬编码）、动态路由（基于Nacos配置中心热更新）。

3.1 环境依赖准备

网关项目核心依赖（Spring Boot 2.7.x + Spring Cloud Alibaba 2021），重点注意：网关项目不能引入web依赖，否则会冲突。

<!-- 网关核心依赖 -->
<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>
<!-- 负载均衡依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

3.2 静态路由配置（yml文件）

静态路由直接在application.yml中配置，适合固定不变的路由规则，支持负载均衡转发到注册中心服务。

spring:
  cloud:
    gateway:
      # 开启网关
      enabled: true
      # 路由配置
      routes:
        # 订单服务路由
        - id: order-service-route
          # lb代表负载均衡，转发到nacos中的order-service服务
          uri: lb://order-service
          predicates:
            # 匹配所有/order开头的请求
            - Path=/order/**
            # 仅允许GET、POST请求
            - Method=GET,POST
        # 用户服务路由
        - id: user-service-route
          uri: lb://user-service
          predicates:
            - Path=/user/**

配置说明：客户端请求 http://网关IP/order/list 会自动转发到 nacos 中的 order-service 服务，实现接口统一转发。

3.3 动态路由配置（Nacos热更新）

静态路由需重启服务生效，生产环境推荐动态路由，基于Nacos配置中心实现路由规则热更新，无需重启网关服务。

核心原理：监听Nacos配置变更，实时刷新网关路由表。实现步骤如下：

1. 引入Nacos配置中心依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

2. 编写动态路由配置类

@Configuration
@RefreshScope
public class GatewayDynamicRouteConfig {

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
                // 商品服务动态路由
                .route("goods-service-route", r -> r.path("/goods/**")
                        .uri("lb://goods-service"))
                .build();
    }
}

3. Nacos配置中心新增网关路由配置，修改配置后网关实时生效，无需重启服务。

四、全局过滤器与局部过滤器实战

过滤器是网关实现通用业务逻辑的核心，下面分别演示局部过滤器、全局过滤器的开发与使用，以常用的Token鉴权为例。

4.1 局部过滤器（单路由生效）

局部过滤器仅对当前配置的路由生效，适合单个服务的特殊拦截规则。这里使用内置过滤器实现请求头参数过滤。

spring:
  cloud:
    gateway:
      routes:
        - id: order-service-route
          uri: lb://order-service
          predicates:
            - Path=/order/**
          filters:
            # 局部过滤器：去除请求路径前缀
            - StripPrefix=1
            # 局部过滤器：添加请求头
            - AddRequestHeader=source,gateway

4.2 全局过滤器（全路由生效）

全局过滤器对网关所有路由生效，适合全局通用逻辑：Token鉴权、跨域处理、日志打印、请求拦截等。

自定义全局Token鉴权过滤器实战：

@Component
@Order(-100) // 优先级最高，最先执行
public class AuthGlobalFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        // 1. 获取请求token
        String token = request.getHeaders().getFirst("token");
        // 2. 简单校验token（生产环境需完善JWT校验）
        if (StringUtils.isEmpty(token)) {
            ServerHttpResponse response = exchange.getResponse();
            response.setStatusCode(HttpStatus.UNAUTHORIZED);
            return response.setComplete();
        }
        // 3. 校验通过，放行请求
        return chain.filter(exchange);
    }
}

代码说明：通过@Order设置过滤器执行优先级，数值越小优先级越高，保证鉴权逻辑优先执行；无Token的请求直接拦截，返回401未授权。

五、网关限流熔断（Sentinel集成实战）

流量防护是网关核心能力，生产环境必须配置限流熔断。本文采用Sentinel + Gateway实现网关层全局限流、接口限流、熔断降级。

5.1 引入Sentinel网关依赖

<!-- Sentinel网关限流依赖 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>sentinel-spring-cloud-gateway-adapter</artifactId>
</dependency>

5.2 网关限流规则配置

基于Sentinel实现路由维度限流，对订单服务接口设置每秒最大请求数，超出流量直接限流。

@Configuration
public class SentinelGatewayConfig {

    @Bean
    public GatewayRuleManager gatewayRuleManager() {
        // 初始化网关限流规则
        List<GatewayFlowRule> rules = new ArrayList<>();
        // 针对order-service-route路由限流
        GatewayFlowRule rule = new GatewayFlowRule("order-service-route")
                .setCount(10) // 每秒最大请求数10
                .setIntervalSec(1); // 统计时间窗口1秒
        rules.add(rule);
        GatewayRuleManager.loadRules(rules);
        return new GatewayRuleManager();
    }
}

5.3 自定义限流降级返回结果

默认限流返回英文提示，自定义友好降级响应：

@Component
public class GatewayBlockHandler implements BlockRequestHandler {
    @Override
    public Mono<ServerHttpResponse> handleRequest(ServerWebExchange exchange, Throwable t) {
        // 构建统一限流返回结果
        Map<String,Object> result = new HashMap<>();
        result.put("code",500);
        result.put("msg","请求过于频繁，请稍后再试！");
        result.put("data",null);

        ServerHttpResponse response = exchange.getResponse();
        response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
        DataBuffer buffer = response.bufferFactory().wrap(JSON.toJSONString(result).getBytes(StandardCharsets.UTF_8));
        return response.writeWith(Mono.just(buffer));
    }
}

六、完整网关实战总结与项目架构

6.1 整体架构流程

客户端请求 → Spring Cloud Gateway网关 → 全局过滤器鉴权 → 断言匹配路由 → Sentinel限流校验 → 局部过滤器处理 → 负载均衡转发至后端微服务 → 响应返回

6.2 核心功能落地清单

• ✅ 统一流量入口，隐藏后端服务地址

• ✅ 静态+动态双模式路由配置，支持热更新

• ✅ 全局+局部过滤器，实现统一鉴权、参数处理

• ✅ Sentinel网关限流熔断，实现流量防护

• ✅ 整合Nacos服务发现、负载均衡

七、常见踩坑总结

1. 依赖冲突：网关项目禁止引入spring-boot-starter-web依赖，会导致网关启动失败

2. 路由优先级：精准路由优先级高于模糊路由，配置时避免路径匹配冲突

3. 过滤器顺序：通过@Order注解调整执行优先级，鉴权过滤器需优先执行

4. 限流不生效：必须引入sentinel网关适配依赖，且路由ID需与限流规则ID一致

八、文末总结

Spring Cloud Gateway 作为微服务的流量守门人，是微服务架构中不可或缺的核心组件。本文完整讲解了网关的核心价值、三大核心组件、路由配置、过滤器开发、Sentinel限流熔断，并提供了可直接落地的实战代码。

相比于Zuul，Gateway基于Netty实现异步非阻塞，吞吐量更高、性能更强，完全适配高并发微服务场景。后续文章会继续讲解网关灰度发布、日志链路追踪、自定义断言、网关集群部署等高级特性。