当前位置： 首页 > news >正文

API Gateway ：API网关组件

news 2025/9/20 6:25:00

目录

一、概念

1.1 概念

1.2 核心价值

1.3 能力边界

1.4 应用场景

1.5 主流 Gateway 技术

二、Spring Cloud Gateway(SCG) 介绍

2.1 核心架构概念

2.2 核心工作原理与流程

2.3 核心价值

2.4 应用场景

2.5 与Nginx对比

三、Spring Cloud Gateway使用

3.1 依赖与基础配置

3.2 两种配置方式

3.3 自定义过滤器

3.4 关键特性与高级功能

3.5 主要配置项及示例

一、概念

1.1 概念

API 网关的定义：
API 网关是一个反向代理和统一入口点，它位于客户端（如Web浏览器、移动应用）与内部一系列微服务之间。所有外部客户端的请求首先会到达网关，由网关进行路由、聚合、协议转换等一系列处理后再转发到相应的后端服务，并将结果返回给客户端。

1.2 核心价值

引入 API 网关的核心价值在于它解决了微服务架构下客户端直接访问服务所带来的诸多痛点，实现了关注点分离。

  • 简化客户端（解耦客户端与后端）

    • 痛点：在微服务架构中，后端服务被拆分为数十甚至上百个细粒度的服务。客户端（如手机App）需要知道每个服务的地址、端口和API细节，这导致客户端代码异常复杂且与后端紧密耦合。

    • 网关价值：网关为客户端提供了一个统一的入口（通常是一个域名）。客户端只需与网关交互，完全不需要感知后端有多少个服务、它们在哪里。当后端服务发生变化（如拆分、合并）时，只需修改网关路由配置，客户端无需任何改动。

  • 聚合与裁剪接口（BFF - Backend For Frontend）

    • 痛点：一个手机页面可能需要显示用户信息、订单列表、消息通知等，这需要调用3-4个不同的微服务。由客户端串行调用这些接口会导致延迟高、性能差。

    • 网关价值：网关可以聚合多个下游服务的调用，将一个页面所需的所有数据打包成一个响应返回给客户端，大大减少了网络往返次数。更进一步，它可以为特定客户端（如Web、iOS、Android）定制接口（BFF模式），返回最适合该客户端的数据结构，避免传输冗余数据。

  • 集中式横切关注点（Cross-Cutting Concerns）

    • 这是网关最重要的价值之一。将各个微服务都需要但又不是核心业务逻辑的功能抽离到网关统一处理。

    • 身份认证与授权：在网关层统一校验Token、API密钥，避免每个微服务都重复实现一套安全逻辑。

    • 流量控制与熔断：限制每个客户端的请求速率，防止恶意攻击或某客户端拖垮整个系统；当下游服务不可用时，快速失败并返回降级响应，避免雪崩效应。

    • 监控与日志：在网关集中收集所有请求和响应的指标（如QPS、延迟、错误率），为系统监控和分析提供统一的数据源。

    • 负载均衡：将请求均匀地分发到同一个服务的多个实例上。

    • SSL终止：在网关处完成HTTPS的解密，减轻后端服务的计算压力。

  • 增强安全性

    • 网关隐藏了内部微服务的拓扑结构和细节（如端口、版本），对外只暴露一个端点，减少了攻击面。

    • 可以集中实施WAF（Web应用防火墙）功能，如防SQL注入、防爬虫等。

1.3 能力边界

  • 不是业务逻辑的承载者

    • 边界：网关的核心职责是请求路由和通用功能处理。绝不能将复杂的业务逻辑写入网关。业务逻辑必须始终放在下游的微服务中。

    • 误区：例如，“创建订单”的业务校验和持久化操作应该在“订单服务”中完成，网关只负责将 POST /orders 请求路由过去。

  • 可能成为性能瓶颈与单点故障

    • 边界：所有流量都经过网关，如果设计不当，网关很容易成为系统的瓶颈。

    • 解决方案：需要通过水平扩展（部署多个网关实例）并结合负载均衡器来避免单点故障和提升处理能力。

  • 可能增加延迟

    • 边界：网关作为额外的一跳（Hop），必然会引入少量的网络延迟。虽然通过聚合请求可以减少客户端的总延迟，但单个请求的延迟确实增加了。

    • 解决方案：网关的性能至关重要，应选择高性能的技术栈（如Nginx, Envoy, 基于Netty的Spring Cloud Gateway），并将网关部署在物理上离后端服务尽可能近的地方。

  • 可能造成配置复杂化

    • 边界：网关的路由规则、策略配置可能会变得非常复杂，难以管理。

    • 解决方案：需要配套完善的配置管理系统和清晰的流程，甚至采用 GitOps 理念，用代码来管理网关配置。

