1. 概述

Spring Cloud Gateway 是 Spring Cloud 生态下的一个 API 网关，它的核心作用是在微服务架构中，作为所有外部请求的统一入口，负责路由、过滤、鉴权、限流、日志等工作。

本文将带你从零开始，用 Spring Cloud Gateway 搭建一个可直接运行的 API 网关服务。

2. 基础实战：路由转发示例

2.1. 项目初始化

通过Spring Initializr创建标准Spring Boot项目：

  • 核心依赖：Reactive Gateway（对应spring-cloud-starter-gateway-server-webflux）

2.2. 核心配置

2.2.1. 依赖管理（pom.xml）

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
        </dependency>

    <properties>
        <spring-cloud.version>2025.1.1</spring-cloud.version>
    </properties>

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

2.2.2. 路由配置（application.yml）

采用Spring Cloud Gateway 5.x全新配置命名空间spring.cloud.gateway.server.webflux，配置一个基础的路径路由规则：

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: user-route  # 路由唯一标识
              uri: http://localhost:8080  # 目标服务地址
              predicates:
                - Path=/users  # 断言：精确匹配 /users 路径的请求

2.3. 启动网关服务

运行 HelloGatewayWebfluxApplication，控制台输出以下关键日志表示启动成功：

Netty started on port ....(http)
Started HelloGatewayWebfluxApplication in X seconds

在这里插入图片描述

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.0.6)

2026-05-09T21:38:50.752+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] c.e.h.HelloGatewayWebfluxApplication     : Starting HelloGatewayWebfluxApplication using Java 21.0.1 with PID 2872 (E:\hello-world\hello-gateway-webflux\target\classes started by SongGuanxun in E:\hello-world\hello-gateway-webflux)
2026-05-09T21:38:50.768+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] c.e.h.HelloGatewayWebfluxApplication     : No active profile set, falling back to 1 default profile: "default"
2026-05-09T21:38:55.415+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.cloud.context.scope.GenericScope     : BeanFactory id=0b86235a-066e-3b9d-bdb7-ec0e58450ea4
2026-05-09T21:38:59.214+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [After]
2026-05-09T21:38:59.215+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Before]
2026-05-09T21:38:59.215+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Between]
2026-05-09T21:38:59.216+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Cookie]
2026-05-09T21:38:59.216+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Header]
2026-05-09T21:38:59.216+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Host]
2026-05-09T21:38:59.216+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Method]
2026-05-09T21:38:59.217+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Path]
2026-05-09T21:38:59.217+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Query]
2026-05-09T21:38:59.217+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [ReadBody]
2026-05-09T21:38:59.217+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [RemoteAddr]
2026-05-09T21:38:59.218+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Version]
2026-05-09T21:38:59.218+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [XForwardedRemoteAddr]
2026-05-09T21:38:59.218+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [Weight]
2026-05-09T21:38:59.218+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.c.g.r.RouteDefinitionRouteLocator    : Loaded RoutePredicateFactory [CloudFoundryRouteService]
2026-05-09T21:39:00.953+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] o.s.boot.reactor.netty.NettyWebServer    : Netty started on port 9090 (http)
2026-05-09T21:39:01.143+08:00  INFO 2872 --- [hello-gateway-webflux] [           main] c.e.h.HelloGatewayWebfluxApplication     : Started HelloGatewayWebfluxApplication in 13.356 seconds (process running for 16.914)

2.4. 功能验证：测试路由转发效果

2.4.1. 启动后端服务

为验证路由功能，启动一个运行在8080端口的后端服务，并提供 /users 接口。

2.4.2. 直接访问后端服务

2.4.3. 通过网关访问后端服务

2.4.4. 结果对比与分析

  • 直接访问后端服务：http://localhost:8080/users
  • 通过网关访问后端服务：http://localhost:9090/users

两者返回结果一致，说明路由配置生效，网关能够将 /users 接口请求正确路由到后端服务。

3. 完整项目源码

3.1. pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

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

    <groupId>com.example</groupId>
    <artifactId>hello-gateway-webflux</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>21</java.version>
        <spring-cloud.version>2025.1.1</spring-cloud.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.projectreactor</groupId>
            <artifactId>reactor-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

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

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

3.2. application.yml

spring:
  application:
    name: hello-gateway-webflux
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: user-route  # 路由唯一标识
              uri: http://localhost:8080  # 目标服务地址
              predicates:
                - Path=/users  # 断言：精确匹配 /users 路径的请求

server:
  port: 9090

3.3. HelloGatewayWebfluxApplication

package com.example.hello_gateway_webflux;

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

@SpringBootApplication
public class HelloGatewayWebfluxApplication {

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

}

4. 官方参考资源

4.1. Spring Cloud Gateway 项目主页

https://spring.io/projects/spring-cloud-gateway

4.2. Spring Cloud Gateway 官方文档

https://docs.spring.io/spring-cloud-gateway/reference/

# gateway
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区