Spring Cloud Gateway网关配置与实战

20XX/XX/XXSpringCloudGateway网关配置与实战汇报人:XXXCONTENTS目录01

网关概述与核心价值02

环境搭建与基础配置03

路由规则设计与实现04

过滤器机制与应用CONTENTS目录05

高级特性配置06

实战案例演示07

常见问题与最佳实践网关概述与核心价值01微服务架构的统一入口API网关作为微服务集群的"大门"，所有客户端请求需通过网关转发至相应服务，隐藏后端服务复杂性，简化客户端调用逻辑。请求路由与负载均衡根据预设规则将请求分发到目标服务，支持通过服务名（如lb://user-service）实现负载均衡，自动分摊流量到多个服务实例。统一功能增强平台集中处理认证授权、限流熔断、日志监控、请求/响应修改等横切关注点，避免每个服务重复实现，提升系统一致性与可维护性。微服务通信的中间层在客户端与微服务之间建立通信桥梁，支持协议转换（如HTTP转WebSocket）、数据脱敏、安全防护等，保障服务间通信安全高效。API网关在微服务架构中的定位SpringCloudGateway核心优势解析基于响应式编程的高性能SpringCloudGateway基于Spring5.x、SpringBoot2.x技术版本编写，采用Webflux中的reactor-netty响应式编程组件，底层使用Netty通讯框架，实现非阻塞异步处理，吞吐量是Zuul1.x的3倍以上。强大的路由与过滤功能核心功能包括路由转发、断言匹配、过滤器链执行，支持动态路由配置，可通过配置中心（如Zookeeper或ConfigServer）实现路由规则的动态更新，满足复杂业务场景需求。无缝整合SpringCloud生态与SpringCloudAlibaba、Nacos、Sentinel等组件完美兼容，支持服务发现、负载均衡、限流熔断等微服务治理能力，原生支持WebSocket协议，适合实时通信场景。灵活的扩展性与易配置性提供丰富的内置过滤器工厂（如AddRequestHeader、StripPrefix、RequestRateLimiter等），同时支持自定义过滤器和路由断言，配置方式灵活，可通过YAML配置文件或Java代码两种方式实现。与Zuul网关的性能对比分析架构设计差异

SpringCloudGateway基于Spring5.x、SpringBoot2.x和ProjectReactor构建，采用非阻塞异步响应式编程模型，底层使用Netty通讯框架；Zuul1.x基于Servlet2.5，采用阻塞式I/O模型，多线程处理请求，线程开销较大。吞吐量性能对比

在相同硬件环境下，SpringCloudGateway的吞吐量是Zuul1.x的3倍以上，尤其在高并发场景下优势明显，能更高效地处理大量并发请求。响应延迟表现

SpringCloudGateway由于基于非阻塞I/O，响应延迟更低，特别是在处理长连接和高并发请求时，能保持更稳定的响应时间；Zuul1.x在高负载下易出现线程阻塞，导致响应延迟增加。资源占用情况

SpringCloudGateway采用响应式编程，能更有效地利用系统资源，在相同请求量下CPU和内存占用率低于Zuul1.x，具备更好的资源利用率和scalability。核心组件三元模型：路由-断言-过滤器

01路由（Route）：网关的基本单元路由是Gateway的核心模块，由唯一ID、目标URI、一组断言和过滤器组成。当请求满足断言条件时，将被转发至URI指定的后端服务。例如配置ID为user-service-route，目标URI为lb://user-service，通过Path断言匹配请求路径。

