网关路由配置这件事看着就是“从哪来、到哪去”的转发规则可真正上手之后你会发现越简单的配置越容易埋雷。前阵子我在做微服务网关改造时被一段yml折腾了一下午——明明路由规则都写对了请求就是打不到目标服务后来查出来是谓词顺序和StripPrefix叠加导致的问题。这篇就把Spring Cloud Gateway的配置方式从头到脚捋一遍包括静态路由、基于注册中心的动态路由、以及我踩过的那些坑。1. 路由配置的三种姿势yml、Java装配与配置中心1.1 四种配置方式的适用边界Spring Cloud Gateway支持多种配置入口很多初学者只知道在application.yml里写死路由但其实选择哪种方式直接决定了后续维护成本和动态能力。先把结论放前面配置方式动态性适合场景维护成本yml静态配置需重启才能生效路由数量少、变化不频繁低Java Bean方式需重启才能生效需要复杂逻辑生成路由中配置中心Nacos/Consul支持动态刷新路由频繁调整、多环境隔离中高RouteDefinitionRepository自定义存储支持运行时变更需要后台管理界面、灰度发布高1.2 yml声明式配置的基本结构最常见的静态路由配置长这样spring: cloud: gateway: routes: - id: order-service-route uri: http://192.168.1.100:8082 predicates: - Path/api/order/** filters: - StripPrefix1 - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1这段配置里有两个值得注意的点。uri字段可以是具体的HTTP地址也可以是lb://开头的注册中心服务名。前者适合后端服务地址固定不变的小项目后者是微服务架构下的标准做法。StripPrefix1的作用是去掉路径前缀比如请求进来是/api/order/list经过StripPrefix1之后转发到下游的就是/order/list。这里最容易出错的是前缀层数算错后面我会专门讲。1.3 用Java代码动态构建路由如果路由规则需要依赖数据库查询结果、或者要经过复杂的条件判断再决定转发目标yml就有点力不从心了。这时候可以通过RouteLocatorBuilder来编程式构建Configuration public class GatewayRoutesConfig { Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route(order-service-route, r - r .path(/api/order/**) .filters(f - f.stripPrefix(1)) .uri(http://192.168.1.100:8082)) .route(user-service-route, r - r .path(/api/user/**) .filters(f - f.stripPrefix(1)) .uri(lb://user-service)) .build(); } }Java配置和yml本质上是等价的yml最终也会被解析成RouteDefinition再转成Route对象。选择哪种方式取决于你的路由定义是相对固定还是需要代码动态生成。1.4 配置中心的接入思路当路由规则需要频繁调整比如上线新服务、切换流量比例每改一次就重启网关不太现实。这时可以把路由配置放到Nacos或Consul里Spring Cloud Gateway在2.0版本之后支持从配置中心动态刷新路由。核心是监听配置变更事件然后发布RefreshRoutesEventComponent public class RoutesRefresher implements ApplicationEventPublisherAware { private ApplicationEventPublisher publisher; private NacosConfigManager nacosConfigManager; Override public void setApplicationEventPublisher(ApplicationEventPublisher publisher) { this.publisher publisher; } EventListener public void onNacosConfigReceived(NacosConfigReceivedEvent event) { // 配置变更后把新的路由定义加载到RouteDefinitionRepository loadNewRouteDefinitions(); // 通知Gateway刷新路由 this.publisher.publishEvent(new RefreshRoutesEvent(this)); } }这里有个很容易忽略的细节光有RefreshRoutesEvent还不够你必须把新的路由定义写入RouteDefinitionRepositoryGateway刷新时才会读到最新数据。实际项目中很多人只发布了事件路由却没更新查了半天发现是数据源没换。2. 路由配置里的关键字段拆解ID、URI、谓词与过滤器2.1 路由唯一标识ID的命名习惯每个路由必须有一个唯一的id。这个id不仅是标识在日志排查、监控告警时会直接作为维度出现。建议命名规则业务线-服务名-用途比如trade-order-route、admin-user-route。我第一次没注意id的唯一性在两个环境的配置里复用同样的id结果线上路由时好时坏因为其中一个配置被另外一个覆盖了。记住路由id在同一个网关实例中必须全局唯一重复id会导致路由表覆盖而且不报任何错误。2.2 URI的写法http地址与lb协议的差别uri决定请求最终转发到哪目前支持三种写法http://host:port固定地址适用于单体服务或地址不变的后端https://host:port走HTTPS转发lb://service-name结合注册中心做客户端负载均衡lb://协议会触发ReactiveLoadBalancer进行服务实例选择本质上是让Gateway充当负载均衡客户端。但要注意lb://后面的服务名必须和注册中心里的服务名完全一致大小写敏感。2.3 谓词Predicate才是路由判断的核心逻辑谓词决定了“什么请求会走这条路由”。Spring Cloud Gateway内置了很多谓词工厂最常用的几个谓词类型写法示例匹配逻辑PathPath/api/order/**按请求路径匹配**匹配多级路径MethodMethodGET,POST按HTTP方法匹配HeaderHeaderX-Request-Id, \d按请求头是否存在或正则匹配QueryQueryname, abc.*按查询参数名和值匹配CookieCookiesessionId, 12345按Cookie名值匹配HostHost**.example.com按Host头匹配通配符RemoteAddrRemoteAddr192.168.1.1/24按客户端IP匹配WeightWeightgroup1, 8按权重分组灰度发布常用谓词是链式且必须全部满足的。同一个路由下配置多个谓词要求这些条件同时成立才会命中。有一条Path/api/**和一条HeaderX-Versionv2请求必须同时满足才走这条路由而不是二选一。2.4 过滤器Filter对请求响应做的事过滤器是路由配置里灵活度最高的部分。内置过滤器很多实际开发中这几个必须吃透StripPrefix去掉路径前缀数值代表去掉几段。/api/order/list配StripPrefix1转发为/order/list配StripPrefix2转发为/listRewritePath正则重写路径支持分组引用AddRequestHeader/AddRequestParameter给下游请求追加头或参数RemoveRequestHeader/RemoveResponseHeader脱敏场景常用Retry下游异常时的重试机制RequestRateLimiter令牌桶限流CircuitBreaker集成Resilience4j做熔断降级看一个组合使用的例子filters: - StripPrefix1 - RewritePath/order/(?segment.*), /new-order/$\{segment} - AddRequestHeaderX-Gateway-Host, gateway.internal - AddRequestParametersource, web这里需要注意RewritePath和StripPrefix同时用的时候执行顺序是按配置的先后来的。所以如果你先StripPrefix再RewritePath匹配的路径已经是去掉前缀后的路径了很容易把规则写废。3. 路由优先级与匹配流程顺序就是规则的第一条3.1 路由匹配的短路机制在这个按概率即可的配置场景下有一个核心机制必须搞清楚Gateway按路由配置顺序从上到下匹配命中即停后面的路由不再判断。举个例子routes: - id: exact-api uri: http://service-a:8080 predicates: - Path/api/exact - id: wildcard-api uri: http://service-b:8080 predicates: - Path/api/**如果请求是/api/exact会命中exact-api不会继续匹配wildcard-api。这个短路机制很符合直觉但反过来说如果你把泛化的/api/**放在精确路由前面所有匹配到的请求都会被吞掉精确路由永远不生效。3.2 用order字段显式控制优先级yml配置里有一个order字段可以显式指定优先级数值越小越先匹配默认值是0。多个路由的匹配优先级处理逻辑如下routes: - id: low-priority uri: http://service-b:8080 order: 10 predicates: - Path/api/** - id: high-priority uri: http://service-a:8080 order: 1 predicates: - Path/api/exact这里order1的high-priority会先参与匹配命中/api/exact后短路返回。配置中建议泛化规则order值设大精确规则order值设小。3.3 多个谓词组合的正确姿势谓词之间是AND关系但很多人在配置时会产生“或”的错觉。比如想让GET和POST请求都走同一条路由正确写法是predicates: - Path/api/order/** - MethodGET,POSTMethodGET,POST表示逗号分隔的“或”关系这是谓词内部值的语义不是谓词与谓词之间的语义。再拓展一下如果是/api/order和/api/user两个路径都走同一条路由写法是predicates: - Path/api/order/**,/api/user/**Path谓词里也可以用逗号分隔多个模式用正则替换时也更方便。4. 动态路由与注册中心联动从写死地址到lb自动发现4.1 注册中心模式下的路由配置逻辑微服务架构下后端服务实例的IP端口是动态变化的依赖固定HTTP地址配置不现实。Spring Cloud Gateway配合Nacos或Consul时配置可以简化成这样spring: cloud: gateway: discovery: locator: enabled: true lowerCaseServiceId: true routes: - id: user-service-route uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1启用discovery.locator.enabledtrue之后Gateway会自动把注册中心里的服务转换为路由你可以直接通过http://网关地址/服务名/接口路径访问。这个功能适合快速联调但不推荐生产环境直接用因为自动生成的路由缺乏过滤器和谓词控制能力也不够可控。4.2 lb协议背后的负载均衡机制配置lb://user-service时Gateway启动时会注入LoadBalancerClientFilter它的工作是从uri中提取user-service服务名向注册中心获取user-service的服务实例列表通过ReactiveLoadBalancer选择一个实例默认是轮询将请求转发到所选实例的具体IP和端口整个过程对调用方透明所以Gateway实例本身也成了负载均衡器。这里有个经验Gateway和后端服务之间尽量走内网不要在公网上暴露lb://路由。4.3 基于RouteDefinitionRepository的自定义路由管理如果配置中心和yml都无法满足在运行期用接口动态管理路由是更彻底的方案。实现方式不复杂核心是自己实现RouteDefinitionRepository接口把路由定义存到数据库或Redis中Component public class DatabaseRouteDefinitionRepository implements RouteDefinitionRepository { Autowired private RouteConfigMapper routeConfigMapper; Override public FluxRouteDefinition getRouteDefinitions() { ListRouteConfigDO configs routeConfigMapper.selectAll(); return Flux.fromIterable(configs.stream() .map(config - { RouteDefinition definition new RouteDefinition(); definition.setId(config.getRouteId()); definition.setUri(URI.create(config.getUri())); definition.setPredicates(parsePredicates(config.getPredicates())); definition.setFilters(parseFilters(config.getFilters())); return definition; }) .collect(Collectors.toList())); } Override public MonoVoid save(MonoRouteDefinition route) { return route.map(def - { // 将RouteDefinition转换为数据库对象并保存 RouteConfigDO configDO convertToDO(def); routeConfigMapper.insertOrUpdate(configDO); return def; }).then(); } Override public MonoVoid delete(MonoString routeId) { return routeId.map(id - { routeConfigMapper.deleteByRouteId(id); return id; }).then(); } }保存或删除路由后记得发布RefreshRoutesEventapplicationEventPublisher.publishEvent(new RefreshRoutesEvent(this));这个方案的优点是路由完全可控支持后台配置界面缺点是你要自己处理缓存、并发、异常回滚等问题。我建议如果团队没有专门的网关平台先用Nacos配置中心等路由数量上百条、需要版本管理时再上自定义存储。5. 一次真实的配置排查从请求异常到定位根因的完整链路5.1 现象描述所有请求都502有次接到告警网关转发全部返回502 Bad Gateway。从调用方视角看所有接口直接不可用。查Gateway日志发现大量ConnectTimeoutException和500 Bad Gateway。我的排查链路是先确认路由有没有匹配打开Gateway的DEBUG日志查看RoutingFilter是否打印了匹配到的routeId确认匹配到了再看转发目标地址指向哪里用telnet或nc测试目标地址端口是否通不通就查后端服务通了就看服务自身响应结果发现后端服务所在机器负载过高TCP连接超过connect-timeout默认值这个默认值在不同版本有差异老版本可能只有几秒触发了Gateway的快速失败直接把上游错误转换成502返回。5.2 超时参数的正确配置Gateway侧有两个超时参数必须理解spring: cloud: gateway: httpclient: connect-timeout: 3000 response-timeout: 10sconnect-timeout是建立TCP连接的超时时间单位毫秒response-timeout是等待下游响应整个过程的超时可以用Duration格式。实战中建议connect-timeout不要设太大否则下游网络故障时网关线程会被大量占用。response-timeout按业务接口的最长可接受延迟来设一般5到10秒比较合理。5.3 502与503在不同场景下的含义很多人遇到502就一股脑查下游服务其实在Gateway场景下要区分状态码触发场景排查重点502 Bad Gateway下游连接失败、响应格式错误、上游提前断开网络连通性、下游服务存活状态503 Service Unavailable路由匹配不到、服务实例数为0、熔断降级触发路由配置、注册中心实例列表、熔断器状态504 Gateway Timeout下游响应超过response-timeout下游接口性能、超时配置注意到热搜词里有“unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses”这类报错这通常出现在本地调试AI网关或代码生成服务时本质上是本地服务未被正确启动比如127.0.0.1:15721这个端口的进程挂了或者根本没起。这类问题优先检查目标进程是否存活不要一开始就去扒网关配置。5.4 验证路由配置的小工具实际联调过程中我习惯用curl加verbose模式来避开浏览器缓存和代理干扰curl -v http://gateway-host:8080/api/order/list然后看关键输出 HTTP/1.1 200 OK X-Forwarded-Host: gateway-host X-Forwarded-Port: 8080如果响应头里有这些说明请求确实经过了Gateway。如果返回404大概率是StripPrefix配错如果返回503去查路由是否匹配到如果返回502去查下游连通性。6. 几个高频坑位与相对省心的处理方案6.1 StripPrefix与RewritePath混用的路径混乱问题这是问得最多的一类问题。请求/api/order/list配置了StripPrefix1转发后变成/order/list。如果再叠加RewritePath/api/(.*), /orders/$1你会发现规则根本不会命中因为此时路径已经变成/order/list不再以/api/开头。处理建议同一路由尽量只使用一种路径修改方案。如果确实需要同时用比如先统一去前缀、再做正则改写一定要按照执行顺序调整匹配表达式。写在后面的过滤器操作的是前面过滤器处理过的路径。6.2 网关层面的跨域重复配置如果下游服务自己也配了CORSGateway再配一遍CORS就会出现重复响应头问题。之前碰到过浏览器报“The Access-Control-Allow-Origin header contains multiple values”就是Gateway加了一层CORS后端又加了一层。建议CORS在网关统一处理后端服务关闭CORS。如果后端无法改配置Gateway侧用DedupeResponseHeader去重filters: - DedupeResponseHeaderAccess-Control-Allow-Origin Access-Control-Allow-Credentials, RETAIN_FIRST6.3 全局过滤器对不同路由的影响用GlobalFilter做鉴权、日志、灰度标记时一定注意它作用于所有路由。有时候某条路由响应异常查下来不是路由本身的问题而是全局过滤器里抛了异常。我的习惯是全局过滤器只做必要的事情鉴权、链路追踪、通用请求头注入其它业务逻辑尽可能下沉到具体路由的GatewayFilter里。这样排查问题时路由维度比全局维度清晰得多。6.4 大文件上传时的超时设置网关默认对请求体有大小限制且默认的响应超时对长时间上传任务不友好。上传场景需要单独调大这些参数同时注意Nginx层如果有也要同步调整缓冲和时间限制。只调Gateway不调Nginx请求还是会在前面被拦断。spring: codec: max-in-memory-size: 10MB cloud: gateway: httpclient: response-timeout: 60s6.5 多环境配置管理的建议路由配置在dev、test、prod环境之间差异不小。建议用配置中心的能力做环境隔离而不是把环境判断逻辑写到代码里。Nacos中配置Data ID按环境命名比如gateway-routes-dev.yml、gateway-routes-prod.yml通过spring.cloud.nacos.config.shared-configs引入对应环境的配置文件。注意一点配置文件中的路由定义是增量覆盖还是整体替换取决于你存储路由定义的方式。如果是yml整体读取一条路由的新增会影响所有路由所以改动前先确认环境。7. 最后聊点实在的配置习惯生产环境用了很久Gateway之后我的体会是路由配置最重要的不是会用哪些参数而是变更可追溯、影响可控制。目前比较稳妥的落地组合是常规路由走配置中心发布流程走审批和标签隔离特别复杂的交互走自定义RouteDefinitionRepository并给管理端加上操作审计。Gateway本身就是流量入口越到后面越会发现路由配置能力直接决定了网关平台的交付效率。如果你刚开始接触Gateway建议先搭建一个最小环境用yml把一条Path路由从请求到转发的链路走通再加上lb://模式对接注册中心。上手之后再逐步引入过滤器、限流、熔断每种能力都单独验证别一次性配太多。等路由表超过20条再考虑上配置中心或动态管理否则只会给自己增加运维负担。