1.4 应用场景

  • 微服务架构

    • 这是最经典的应用场景。作为所有微服务的统一入口，处理路由、安全、监控等横切关注点。

  • 前后端分离与BFF模式

    • 为不同的客户端（如小程序、Web管理后台、合作伙伴API）提供量身定制的API接口，聚合数据，避免客户端直接调用多个内部服务。

  • 第三方开放平台（API Economy）

    • 企业将自身能力以API的形式开放给第三方开发者。网关负责API生命周期管理（发布、版本控制、下线）、计量计费（统计API调用次数）、开发者门户接入和速率限制。

  • 混合云与多云部署

    • 网关可以作为流量管理器，将请求路由到不同云环境（如AWS、Azure、私有云）中的服务，实现灵活的部署和迁移策略。

  • 遗留系统现代化改造

    • 在改造单体应用时，可以先将网关架在单体应用前面，将新的微服务逐步从单体中剥离出来。网关负责将特定请求路由到新服务，其余请求仍转发给单体应用，实现平滑迁移。

  • 边缘计算（Edge Computing）

    • 在IoT场景中，网关可以部署在靠近设备的地点，负责协议转换（如MQTT转HTTP）、数据过滤和缓存，减少传输到云端的数据量。

1.5 主流 Gateway 技术

特性维度Spring Cloud GatewayZuul 1.xZuul 2.x备注
核心模型异步非阻塞 (WebFlux + Reactor)同步阻塞 (Servlet)异步非阻塞 (Netty)SCG 和 Zuul2 更适合高并发、长连接场景。
性能非常高，与 Zuul1 相比有 ~1.6倍 的性能提升低，每个请求占用一个线程高，与 SCG 互有胜负，基准测试结果接近性能是 SCG 和 Zuul2 的最大优势。
编程模型函数式、声明式 (Java DSL)过滤器 (Filter)过滤器 (Filter)SCG 的 DSL 配置路由非常灵活和强大。
集成度与 Spring 生态完美集成与 Spring Cloud Netflix 集成与 Spring Cloud Netflix 集成，但官方支持减弱SCG 是 Spring Cloud 官方亲生儿子，未来主流。
维护状态活跃 (Spring 官方持续维护和更新)停止维护 (已进入 Attic 模式)有限维护 (Netflix 内部优先，社区缓慢)Zuul 1/2 已不再是 Spring Cloud 的推荐选项。
功能特性路由、断言、过滤器、熔断、限流、重试等路由、过滤器路由、过滤器SCG 内置了更多实用功能，开箱即用性更好。
配置方式代码 DSL、YAML 配置文件配置文件、注解配置文件、GroovySCG 支持 YAML 和代码两种方式，非常灵活。
学习曲线中等（需了解 Reactor 响应式编程）低（传统 Servlet 模型）中高（需了解异步和非阻塞概念）对于传统 Spring MVC 开发者，SCG 需要新的知识。

其他选择：

  • Kong：基于OpenResty（Nginx + Lua），性能极高，通过插件扩展。

  • APISIX：Apache顶级项目，基于Nginx和etcd，动态路由和插件热加载能力非常强。

  • ShenYu：国产Apache顶级项目，功能全面，支持多种协议代理。

技术选型：

  • 技术栈是Spring Cloud -> 首选Spring Cloud Gateway。

  • 追求极致性能、高可用，且有运维能力 -> 考虑Kong/APISIX。

虽然 SCG 在 JVM 网关中性能出众，但与基于 C/Nginx 的网关（如 Kong, APISIX）或 C++ 的 Envoy 相比，在极限性能（如每秒请求数 RPS）和资源消耗（内存占用）上仍有差距。对于绝大多数Java应用场景，SCG 的性能是过剩的，但对于追求极致性能的边缘计算场景，可能需要考虑其他方案。

