4. Spring Cloud Gateway 入门：核心概念与项目搭建

Spring Cloud Gateway 是 Spring 官方基于 Spring WebFlux 构建的 API 网关，旨在为微服务架构提供一种简单、有效且统一的 API 路由管理方式。本章将深入剖析其三大核心概念：Route（路由）、Predicate（断言）、Filter（过滤器），并通过一个完整的 Hello World 项目演示从零搭建到成功路由的全过程。

4.1 三大核心概念

Spring Cloud Gateway 的处理流程可以概括为：客户端请求进入网关，由 Predicate 匹配规则决定是否由某个 Route 处理，在请求前后经过一系列 Filter 进行增强或拦截，最终转发到目标微服务。

4.2 路由处理流程（SVG 图）

下图展示了 Spring Cloud Gateway 内部对一个 HTTP 请求的完整处理链路：

4.3 项目搭建与 Hello World

下面通过一个完整的 Spring Boot 项目演示 Spring Cloud Gateway 的搭建与基本路由配置。项目使用 Maven 构建，JDK 17+。

4.3.1 创建 Maven 项目并引入依赖

在 pom.xml 中添加以下核心依赖：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
    <relativePath/>
</parent>

<dependencies>
    <!-- Spring Cloud Gateway 核心依赖 -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

4.3.2 编写启动类

创建一个标准的 Spring Boot 启动类：

package com.example.gateway;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

4.3.3 配置路由（YAML 方式）

在 application.yml 中配置一个简单的路由，将 /hello/** 的请求转发到 http://httpbin.org：

server:
  port: 8080

spring:
  cloud:
    gateway:
      routes:
        - id: hello_route
          uri: http://httpbin.org
          predicates:
            - Path=/hello/**
          filters:
            - StripPrefix=1

4.3.4 验证 Hello World

启动项目后，使用 curl 或浏览器访问：

# 请求网关
curl http://localhost:8080/hello/get

# 实际转发到 http://httpbin.org/get
# 返回 httpbin.org 的标准 JSON 响应

如果看到 httpbin.org 返回的 JSON 数据，说明路由配置成功。网关将 /hello/get 的 /hello 前缀剥离后，转发到 http://httpbin.org/get。

4.4 核心概念关系图（SVG 图）

下图展示了 Route、Predicate、Filter 三者之间的组合关系：

4.5 常见问题与避坑指南

• 依赖冲突： 不要同时引入 spring-boot-starter-web 和 spring-boot-starter-gateway，否则启动报错。
• 路径匹配优先级： 多个路由的 Predicate 匹配时，按配置顺序生效。精确路径应放在通配路径之前。
• Filter 顺序： 同一个路由中多个 Filter 按配置顺序执行。Pre Filter 顺序影响请求处理，Post Filter 顺序影响响应处理。
• 调试技巧： 开启 Gateway 的日志级别可查看路由匹配详情：logging.level.org.springframework.cloud.gateway=DEBUG