文档中心

API 网关

路由管理

路由概述

API 网关在处理收到的请求时，会按照事先配置的路由规则的优先级逐一进行匹配。本文介绍路由的基本概念、匹配规则等。

什么是路由

路由是 API 网关将客户端请求精准转发到后端服务的核心规则。当客户端请求到网关后，网关将依据路由配置中定义的优先级、路径、请求头、请求参数等信息，把请求按照路由绑定的 Upstream 转发至后端服务，并在转发过程中按照路由策略对请求或响应进行处理。

路由匹配优先级

存在多条路由规则时，按照自定义优先级 > 路径（Path）> 请求头（Header）> 请求参数（Query）> 创建时间的优先级从高到低依次进行排序，详细规则如下：

路由匹配方式

API 网关提供了两种优先级配置方式，创建时间于 2024 年 6 月 14 日前的网关默认使用 v1 版本匹配逻辑，2024 年 6 月 14 日后的网关默认使用 v2 版本匹配逻辑，两种版本的优先级匹配逻辑如下：

版本	优先级逻辑	优点	缺点
v1	按照路由的创建时间来判断优先级。创建时间越早，优先级越高。	逻辑简单，容易上手。	路由精确度低。
v2	按照路由的精确度来判断优先级。精确度越高，优先级越高。	路由精确度高。	逻辑复杂，有一定的理解成本。

注意事项

场景说明

当一个请求可以匹配多个规则时，需要定义这些规则的优先级，防止请求只按照最高精准度进行匹配。

请求场景	路由配置	匹配规则
场景1 /abcd	route1 Path：前缀匹配 /abcd 创建时间：2024-06-13 00:00:00 route2: Path：精准匹配 /abcd 创建时间：2024-06-13 00:00:02 route3: Path：前缀匹配 /abcd Header: x-forward-for 精准匹配 xxx 创建时间：2024-06-13 00:00:03 route4: Path：精准匹配 /abcd Header: x-forward-for 精准匹配 xxx 创建时间：2024-06-13 00:00:04	v1： route1 > route2 v2: route2 > route1
场景2 /abcd Heade：x-forword-for =xxx			v1: route1 > route2 > route3 > route4 v2: route4 > route3 > route2 > route1

仅用作路由生效优先级的说明，实际有且仅有一条路由生效。优先级说明：

场景 1 配置 v2 版本匹配规则：优先匹配 route2。因为精准匹配精准度高于前缀匹配， route2 精准度高于 route1。其中，route3、route4的匹配条件中需要携带有效 header 信息，因此未命中匹配。

路由策略

路由策略是指路由命中后，API 网关在请求转发过程中对请求或响应的处理，一条路由可以同时启用多项路由策略，多项策略间将按照能力协同生效。API 网关当前支持的路由策略如下所示。

策略名称	能力说明
超时策略	设置网关向后端 Upstream 转发请求的最长等待时间，超时后立即返回错误，避免后端慢响应耗尽网关连接资源。
跨域策略	基于 CORS 协议放行跨域请求，控制允许的来源、方法、请求头等。
重写策略	将请求中的路径 Path 改写为转发至该后端服务的实际路径。
重试策略	当 Upstream 后端服务返回特定的状态码时，网关自动按照配置的重试条件和次数进行重试。
流量镜像策略	将命中路由的流量按比例镜像复制到指定的 Upstream，且镜像流量不影响主链路的响应。

最近更新时间：2026.05.28 11:01:58

这个页面对您有帮助吗？

有用

无用