Spring Cloud Gateway 负责统一接收外部请求并根据路由规则将请求转发到对应的后端服务。实际开发中一个非常典型的问题是外部请求地址中包含/ai、/user等服务前缀而后端 Controller 中却没有这些前缀。这个差异主要由 Path Predicate 与 StripPrefix Filter 共同完成。理解二者的职责和执行顺序可以解决大部分网关路径配置问题。一、Gateway 路由中的路径处理机制先看一个典型配置spring: cloud: gateway: routes: - id: ai-route uri: lb://ai-service predicates: - Path/ai/** # 匹配以 /ai/ 开头的请求路径 filters: - StripPrefix1 # 转发前删除路径中的第一段 /ai假设客户端访问/api.example.com/ai/chat/stream请求进入 Gateway 后首先由Path/ai/**判断这条请求是否属于当前路由。匹配成功以后StripPrefix1再删除路径中的第一段/ai【先匹配再删除匹配前缀】最终转发给ai-service的实际路径变成/chat/stream因此下游 Controller 只需要定义GetMapping(/chat/stream) // 下游 Controller 无需再写 /ai 前缀无需再额外写/ai。这段配置体现了两个连续步骤Predicate 决定请求进入哪条 RouteFilter 决定请求在转发之前怎样变化。Path 与 StripPrefix 分别位于这两个阶段。二、Path Predicate 的路由匹配职责Spring Cloud Gateway 中一条 Route 可以理解为一条完整的转发规则。Route 通常包含目标 URI、Predicate 和 Filter。Predicate 负责判断当前请求是否满足这条路由的进入条件。Path是最常见的 Predicate 之一predicates: - Path/ai/** # 请求路径以 /ai/ 开头时匹配当前路由这里的含义是请求路径以/ai/开头时当前 Route 才会被匹配。类似地可以分别定义/ai/** → AI 服务 # 路径前缀分流 /user/** → 用户服务 /order/** → 订单服务这样前端只需要访问一个统一域名Gateway 根据路径前缀完成服务分流。Path 的作用到这里就结束了。它负责的是“选择”不会主动修改原始请求路径。如果只配置- Path/ai/** # 只做匹配不修改原始请求路径客户端请求/ai/chat/stream后下游默认仍然会收到/ai/chat/stream。因此如果 Controller 本身就是GetMapping(/ai/chat/stream)那么只配置 Path 完全可以正常工作。三、StripPrefix Filter 的路径改写职责很多项目希望/ai只承担网关层的服务标识下游服务内部仍然使用更简洁的业务路径。这时就需要 StripPrefix。官方定义中StripPrefix 接收一个parts参数用于指定在请求转发到下游之前删除多少个路径段。例如filters: - StripPrefix1对于/ai/chat/stream路径可以拆成ai / chat / stream删除第一段之后得到/chat/stream如果配置StripPrefix2那么前两段都会被删除最终只剩/stream因此StripPrefix的核心并不是“寻找哪个服务”而是在 Route 已经确定以后对即将发送给下游的 URL 做一次路径转换。这也是 Path 与 StripPrefix 最重要的区别Path → 判断请求是否进入当前路由 StripPrefix → 修改进入路由后的请求路径二者解决的是前后两个不同阶段的问题。四、组合配置的核心价值Path 与 StripPrefix 经常组合使用是因为微服务系统通常同时存在两套路由语义。对外 API 需要明确服务边界例如/api/v1/ai/chat /api/v1/user/profile /api/v1/order/list这些路径需要让 Gateway 能够快速判断请求属于哪个业务模块。服务内部则更关注自身业务不一定希望 Controller 长期携带/api/v1/ai这一类网关前缀。例如 AI Service 内部可能只维护/chat /rag /agent此时 Gateway 可以负责外部路径与内部路径之间的适配外部 /api/v1/ai/chat Gateway Path/api/v1/ai/** StripPrefix3 内部 /chat这样做的主要价值是降低外部 API 与内部服务结构之间的耦合。未来 AI 能力进一步拆分为 Chat Service、RAG Service 和 Agent Service 时外部地址仍然可以保持稳定只需要调整 Gateway 的路由关系。前端无需跟随内部微服务结构反复修改接口地址。【稳定的对外API接口可接受变动的内部业务结构】因此Path StripPrefix 可以理解为一种外部路径与内部服务路径之间的适配机制。五、路径异常的定位方法Path 和 StripPrefix 配置错误时最常见的结果是 404。排查时可以依次确认三个路径。第一步记录客户端真正发送的原始路径例如/ai/chat/stream第二步根据 Gateway 配置计算 Filter 执行后的路径。例如Path/ai/** StripPrefix1 最终路径 /chat/stream第三步检查下游 Controller 的真实映射GetMapping(/chat/stream)只要把这三者放在一起大部分问题都可以直接发现。如果 Path 本身没有匹配成功请求不会进入目标 Route如果 StripPrefix 删除数量错误请求会被转发到错误路径如果前两步都正确则需要继续检查 Controller Mapping、Context Path 等下游配置。相比直接修改配置反复测试先明确“原始路径—网关处理后路径—Controller 路径”这三个值定位效率会更高。六、总结Path Predicate 与 StripPrefix Filter 是 Spring Cloud Gateway 中两个职责非常清晰的路径组件。Path 负责根据请求地址判断应该进入哪一条 RouteStripPrefix 负责在路由命中以后删除指定数量的路径段。二者组合使用时可以让外部 API 保持统一、清晰的服务前缀同时让内部 Controller 保留更简洁的业务路径。整个设计的核心可以归纳为外部请求 ↓ Path选择目标 Route ↓ StripPrefix调整请求路径 ↓ 下游 Controller理解这条路径以后再遇到 Gateway 前缀、Controller 映射和 404 问题就可以直接沿请求路径逐层判断而不需要依赖对配置项的机械记忆。参考资料Spring Cloud Gateway 官方文档StripPrefix GatewayFilter FactorySpring Cloud Gateway :: Spring Cloud GatewaySpring Cloud Gateway 官方文档Route Predicate FactoriesSpring Cloud Gateway :: Spring Cloud Gateway