02断言（Predicate）：请求匹配规则断言是请求转发的判断条件，基于HTTP请求的路径、方法、头信息等进行匹配。常见断言类型包括Path（路径匹配，如/users/**）、Method（请求方法匹配，如GET）、Header（请求头匹配，如token=^[A-Za-z0-9]+$）、Host（主机名匹配，如**.）等，多个断言需同时满足。

03过滤器（Filter）：请求/响应处理过滤器用于在请求转发前后修改请求或响应，分为局部过滤器（作用于特定路由）和全局过滤器（作用于所有路由）。内置过滤器如AddRequestHeader（添加请求头）、StripPrefix（移除路径前缀）、RewritePath（重写路径），支持自定义过滤器实现鉴权、限流等功能。环境搭建与基础配置02开发环境准备与依赖管理

基础环境要求JDK8及以上版本，SpringBoot2.x，SpringCloud2021.0.x及对应版本，Maven3.6+或Gradle7.0+构建工具。

核心依赖配置在pom.xml中添加SpringCloudGateway依赖：<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-gateway</artifactId></dependency>，若需服务发现集成Nacos或Eureka，需添加对应服务发现依赖。

排除冲突依赖Gateway基于WebFlux响应式编程，需排除spring-boot-starter-web依赖，避免Netty容器冲突，确保项目中仅保留spring-boot-starter-webflux依赖。

依赖管理最佳实践使用SpringCloudBOM管理依赖版本，通过dependencyManagement统一控制SpringCloud及各组件版本，避免版本冲突，提升项目稳定性。启动类配置与项目结构

基础启动类实现创建标准SpringBoot启动类，使用@SpringBootApplication注解，无需额外@EnableGateway注解。示例代码：@SpringBootApplicationpublicclassGatewayApplication{publicstaticvoidmain(String[]args){SpringApplication.run(GatewayApplication.class,args);}}

服务发现集成配置若需集成服务发现（如Nacos/Eureka），添加@EnableDiscoveryClient注解开启服务注册发现功能，结合配置文件中服务注册中心地址实现动态路由。

典型项目结构解析推荐采用"配置类+过滤器+工具类"三层结构：config目录存放路由配置类（如GatewayConfig）、filter目录存放自定义过滤器、utils目录存放通用工具类，资源目录放置application.yml配置文件。

依赖冲突规避要点Gateway基于WebFlux响应式编程，需排除spring-boot-starter-web依赖，避免Netty容器冲突；添加spring-cloud-starter-gateway核心依赖及服务发现组件依赖（如spring-cloud-starter-alibaba-nacos-discovery）。配置文件加载顺序详解

核心配置文件类型SpringCloudGateway配置文件主要包括bootstrap.yml（引导配置，高优先级）、application.yml（应用配置）以及通过配置中心（如Nacos）获取的远程配置文件。

配置加载优先级配置加载顺序为：bootstrap.yml→bootstrap-{profile}.yml（环境特定配置）→Nacos配置中心动态配置→application.yml→application-{profile}.yml，高优先级配置会覆盖低优先级配置。

环境隔离与命名空间通过files.active指定环境（如dev/test/prod），结合Nacos命名空间（namespace）实现多环境配置隔离，确保不同环境配置独立管理。

共享配置与动态刷新使用shared-configs配置共享通用配置（如teach-common.yml），结合配置中心支持配置动态更新，无需重启网关即可生效。服务发现依赖引入在pom.xml中添加Nacos服务发现依赖：<dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId></dependency>Nacos地址配置在application.yml中配置Nacos服务端地址：spring.cloud.nacos.discovery.server-addr=:8848服务发现开关启用通过配置spring.cloud.gateway.discovery.locator.enabled=true开启服务发现自动路由功能服务名路由规则启用后可通过http://网关地址/服务名/**自动路由到对应服务，如访问http://localhost:8080/user-service/users/1将转发至user-service服务服务名小写配置配置spring.cloud.gateway.discovery.locator.lower-case-service-id=true可将服务名转为小写，避免因大小写不一致导致路由失败Nacos服务发现集成配置路由规则设计与实现03路由核心属性解析01路由ID（id）路由的唯一标识符，字符串类型，必须在所有路由配置中保持唯一，建议与服务名关联以提高可读性，如"user-service-route"。02目标服务URI（uri）指定请求转发的目标地址，支持具体URL（如"http://localhost:8081"）或服务发现负载均衡地址（如"lb://user-service"，lb表示启用负载均衡）。03断言集合（predicates）定义请求匹配规则的列表，只有所有断言条件均满足时请求才会被路由。常见断言包括Path（路径匹配）、Method（请求方法）、Header（请求头）、Host（主机名）等。04过滤器集合（filters）对请求/响应进行处理的逻辑链，可修改请求头、重写路径、添加参数等。内置过滤器如StripPrefix（移除路径前缀）、AddRequestHeader（添加请求头）、RewritePath（重写路径）等。05路由优先级（order）整数类型，值越小优先级越高，用于当多个路由规则可能匹配同一请求时确定执行顺序，未指定时按配置顺序匹配。静态路由配置示例基础路由配置样例spring:cloud:gateway:routes:-id:user-service-routeuri:lb://user-servicepredicates:-Path=/users/**filters:-StripPrefix=1路径重写配置示例spring:cloud:gateway:routes:-id:rewrite-routeuri:http://localhost:10001predicates:-Path=/api/brand/**filters:-RewritePath=/api/brand/(?<segment>.*),/${segment}多条件组合路由示例spring:cloud:gateway:routes:-id:multi-condition-routeuri:lb://order-servicepredicates:-Path=/orders/**-Method=GET-Header=X-Version,v1filters:-AddRequestHeader=X-Request-From,gateway动态路由的定义与优势动态路由指无需重启网关，通过配置中心（如Nacos、ConfigServer）实时更新路由规则，实现请求转发策略的动态调整，提升微服务架构的灵活性和可维护性。服务发现路由的开启配置通过设置spring.cloud.gateway.discovery.locator.enabled=true，网关可自动从服务注册中心（如Nacos、Eureka）获取服务列表，生成路由规则，无需手动配置每个服务地址。自动路由的生成规则开启服务发现后，网关默认按服务名创建路由，如服务名user-service对应路由ID为ReactiveCompositeDiscoveryClient_user-service，匹配路径为/user-service/**，并通过RewritePath过滤器重写路径。服务发现与静态路由的协同静态路由（手动配置）与服务发现路由可共存，静态路由优先级高于自动生成路由，适用于需要自定义断言、过滤器的场景，自动路由则简化常规服务的路由配置。动态路由与服务发现机制常用断言类型及配置示例

路径匹配（Path）通过请求路径匹配路由，支持精确匹配、单级通配符(*)和多级通配符(**)。示例：Path=/api/user/**匹配所有以/api/user/开头的路径。

请求方法匹配（Method）根据HTTP请求方法（GET/POST/PUT等）进行匹配。示例：Method=GET仅允许GET请求通过该路由。

请求头匹配（Header）检查请求头是否存在指定名称且值符合正则表达式。示例：Header=token,^(?!\\d+$)[\\da-zA-Z]+$要求请求头包含token且值为数字字母组合。

时间匹配（After/Before/Between）基于请求时间判断是否路由。示例：After=2024-03-09T00:00:00+08:00[Asia/Shanghai]仅允许该时间之后的请求通过。

Cookie匹配检查请求是否携带指定Cookie名称和值。示例：Cookie=AA,AA仅匹配包含name为AA且value为AA的Cookie请求。路由优先级与匹配规则

路由优先级控制机制路由优先级通过order属性定义，数值越小优先级越高。默认按配置顺序匹配，order值可显式设置以调整执行顺序，确保关键路由优先匹配。

路径匹配规则详解支持精确匹配（如Path=/api/user）、单级通配符（Path=/api/user/*）、多级通配符（Path=/api/user/**）和正则表达式（Path=/api/user/\\d+），满足不同场景的路径匹配需求。

多条件组合匹配策略可组合使用Path、Method、Header等多种断言条件，如同时匹配路径（Path=/api/order/**）和请求方法（Method=POST），只有所有条件满足时才触发路由转发。

路由匹配冲突解决方案当多个路由规则冲突时，优先匹配order值小的路由；若order相同，则按配置顺序匹配。建议通过合理设置order值和路径精确性避免冲突，确保路由转发符合预期。过滤器机制与应用04过滤器分类与生命周期

按作用范围分类全局过滤器（GlobalFilter）作用于所有路由，无需配置即可生效，适用于全局鉴权、日志记录等通用场景；局部过滤器（GatewayFilter）需绑定到特定路由，仅对该路由生效，用于路由级定制化处理。

按执行阶段分类Pre过滤器在请求路由到目标服务前执行，可实现鉴权、修改请求头；Post过滤器在目标服务返回响应后执行，用于修改响应头、记录日志等操作。

过滤器执行流程客户端请求依次经过Pre过滤器链、路由转发至目标服务，服务响应后逆向经过Post过滤器链返回客户端，执行顺序由@Order注解或Ordered接口的order值决定，值越小优先级越高。内置过滤器工厂详解请求头操作过滤器AddRequestHeader：添加请求头，如"AddRequestHeader=X-Request-Id,12345"；RemoveRequestHeader：移除指定请求头，如"RemoveRequestHeader=Authorization"；SetRequestHeader：覆盖请求头值，如"SetRequestHeader=Host,"。请求参数操作过滤器AddRequestParameter：添加请求参数，如"AddRequestParameter=traceId,GATEWAY-TRACE"；RemoveRequestParameter：移除敏感参数，如"RemoveRequestParameter=password"；MapRequestHeader：映射请求头，如"MapRequestHeader=X-User-Id,userId"。路径操作过滤器StripPrefix：移除路径前缀，如"StripPrefix=1"可将"/api/user/list"转为"/user/list"；PrefixPath：添加路径前缀，如"PrefixPath=/brand"可将"/abc"转为"/brand/abc"；RewritePath：重写路径，如"RewritePath=/api/(?<segment>.*),/$\\{segment}"。响应处理过滤器AddResponseHeader：添加响应头，如"AddResponseHeader=X-Response-Time,100ms"；RemoveResponseHeader：移除响应头，如"RemoveResponseHeader=Server"；SetStatus：设置响应状态码，如"SetStatus=401"。流量控制过滤器RequestRateLimiter：基于令牌桶算法实现限流，需配置限流策略；Retry：请求重试机制，可设置重试次数和状态码；RequestSize：限制请求体大小，如"RequestSize=10MB"，超过返回413状态码。请求头与参数处理过滤器

01请求头添加：AddRequestHeader在请求转发前添加指定请求头，配置示例：-AddRequestHeader=X-Request-Source,gateway。常用于传递请求来源标识，方便下游服务做权限控制。

02请求头移除：RemoveRequestHeader转发前移除请求中指定的敏感请求头，配置示例：-RemoveRequestHeader=Authorization。适用于下游服务不需要客户端直接传递令牌，由网关统一处理认证的场景。

03请求头覆盖：SetRequestHeader若请求中已存在指定请求头则覆盖其值，不存在则添加，配置示例：-SetRequestHeader=Authorization,111111。与AddRequestHeader的区别是会覆盖原有值。

04请求参数添加：AddRequestParameter转发请求时为请求添加参数，支持GET/POST，配置示例：-AddRequestParameter=from,gateway。可用于统计请求来源或传递额外标识如灰度标记。

05请求参数移除：RemoveRequestParameter转发前移除请求中的指定敏感参数，配置示例：-RemoveRequestParameter=password。可有效防止敏感参数如密码等传递到下游服务。路径重写与前缀处理

StripPrefix过滤器：移除路径前缀通过配置StripPrefix=1，可移除请求路径中的第一个前缀段。例如，请求/api/user/get经处理后转发为/user/get。

PrefixPath过滤器：添加路径前缀使用PrefixPath=/brand配置，可在请求路径前添加指定前缀。如原请求/abc会被转换为/brand/abc后转发。

RewritePath过滤器：正则路径重写通过正则表达式实现路径重写，例如配置RewritePath=/api/product/(?<segment>.*),/$\{segment\}，可将/api/product/xxx重写为/xxx。

组合使用注意事项StripPrefix与PrefixPath一般不建议同时使用，若需特殊场景组合使用，需注意执行顺序，通常StripPrefix在前，PrefixPath在后。全局过滤器实现方式

实现GlobalFilter接口创建类实现GlobalFilter接口，重写filter方法处理请求逻辑，通过ServerWebExchange获取请求/响应对象，使用GatewayFilterChain传递请求。

实现Ordered接口指定优先级实现Ordered接口或使用@Order注解，返回int类型优先级值（值越小优先级越高），控制多个全局过滤器的执行顺序。

通过@Component注解注册在自定义全局过滤器类上添加@Component注解，Spring容器自动扫描并注册为Bean，无需额外配置即可作用于所有路由。

示例：全局鉴权过滤器实现验证请求头中Authorization令牌逻辑，无效时返回401状态码；通过getOrder()返回0确保优先执行，代码简洁且作用于所有路由。高级特性配置05添加Sentinel依赖在pom.xml中添加SpringCloudAlibabaSentinel依赖：<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-alibaba-sentinel</artifactId></dependency>启用Sentinel配置在application.yml中配置：spring.cloud.gateway.sentinel.enabled=true，开启网关Sentinel集成功能配置Sentinel过滤器创建SentinelGatewayConfig配置类，注册SentinelGatewayFilterFactory和SentinelGatewayBlockExceptionHandlerBean，实现限流规则生效与异常处理路由级限流规则配置在路由配置中通过filters属性添加Sentinel限流规则，例如：-name:RequestRateLimiterargs:{key-resolver:'#{@ipKeyResolver}',redis-rate-limiter.replenishRate:10,redis-rate-limiter.burstCapacity:20}Sentinel限流集成配置CORS跨域配置策略CORS跨域问题产生原因浏览器出于安全考虑实施同源策略，当请求协议、域名或端口不同时会触发跨域限制，需通过CORS机制允许跨域访问。全局CORS配置方式在application.yml中通过spring.cloud.gateway.globalcors配置全局跨域规则，例如allowed-origins:"http://localhost:3000"允许指定源的跨域请求。路由级别CORS配置针对特定路由在routes下配置cors过滤器，可实现不同服务的差异化跨域策略，优先级高于全局配置。常见配置参数说明allowed-methods指定允许的HTTP方法，allowed-headers配置允许的请求头，allow-credentials设置是否允许携带Cookie，max-age定义预检请求缓存时间。动态配置中心集成配置中心核心价值解决传统静态配置修改需重启网关的问题，实现路由规则、过滤器参数等配置的实时更新，提升微服务架构的灵活性和可维护性。主流配置中心选型支持Nacos、SpringCloudConfigServer等主流配置中心，其中Nacos同时提供服务发现与配置管理功能，与SpringCloudGateway无缝集成。动态路由配置实现通过配置中心存储路由规则YAML配置，网关启动时从配置中心拉取，配置变更时自动刷新。示例：在Nacos中修改routes节点即可实时更新路由策略。配置动态刷新验证结合SpringCloudGatewayActuator端点（如/actuator/gateway/routes），可查看当前生效路由；修改配置中心路由后，无需重启网关，10秒内即可通过端点验证更新结果。负载均衡策略配置

负载均衡URI格式使用"lb://服务名"格式指定目标服务，如"lb://user-service"，自动从服务注册中心获取实例列表并实现负载均衡。

默认负载均衡策略SpringCloudGateway默认集成Ribbon，采用轮询（RoundRobin）策略分发请求，无需额外配置即可生效。

自定义负载均衡策略通过配置文件指定服务级策略，如设置"user-service.ribbon.NFLoadBalancerRuleClassName=flix.loadbalancer.RandomRule"实现随机访问。

配置示例在application.yml中配置：spring.cloud.gateway.routes[0].uri=lb://order-service，结合服务注册中心实现动态负载均衡。实战案例演示06用户服务路由配置案例

基础路由配置（YAML方式）spring:cloud:gateway:routes:-id:user-service-routeuri:lb://user-servicepredicates:-Path=/users/**filters:-StripPrefix=1

路径重写与负载均衡通过lb://user-service实现服务发现与负载均衡，StripPrefix=1移除/users前缀，将请求转发至user-service的对应接口

多条件匹配示例predicates:-Path=/api/user/**-Method=GET-Header=X-Version,v1，组合路径、请求方法和请求头条件实现精准路由

Java代码配置方式@BeanpublicRouteLocatorcustomRouteLocator(RouteLocatorBuilderbuilder){returnbuilder.routes().route("user-service",r->r.path("/users/**").uri("lb://user-service").filters(f->f.stripPrefix(1))).build();}订单服务路由与过滤实现

订单服务路由规则配置在application.yml中配置订单服务路由，设置id为order-service-route，uri为lb://order-service，通过Path=/api/order/**断言匹配请求路径，使用StripPrefix=1过滤器去除/api前缀后转发至目标服务。

路由断言组合应用结合Method=POST断言限制仅POST请求访问订单创建接口，添加Header=token,^(?!\\d+$)[\\da-zA-Z]+$断言验证请求头token格式，确保请求合法性后进行路由转发。

订单服务过滤器链配置配置AddRequestHeader=X-Request-Source,gateway添加请求来源标识，使用AddRequestParameter=traceId,GATEWAY-TRACE-${random.uuid}注入链路追踪ID，通过RequestRateLimiter过滤器基于Redis实现订单接口限流保护。

动态路由与服务发现集成开启spring.cloud.gateway.discovery.locator.enabled=true，实现从Nacos注册中心自动发现order-service服务实例，结合lb协议实现负载均衡路由，无需手动维护服务地址列表。自定义全局鉴权过滤器开发

全局过滤器实现步骤实现GlobalFilter接口与Ordered接口，通过@Component注解自动注册为SpringBean，无需额外配置即可作用于所有路由。核心逻辑：Token验证流程从请求头获取Authorization令牌，验证其有效性（如JWT签名校验），无效则返回401Unauthorized，有效则通过chain.filter(exchange)放行请求。优先级控制：Order值设置通过getOrder()方法返回整数优先级，值越小执行越早，建议设置为0确保鉴权在其他过滤器前执行，避免无效请求进入后续流程。代码示例：JWT鉴权过滤器@ComponentpublicclassAuthGlobalFilterimplementsGlobalFilter,Ordered{@OverridepublicMono<Void>filter(ServerWebExchangeexchange,GatewayFilterChainchain){Stringtoken=exchange.getRequest().getHeaders().getFirst("Authorization");if(token==null||!token.startsWith("Bearer")){exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);returnexchange.getResponse().setComplete();}returnchain.filter(exchange);}@OverridepublicintgetOrder(){return0;}}限流熔断实战配置基于Sentinel的限流配置引入spring-cloud-starter-alibaba-sentinel依赖，配置spring.cloud.gateway.sentinel.enabled=true开启限流。通过@Bean定义SentinelGatewayFilterFactory和SentinelGatewayBlockExceptionHandler，实现基于QPS的流量控制。RequestRateLimiter过滤器应用使用内置RequestRateLimiter过滤器，配置key-resolver指定限流维度（如IP），结合Redis实现令牌桶算法。示例：filters:-name:RequestRateLimiterargs:redis-rate-limiter.replenishRate=10,redis-rate-limiter.burstCapacity=20。CircuitBreaker熔断配置集成Resilience4j或Sentinel实现熔断，配置CircuitBreaker过滤器指定熔断名称和降级处理逻辑。例如：filters:-name:CircuitBreakerargs:name=myServiceCircuitBreaker,fallbackUri=forward:/fallback。动态规则配置与监控通过Nacos配置中心动态更