路由匹配优先级
更新时间：2026-05-06
概述
当一个请求到达 AI 原生网关时，网关会逐条遍历该实例下的路由匹配规则，找出第一条命中的规则并将请求转发到对应的目标服务。匹配规则可以归纳为三条：
- 路由按创建时间排序，先创建的优先级更高。
- 请求依次匹配，命中即停——只要前面的路由匹配上，后续的路由不会再被检查。
- 路径之外的匹配项（请求方法、请求头、请求参数）以 AND 关系叠加——每多一项配置就多一个必须满足的条件，请求若不带对应字段则该路由不会命中。
匹配规则
匹配过程按以下顺序进行：
- 网关从该实例下的全部路由中，按创建时间从早到晚遍历每一条路由。
-
对每条路由，依次检查请求是否同时满足该路由的所有匹配项：
匹配项 判定逻辑 路径（Path） 按所配置的匹配方式判定： - 前缀匹配：请求路径以路由配置的路径开头时即视为匹配。
- 精确匹配：请求路径与路由配置的路径完全相同时视为匹配。
- 正则匹配：请求路径满足路由配置的正则表达式时视为匹配。
请求方法（Method） 请求的 HTTP Method 在路由配置的 Method 列表中，视为匹配。 请求头（Header） 路由配置的所有 Header 条件均命中时（AND 关系），视为匹配。任一条件不满足即视为该路由不命中。 请求参数（Query） 路由配置的所有 Query 条件均命中时（AND 关系），视为匹配。任一条件不满足即视为该路由不命中。 - 第一条同时满足所有匹配项的路由即为命中路由，请求按其配置进行转发；后续路由不再参与本次匹配。
- 若所有路由都未命中，网关返回 404。
重要
当前暂不支持手动配置路由优先级（即没有 0–100 的自定义优先级数值），优先级完全由创建时间决定。如需调整匹配顺序，请通过调整路由的创建顺序或细化匹配条件（增加 Header / Query）实现。
场景说明
理解优先级规则的关键，是分清「路径相同」与「路径不同」两种情况下路由如何相互影响。
场景一：路径不同
不同路由配置的路径不存在重叠时，请求各自命中对应路由，互不干扰，通常无需额外配置 Header 或 Query。
配置示例：
| 路由 | 路径配置 | 目标服务 |
|---|---|---|
| 路由 A | 精确匹配 /v1/chat/completions |
对话服务 |
| 路由 B | 精确匹配 /v1/embeddings |
向量服务 |
匹配结果：
- 请求
/v1/chat/completions→ 命中路由 A，转发到对话服务。 - 请求
/v1/embeddings→ 命中路由 B，转发到向量服务。
边界情况：路径存在包含关系
若使用前缀匹配，且不同路由的路径存在包含关系（例如路由 X 配置
/v1前缀匹配，路由 Y 配置/v1/chat前缀匹配），由于按创建时间排序，先创建的更宽泛路径（/v1）会先命中，导致/v1/chat路由永远不会被匹配到。此时建议先创建更具体的路径（
/v1/chat），或通过 Header / Query 在更具体的路由上加 AND 条件以避免被前一条吞掉。
场景二：路径相同
多条路由配置完全相同的路径时，必须为每条路由额外加上 Header 或 Query 条件进行区分；否则先创建的路由会"吃掉"全部流量，后创建的精确路由永远不会命中。
正确示例：
| 创建顺序 | 路由 | 路径配置 | 额外条件 | 目标服务 |
|---|---|---|---|---|
| 1（先建） | 路由 A | 精确匹配 /v1/chat/completions |
Header X-Model = gpt-4 |
GPT-4 服务 |
| 2（后建） | 路由 B | 精确匹配 /v1/chat/completions |
Header X-Model = claude |
Claude 服务 |
匹配结果：
- 请求带
X-Model: gpt-4→ 命中路由 A，转发到 GPT-4 服务。 - 请求带
X-Model: claude→ 路由 A 不匹配（Header 条件不满足），继续命中路由 B，转发到 Claude 服务。 - 请求未带
X-Model→ 路由 A、B 均不匹配，网关返回 404。
反例（需避免）：
| 创建顺序 | 路由 | 路径配置 | 额外条件 |
|---|---|---|---|
| 1（先建） | 路由 B | 精确匹配 /v1/chat/completions |
未配置 Header |
| 2（后建） | 路由 A | 精确匹配 /v1/chat/completions |
Header X-Model = gpt-4 |
问题：所有请求都会被先创建的路由 B 先命中（B 没有 Header 限制，只看路径），导致路由 A 永远不生效。看起来像"Header 匹配没生效"，本质是路由顺序与匹配逻辑不匹配导致的。
最佳实践
为避免线上出现"路由配了但不生效"的常见问题，建议：
- 路径完全相同的多条路由：必须为每条都配置不同的 Header 或 Query 条件，并确保所有客户端请求一定会带上区分字段。
- 路径存在包含关系：将更具体的路径先于宽泛路径创建，或在更具体路径上叠加 Header / Query 进一步区分。
- 新增路由时谨慎调整顺序：如果新增路由因创建时间靠后无法生效，可考虑删除并重新创建以调整时间排序，或在更早的路由上补充 AND 条件让其"让路"。
- 变更前规划好优先级：在网关上配置多条相似路由前，先梳理路径与额外条件的组合，避免线上出现"看起来像没生效"的问题。
评价此篇文章