Spring Cloud Gateway：路由配置基础

服务多了以后，每个调用方都直接访问各个服务的地址，鉴权、限流、灰度这些横切逻辑就无处安放。Spring Cloud Gateway 作为统一流量入口，负责"把请求路由到正确的服务"，是微服务架构的前门。本章讲清路由配置的核心三要素，先让请求能按规则转发到目标服务。

网关在整个体系中的位置

网关位于客户端与后端服务之间：外部请求先到网关，网关完成路由、过滤（鉴权、限流、跨域等）后再把请求转发给具体的微服务，微服务之间的内部调用则不经过网关。因此网关是横切能力的天然落点（第 09、10、21 章都会用到），也是安全边界的第一道防线。

实现选型：反应式为主，MVC 为补充

Spring Cloud Gateway 默认实现基于 WebFlux 反应式栈（Netty），吞吐高、资源占用低，但它运行在非 Servlet 环境，工程里不要同时引入 spring-boot-starter-web，否则会冲突。从 2024.0 版本起，官方还提供了基于 Spring MVC（Servlet 栈）的网关模块，便于沿用既有 MVC 基础设施的团队平滑迁移，两类模块的路由模型基本一致，具体依赖坐标以官方文档为准。本教程以反应式版本为主线。

三个核心概念

路由（Route）：一条转发规则，包含 id、目标 uri、一组谓词与过滤器。谓词（Predicate）：匹配条件，决定"什么请求命中这条路由"，例如路径以 /api/user 开头。过滤器（Filter）：请求转发前后对请求/响应做加工，例如改写路径、加请求头（第 09 章详述）。

第一个路由配置

引入依赖 spring-cloud-starter-gateway 与 spring-cloud-starter-loadbalancer 后，在网关工程的 application.yml 中配置：

spring:
  cloud:
    gateway:
      routes:
        - id: user-route
          uri: lb://user-service        # 按服务名转发，lb 交给 LoadBalancer
          predicates:
            - Path=/api/user/**
          filters:
            - StripPrefix=1             # 去掉 /api 前缀再转发
        - id: order-route
          uri: lb://order-service
          predicates:
            - Path=/api/order/**
          filters:
            - StripPrefix=1
server:
  port: 9000

启动网关与两个服务后，请求 http://localhost:9000/api/user/1 会命中 user-route：谓词匹配路径 → StripPrefix 把 /api 去掉 → 转发到 user-service 的 /user/1。这就是网关最基础的用法。uri 还可以直接写 http://localhost:8081 指向固定地址，但微服务场景应优先 lb:// 服务名，才能享受注册与负载均衡。

常用谓词速览

Path 是最常用的，此外还有 Method（限定 HTTP 方法）、Header（按请求头匹配）、Query（按查询参数）、Cookie、Host（按域名），以及时间类谓词 After/Before/Between（可用于发布窗口控制、灰度放量）。谓词之间是"与"关系，需要"或"逻辑时拆成多条路由或利用路由顺序，具体组合能力以官方文档为准。

Java 方式等价配置

路由也可以用 RouteLocator Bean 声明，适合需要复杂逻辑或动态拼接的场景：

@Bean
RouteLocator customRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("user-route", r -> r.path("/api/user/**")
                .filters(f -> f.stripPrefix(1))
                .uri("lb://user-service"))
        .build();
}

验证与排障

路由不生效时先做三件事：确认目标服务已注册且网关能解析服务名（网关需引入 discovery 客户端依赖）；用网关日志或 Actuator 的 gateway 端点查看路由表（打开 actuator 的 gateway 相关端点后访问 /actuator/gateway/routes）；检查谓词写错导致 404——404 往往不是"服务没起来"而是"没有路由命中"，注意区分。

小结

路由 = 谓词匹配 + 过滤加工 + 转发目标，掌握 Path/StripPrefix/lb:// 三者就能搭起网关骨架。真正的网关威力在过滤器：统一加头、鉴权、限流全靠它，接下来的三章分别讲过滤器体系、跨域与限流。