二、Spring Cloud Gateway(SCG) 介绍

2.1 核心架构概念

Spring Cloud Gateway 是一个基于 Spring 5、Project Reactor 和 Spring Boot 2 构建的 API 网关。它旨在为微服务架构提供一个简单、有效且统一的入口点，用于路由到后端服务、执行横切关注点（如安全、监控、限流）等。

其核心设计理念是构建一个非阻塞式、异步高性能的网关，能够轻松处理高并发请求，并与整个 Spring Cloud 生态系统（如服务发现、熔断器）无缝集成。

Spring Cloud Gateway 的核心逻辑可以概括为 路由转发 + 断言判断 + 执行过滤器链。其三大核心概念构成了处理所有请求的基础：

  • 路由 (Route)：网关的基本构建模块。一个请求如果匹配了该路由的所有断言，就会被该路由处理。一个路由定义了一条完整的转发规则，包含：

    • ID：路由的唯一标识。

    • 目标 URI：请求最终被转发的地址，可以是具体地址或服务名（通过 lb:// 前缀开启负载均衡）。

    • 断言 (Predicate) 集合：用于判断请求是否匹配当前路由的条件。

    • 过滤器 (Filter) 集合：处理请求和响应的逻辑单元，可以在路由前后修改它们。

  • 断言 (Predicate)：基于 Java 8 的 java.util.function.Predicate 接口。开发人员可以匹配 HTTP 请求中的任何内容（如请求路径、方法、头、参数、Cookie、主机名、时间等）。只有所有断言都返回 true，请求才会匹配该路由。

    • 示例：Path=/api/users/**, Method=GET, Header=X-Request-Id, \d+

  • 过滤器 (Filter)：借鉴了 Servlet 编程模型中的过滤器概念。可以在请求被路由之前（pre） 或之后（post） 修改请求和响应。过滤器的作用范围是特定的路由。过滤器分为两种：

    • GatewayFilter：局部过滤器，仅作用于单个或一组路由。

    • GlobalFilter：全局过滤器，作用于所有路由。通过实现 Ordered 接口或使用 @Order 注解来控制执行顺序。

    • 示例：AddRequestHeader=X-Request-red, blue（在转发前添加请求头）， StripPrefix=2（在转发前剥离路径前缀）。

2.2 核心工作原理与流程

工作流程：

  1. 客户端向 SCG 发起请求。

  2. SCG 将请求交给 Gateway Handler Mapping 处理。

  3. Handler Mapping 根据请求信息寻找匹配的路由（即找到所有断言都为 true 的路由）。

  4. 请求被发送到 Gateway Web Handler 执行此路由上指定的 过滤器链（Filter Chain）。

  5. 过滤器链中 pre 类型的过滤器被执行，可能修改请求。

  6. 请求被代理（路由）到真正的后端服务。

  7. 后端服务返回响应后，过滤器链中 post 类型的过滤器被执行，可能修改响应。

  8. 最终响应返回给客户端。

2.3 核心价值

  • 卓越的性能与低资源消耗

    • 基于 Netty 和 Reactor 的响应式（Reactive）编程模型，使其能够以非阻塞的方式处理请求。这意味着它可以用少量而固定的线程处理大量并发连接，非常适合处理长连接（如 WebSocket）、流媒体和高并发场景，避免了传统同步阻塞网关（如 Zuul 1.x）的线程池耗尽问题。

  • 与 Spring 生态的完美无缝集成

    • 服务发现：开箱即用支持与 Eureka, Nacos, Consul 等注册中心集成，可以轻松地通过服务名（而不是硬编码的 IP:Port）进行路由。lb://user-service

    • 熔断与限流：通过集成 Spring Cloud CircuitBreaker (支持 Resilience4j 和 Sentinel)，可以轻松为路由配置熔断降级策略。同时，集成 Redis 可以实现基于令牌桶算法的分布式限流。

    • 安全性：与 Spring Security 和 OAuth2 深度集成，可以轻松实现身份认证和授权。

    • 监控：天生支持 Micrometer，可以轻松将指标导出到 Prometheus, Grafana 等监控系统。

  • 强大而灵活的路由与过滤器机制

    • 通过 Java DSL 或 YAML 配置路由，方式非常直观和灵活。

    • 提供了大量开箱即用的断言和过滤器工厂（如 Path, Header, RewritePath, RateLimiter 等）。

    • 支持自定义全局过滤器和路由器过滤器，扩展性极强，可以实现任何需要的业务逻辑。

  • 开发者友好

    • 对于已经熟悉 Spring 体系的开发者来说，学习成本相对较低。其配置风格、编程模式与 Spring Boot 应用保持一致。

2.4 应用场景

  • 微服务架构的统一入口 (The Single Entry Point)

    • 这是最经典的场景。所有外部请求（来自Web、移动端、第三方API）首先到达 SCG，由它负责将请求路由到内部相应的微服务（如用户服务、订单服务、商品服务）。

  • 认证与授权 (Authentication & Authorization)

    • 在网关层统一进行 JWT 令牌校验、API 密钥认证，避免每个微服务重复实现安全逻辑。非法请求在进入系统内部之前就被拦截。

  • 请求限流与熔断 (Rate Limiting & Circuit Breaking)

    • 对特定 API 或用户进行限流，防止系统被突发流量或恶意请求打垮。当某个下游服务响应缓慢或不可用时，网关可以快速失败（熔断），并返回降级响应（如默认值），避免雪崩效应。

  • 跨域处理 (CORS)

    • 在网关层统一配置和管理跨域策略，下游服务无需再关心 CORS 问题。

  • 请求/响应转换 (Request/Response Transformation)

    • API 聚合：将多个下游服务的调用结果聚合成一个响应，减少客户端请求次数（BFF 模式）。

    • 协议转换：如支持 WebSocket 到 HTTP 的代理。

    • 数据裁剪：为不同的客户端（如移动端和Web端）返回不同数据结构的响应。

    • 路径重写：例如，将外部暴露的简洁路径 /users 重写为内部服务的具体路径 /api/v1/user-service/users。

  • 日志与监控 (Logging & Monitoring)

    • 作为所有流量的必经之地，是收集访问日志、监控指标（QPS、延迟、错误率）的绝佳位置。

2.5 与Nginx对比

Nginx 和 Spring Cloud Gateway (SCG) 扮演的是不同角色，解决的是不同层面的问题。它们不是替代关系，而是互补关系。

  • Nginx 像是公司的前台和保安总管：他负责所有进入大楼的人流（流量）。他知道该把快递员引到货梯（静态资源），把访客引到前台登记（负载均衡到网关），并且检查每个人的基础通行证（SSL终止、基础限流）。

  • Spring Cloud Gateway 像是公司内部各个部门的接待员：他负责已经进入部门的内部事务。他需要根据访客的工牌和权限（JWT令牌）决定能否进入某个项目室（微服务），记录下这次访问的详细日志（审计），或者把几个简单的请求合并成一个复杂的报告返回（聚合）。

特性NginxSpring Cloud Gateway解释
定位流量网关 (全局层面)业务网关 (微服务层面)Nginx 处理所有进入数据中心的流量；SCG 处理进入微服务集群的业务流量。
性能极高。基于C语言，纯异步IO，资源消耗低，擅长处理海量并发连接。高。基于Java和Netty（异步IO），但受限于JVM，性能绝对值低于Nginx。Nginx 更适合作为第一道屏障，处理最粗暴的流量压力。
功能焦点通用网络服务：静态资源服务、SSL终止、TCP/UDP负载均衡、反向代理、基础限流、高并发。业务集成：动态路由、服务发现（集成Eureka/Nacos）、断路器（集成Resilience4j）、权限校验（JWT）、限流熔断、日志审计、请求改写、灰度发布。SCG 的功能与微服务治理生态深度集成，可以用Java代码灵活定制业务逻辑。
配置方式静态文件 (nginx.conf)。重载配置需要重启或发送信号。动态性弱。动态配置。配置可来自配置文件、数据库、配置中心（如Nacos）。动态性强，可不停机更新路由规则。在微服务频繁发布、扩缩容的场景下，SCG 能自动从注册中心发现新服务实例，而Nginx需要手动改配置或配合Consul等工具实现动态。
生态集成主要通过模块（如Lua脚本）扩展，但复杂度较高。与Spring Cloud生态无缝集成。天生兼容Eureka, Nacos, Sentinel, Sleuth等组件。如果你整个技术栈是Spring Cloud，使用SCG可以获得“开箱即用”的协同体验。

引入 Spring Cloud Gateway 的核心原因：需要一个能和微服务治理体系（如服务发现、熔断、链路追踪）深度集成、并能通过编程方式灵活实现业务逻辑（如鉴权、灰度）的组件。这是Nginx不擅长的地方。

Spring Cloud Gateway 不能完全代替 Nginx的原因：

  • 性能与资源消耗：

    • Nginx 作为C语言编写的软件，在处理静态内容、SSL加密解密、以及作为反向代理处理大量并发连接时，其性能和资源效率（CPU/内存）远高于基于JVM的 SCG。

    • 将 SCG 直接暴露在公网，意味着所有流量（包括恶意攻击、CC攻击）都要先经过JVM，这会让你的网关层更容易成为性能瓶颈且成本更高。让更高效的Nginx扛住第一波流量，是更经济、更安全的选择。

  • 功能的侧重点不同：

    • 静态资源服务：Nginx 是提供静态文件（如图片、HTML、JS、CSS）的王者，效率极高。让SCG去处理静态资源是对其资源的浪费。

    • SSL终止：在大流量场景下，使用Nginx来卸载SSL加解密压力是标准的做法，因为它比在JVM中做这件事效率高得多。

    • TCP/UDP四层代理：Nginx 可以轻松代理MySQL、Redis、DNS等基于TCP或UDP的协议。SCG 目前主要专注于HTTP/HTTPS七层协议。

    • 极端稳定性：Nginx 以其极致的稳定性著称，很少崩溃。而JVM应用可能需要应对GC暂停等问题。

  • 架构职责分离与安全性：

    • 南北流量 vs 东西流量：Nginx 通常位于架构最边缘，处理南北流量（从外部客户端到数据中心的流量）。SCG 则部署在内部，处理东西流量（在微服务集群内部，但介于客户请求和具体服务之间）。

    • 安全边界：Nginx 可以作为第一道安全防线，配置基础的IP黑名单、频率限制等。将SCG隐藏在Nginx之后，相当于多了一层保护，减少了其直接暴露的风险。

典型的混合架构：在实际生产环境中，最常见的正是这种“Nginx + Spring Cloud Gateway”的混合架构，充分发挥各自所长：

流程说明：

  1. 用户访问 https://your-domain.com，请求首先到达 Nginx。

  2. Nginx 完成SSL解密，如果是请求静态文件（如/static/image.jpg），则直接返回，请求终止，效率最高。

  3. 如果是API请求（如/api/orders），Nginx 根据负载均衡策略（如轮询）将请求转发到后端的Spring Cloud Gateway 集群中的某一个实例。

  4. Spring Cloud Gateway 查询注册中心（如Nacos），找到order-service的真实实例地址，并进行JWT令牌校验、记录审计日志等业务操作。

  5. 最后，将请求转发到真正的order-service实例上。

三、Spring Cloud Gateway使用

3.1 依赖与基础配置

首先，在 pom.xml 中添加 Spring Cloud Gateway 依赖。注意：Gateway 基于 WebFlux，因此需要移除 spring-boot-starter-web 依赖，否则会导致启动报错。

<!-- Gateway 依赖 -->
<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>

注意：Spring Cloud Gateway是基于 WebFlux 的编程模型，也意味着需要编写响应式代码。如果你需要集成一些只提供阻塞式客户端的库（例如，某些旧的 JDBC 驱动、同步的 SDK），必须非常小心，需要通过 publishOn 等方法将其调度到单独的弹性线程池中执行，否则会阻塞整个事件循环线程，反而破坏其性能优势。

随后，在 application.yml 中进行基本配置：

server:port: 9527 # 网关端口
spring:application:name: cloud-gatewaycloud:nacos:discovery:server-addr: localhost:8848 # Nacos 注册中心地址gateway:discovery:locator:enabled: true # 开启从注册中心动态创建路由的功能:cite[5]routes: # 开始配置路由- id: payment_route # 路由ID，唯一即可:cite[5]uri: lb://cloud-payment-service # 目标服务名（lb:// 开启负载均衡）:cite[5]predicates: # 断言集合- Path=/payment/get/** # 路径断言:cite[5]#- After=2020-09-15T15:53:47.026+08:00[Asia/Shanghai] # 时间后断言:cite[2]:cite[5]#- Header=X-Request-Id, \d+ # 请求头断言:cite[2]:cite[5]filters: # 过滤器集合- AddResponseHeader=X-Response-Foo, Bar # 添加响应头:cite[1]- StripPrefix=1 # 去除路径前缀（例如请求/gateway/a，转发给服务时为/a）:cite[2]

3.2 两种配置方式

Spring Cloud Gateway 提供了两种配置路由的方式：

  • YAML/Properties 配置文件：如上例所示，是静态配置的常用方式。

  • Java DSL 配置：通过 RouteLocator Bean 实现动态路由，更灵活。

@Configuration
public class GatewayConfig {@Beanpublic RouteLocator customRouteLocator(RouteLocatorBuilder builder) {return builder.routes().route("path_route_xlj", r -> r.path("/guonei").uri("http://news.baidu.com/guonei")).build();}
}

3.3 自定义过滤器

可以创建自定义全局过滤器 (GlobalFilter) 来实现鉴权、日志记录等通用逻辑。下面的例子模拟了一个简单的授权验证：

@Component
@Slf4j
public class AuthorizeFilter implements GlobalFilter, Ordered {private static final String AUTHORIZE_TOKEN = "token";@Overridepublic Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {ServerHttpRequest request = exchange.getRequest();HttpHeaders headers = request.getHeaders();String token = headers.getFirst(AUTHORIZE_TOKEN);if (token == null) {token = request.getQueryParams().getFirst(AUTHORIZE_TOKEN);}if (token == null) {log.warn("Token is missing, unauthorized!");exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);return exchange.getResponse().setComplete();}// TODO: 这里应添加更复杂的token校验逻辑（如JWT解析）return chain.filter(exchange);}@Overridepublic int getOrder() {return -1; // 过滤器执行顺序，值越小优先级越高:cite[6]}
}

  • 过滤器顺序：全局过滤器可以通过实现 Ordered 接口或 @Order 注解来指定执行顺序，值越小优先级越高。

注意：过滤器链不宜过长，避免复杂操作阻塞响应线程。

3.4 关键特性与高级功能

  • 动态路由与负载均衡：通过与服务发现组件（如 Nacos、Eureka、Consul）集成，并结合 lb:// 前缀，Gateway 可以自动从注册中心获取服务实例列表并进行负载均衡。

  • 限流 (Rate Limiting)：可以使用 RequestRateLimiter 网关过滤器工厂集成 Redis 和令牌桶算法实现对请求的限流，保护后端服务。

filters:- name: RequestRateLimiterargs:key-resolver: '#{@myKeyResolver}' # 指定限流键解析器:cite[2]redis-rate-limiter.replenishRate: 1 # 每秒生成的令牌数:cite[2]redis-rate-limiter.burstCapacity: 5 # 令牌桶总容量:cite[2]

KeyResolver Bean 示例（按 IP 限流）：

@Component
public class MyKeyResolver implements KeyResolver {@Overridepublic Mono<String> resolve(ServerWebExchange exchange) {return Mono.just(exchange.getRequest().getRemoteAddress().getAddress().getHostAddress());}
}

  • 熔断降级：虽然 Gateway 默认集成了 Hystrix，但 Hystrix 已进入维护模式。建议集成 Resilience4J 或 Sentinel 等更现代的容错库来实现熔断降级功能。

  • 集成 Spring Security：Spring Cloud Gateway 可以与 Spring Security 集成，为网关添加更完善的身份认证和授权机制。

  • CORS 跨域处理：可以在网关层统一配置跨域规则，简化微服务的开发。

  • 生产环境高可用：部署多个网关实例，并通过负载均衡器（如 Nginx、F5）对外提供统一入口，实现高可用。

  • 性能监控：利用 Spring Boot Actuator 或集成 Micrometer 等监控工具来收集网关的指标（如 QPS、延迟、错误率），便于发现问题并进行调优。

3.5 主要配置项及示例

配置类别配置项 (YAML路径)默认值说明备注/示例
核心与全局配置spring.cloud.gateway.enabledtrue是否启用网关功能设置为 false 可禁用网关
spring.cloud.gateway.fail-on-route-definition-errortrue路由定义错误时是否启动失败设为 false 时，错误会记录警告但不会阻止应用启动
路由配置 (Routes)spring.cloud.gateway.routes[*].id(无)路由的唯一标识符必填，例如 user-service-route
spring.cloud.gateway.routes[*].uri(无)路由的目标URI支持 http://, https://, lb://(负载均衡) 等模式
spring.cloud.gateway.routes[*].order(按声明顺序)路由的优先级数值越小，优先级越高
spring.cloud.gateway.routes[*].predicates(无)断言条件列表，用于匹配请求可配置多个，常用 Path, Method, Header, Query, Host, Cookie 等
spring.cloud.gateway.routes[*].filters(无)过滤器列表，用于修改请求或响应可配置多个，如 AddRequestHeader, RewritePath, Retry 等
默认过滤器spring.cloud.gateway.default-filters(无)全局应用的过滤器列表，会对所有路由生效格式同路由级别的 filters
HTTP客户端配置spring.cloud.gateway.httpclient.connect-timeout约45s或10s (版本差异)建立TCP连接的最大等待时间 (毫秒或Duration格式)推荐 2s~5s
spring.cloud.gateway.httpclient.response-timeout30s从发送请求到接收完整响应的最大等待时间 (Duration格式)推荐普通API 10s~30s，文件上传下载 60s~300s
spring.cloud.gateway.httpclient.ssl.handshake-timeout-millis(无)SSL握手超时时间 (毫秒)
服务发现与动态路由spring.cloud.gateway.discovery.locator.enabledfalse是否启用基于服务发现的动态路由需要引入服务发现客户端（如Nacos, Eureka）依赖
spring.cloud.gateway.discovery.locator.lower-case-service-idfalse是否将服务ID转换为小写适用于Eureka等服务ID可能大写的场景
spring.cloud.gateway.discovery.locator.predicatesPath=/**动态路由的默认断言规则
spring.cloud.gateway.discovery.locator.filters(无)动态路由的默认过滤器
spring.cloud.gateway.discovery.locator.url-expression'lb://'+serviceId动态路由URI的生成表达式
CORS跨域配置spring.cloud.gateway.globalcors.cors-configurations['/**'].allowed-origins(无)允许跨域访问的源例如 http://localhost:8090
spring.cloud.gateway.globalcors.cors-configurations['/**'].allowed-methods(无)允许的HTTP方法例如 GET, POST, PUT, DELETE, OPTIONS
spring.cloud.gateway.globalcors.cors-configurations['/**'].allowed-headers(无)允许的请求头可使用 * 通配符
spring.cloud.gateway.globalcors.cors-configurations['/**'].allow-credentials(无)是否允许发送Cookie等凭证
spring.cloud.gateway.globalcors.cors-configurations['/**'].max-age(无)预检请求结果的缓存时间（秒）
SSL/TLS配置server.ssl.enabledfalse网关自身是否启用HTTPS
server.ssl.key-store(无)密钥库路径
server.ssl.key-store-password(无)密钥库密码
server.ssl.key-alias(无)密钥别名
spring.cloud.gateway.httpclient.ssl.useInsecureTrustManager(无)是否信任所有下游服务的证书（不安全，仅测试用）
spring.cloud.gateway.httpclient.ssl.trustedX509Certificates(无)受信任的特定下游服务证书列表

路由断言 (Predicates) 示例： predicates 定义了匹配规则，以下是一些常见配置：

predicates:- Path=/api/**                 # 路径匹配- Method=GET,POST              # HTTP方法匹配- Header=X-Request-Id, \d+     # 请求头匹配（名称和正则）- Query=name, Jack             # 查询参数匹配（参数名和值，值可正则）- Host=**.example.com          # 主机名匹配- Cookie=sessionid, .+         # Cookie匹配- After=2023-01-20T17:42:47.789-05:00[America/New_York] # 时间之后匹配- Before=2023-01-20T17:42:47.789-05:00[America/New_York] # 时间之前匹配# 可以组合使用，默认为"与"逻辑

过滤器 (Filters) 示例： filters 用于修改请求或响应。

filters:- AddRequestHeader=X-Request-color, blue       # 添加请求头- AddResponseHeader=X-Response-Red, Red        # 添加响应头- RewritePath=/api/(?<segment>.*), /$\{segment} # 重写路径- PrefixPath=/api                              # 添加路径前缀- RemoveRequestHeader=Cookie                   # 移除请求头- name: RequestRateLimiter                     # 请求速率限制args:redis-rate-limiter.replenishRate: 10redis-rate-limiter.burstCapacity: 20- name: Retry                                  # 重试args:retries: 3statuses: BAD_GATEWAY, INTERNAL_SERVER_ERROR# 更多过滤器...

超时配置示例 (基于 Hoxton 及以上版本)：

spring:cloud:gateway:httpclient:connect-timeout: 5000ms    # 连接超时 5秒response-timeout: 60s       # 响应超时 60秒
# 也可为特定路由配置超时 (通过 metadata)
routes:- id: slow_serviceuri: lb://slow-servicepredicates:- Path=/slow/**metadata:response-timeout: 300000   # 300秒connect-timeout: 5000      # 5秒

动态路由与服务发现集成示例 (以 Nacos 为例)：

spring:cloud:gateway:discovery:locator:enabled: true           # 启用动态路由lower-case-service-id: true # 服务名小写routes: # 当然也可以继续使用静态路由配置- id: user-service-routeuri: lb://user-service  # lb:// 表示基于服务名的负载均衡predicates:- Path=/user/**nacos:discovery:server-addr: localhost:8848

全局 CORS 跨域 配置示例：

spring:cloud:gateway:globalcors:add-to-simple-url-handler-mapping: true # 处理 OPTIONS 请求cors-configurations:'[/**]':allowed-origins: "https://www.example.com"allowed-methods: "*"allowed-headers: "*"allow-credentials: truemax-age: 3600

配置建议：

  • 起步阶段：可以从最基本的路由配置（id, uri, predicates）开始。

  • 环境区分：在不同环境（开发、测试、生产）中，注意调整超时时间、重试次数、限流策略等配置。

  • 优先级：牢记 order 值越小优先级越高，以及过滤器链的执行顺序（全局过滤器、路由过滤器）。

  • 监控与排错：合理配置日志级别（如为 org.springframework.cloud.gateway 设置 DEBUG 或 TRACE）有助于排查路由匹配、过滤器执行等问题。

http://www.dtcms.com/a/390734.html

相关文章：

  • conda激活虚拟环境
  • 重构大qmt通达信板块预警自动交易系统--读取通达信成分股
  • 25.9.19 Spring AOP
  • d38: PostgreSQL 简单入门与 Vue3 动态路由实现
  • No006：订阅化时间管理——迈向个性化、生态化的AI服务模式
  • 微服务-sentinel的理论与集成springcloud
  • C++学习：哈希表unordered_set/unordered_map的封装
  • 圆柱永磁体磁场及梯度快速计算与可视化程序
  • 种群演化优化算法：原理与Python实现
  • 基于IPDRR模型能力，每个能力的概念及所要具备的能力产品
  • NUST技术漫谈：当非结构化数据遇见状态跟踪——一场静默的技术革命
  • 在技术无人区开路，OPPO的指南针是“人”
  • AI与NPC发展过程及技术
  • Redis数据库（三）—— 深入解析Redis三种高可用架构：主从复制、哨兵与集群模式
  • (leetcode) 力扣100 13最大子序和(动态规划卡达内算法分治法)
  • SpringBoot整合JUnit：单元测试从入门到精通
  • MySQL三范式详细解析
  • GitHub 仓库权限更改
  • 卷积神经网络（CNN）核心知识点总结
  • Python数据挖掘之基础分类模型_朴素贝叶斯
  • 数字工业化的终极形态：人、机器与算法的三重奏
  • [x-cmd] 在 Linux 与 MacOS 安装与使用 x-cmd
  • wkhtmltopdf 命令参数及作用大全
  • Windows路径转换成Cygwin中的Unix路径的方法
  • JavaWeb之Web资源与Servlet详解
  • [视图功能8] 图表视图：柱状图、折线图与饼图配置实战
  • TDengine IDMP 基本功能——数据可视化（5. 表格）
  • ViTables 安装与 HDF5 数据可视化全指南
  • Python爬虫实战：研究Pandas，构建最新网游数据采集与智能推荐系统
  • 在.NET中实现RabbitMQ客户端的优雅生命周期管理及二次封装