概述

当一个请求到达 AI 原生网关时，网关会在该实例下的所有路由中，找出与请求匹配且优先级最高的一条路由，并将请求转发到对应的目标服务；若所有路由都未命中，网关返回 404。

路由匹配优先级逻辑分为 v1、v2 两个版本，按网关实例的创建时间区分：

匹配逻辑版本	适用实例	优先级规则
v2（默认）	2026 年 6 月 12 日（含）之后创建的网关实例默认使用	按路径（Path）> 请求头（Header）> 请求参数（Query）> 创建时间的优先级从高到低依次排序。路由精确度越高，优先级越高。
v1	2026 年 6 月 12 日之前创建的网关实例	按路由创建时间排序，先创建的优先级更高

重要

v1 版本支持切换到 v2 版本，如有需要请 提交工单 联系技术人员处理。

匹配项说明

无论使用哪个版本的匹配逻辑，一条路由的所有匹配项均以 AND 关系 叠加 —— 每多一项配置就多一个必须满足的条件，请求若不带对应字段则该路由不会命中。各匹配项的判定逻辑如下：

匹配项	判定逻辑
路径（Path）	按所配置的匹配方式判定： 精确匹配：请求路径与路由配置的路径完全相同时视为匹配。 前缀匹配：请求路径以路由配置的路径开头时即视为匹配。 正则匹配：请求路径满足路由配置的正则表达式时视为匹配。
请求方法（Method）	请求的 HTTP Method 在路由配置的 Method 列表中，视为匹配。
请求头（Header）	路由配置的所有 Header 条件均命中时（AND 关系），视为匹配。任一条件不满足即视为该路由不命中。
请求参数（Query）	路由配置的所有 Query 条件均命中时（AND 关系），视为匹配。任一条件不满足即视为该路由不命中。

路由匹配优先级（v2）

2026 年 6 月 12 日（含）之后创建的网关实例默认使用

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

1. 根据路径（Path）进行判断：

   • 匹配规则不同时：精确匹配 > 前缀匹配 > 正则匹配。
   • 匹配规则相同时：路径（Path）字符串越长，优先级越高。
2. 根据请求头（Header）的键值对总数进行判断：总数越大，优先级越高。
3. 根据请求参数（Query）的键值对总数进行判断：总数越大，优先级越高。
4. 根据创建时间进行判断：创建时间越早则优先级越高。

路由匹配优先级（v1）

2026 年 6 月 12 日之前创建的网关实例默认使用

存在多条路由规则时，匹配过程按以下顺序进行：

1. 网关从该实例下的全部路由中，按创建时间从早到晚遍历每一条路由。
2. 对每条路由，依次检查请求是否同时满足该路由的所有匹配项（见上文「匹配项说明」）。
3. 第一条同时满足所有匹配项的路由即为命中路由，请求按其配置进行转发；后续路由不再参与本次匹配。
4. 若所有路由都未命中，网关返回 404。

即 v1 逻辑下请求依次匹配，命中即停 —— 只要前面（更早创建）的路由匹配上，后续的路由不会再被检查。

场景说明

理解优先级规则的关键，是分清「路径不同」「匹配方式不同」「路径存在包含关系」与「路径相同」四种情况下路由如何相互影响。

场景一：路径不同且无包含关系

不同路由配置的路径不存在重叠时，请求各自命中对应路由，互不干扰，v1 与 v2 行为一致，通常无需额外配置 Header 或 Query。

配置示例：

路由	路径配置	目标服务
路由 A	精确匹配 /v1/chat/completions	对话服务
路由 B	精确匹配 /v1/embeddings	向量服务

匹配结果：

• 请求 /v1/chat/completions → 命中路由 A，转发到对话服务。
• 请求 /v1/embeddings → 命中路由 B，转发到向量服务。

场景二：路径重叠且匹配方式不同

多条路由可以匹配同一请求路径，但使用了不同的匹配方式时，v2 按精确匹配 > 前缀匹配 > 正则匹配的顺序判定优先级。

配置示例：

路由	路径配置	目标服务
路由 A	精确匹配 /v1/chat/completions	对话服务
路由 B	前缀匹配 /v1	通用服务
路由 C	正则匹配 ^/v1/.*	正则兜底服务

v2 匹配结果：与创建顺序无关。

• 请求 /v1/chat/completions → 三条路由均可匹配，按精确 > 前缀 > 正则，命中路由 A，转发到对话服务。
• 请求 /v1/embeddings → 路由 B、C 可匹配，前缀优先于正则，命中路由 B，转发到通用服务。

v1 匹配结果：不区分匹配方式，完全按创建时间排序。若前缀匹配的路由 B 最早创建，所有 /v1 开头的请求（包括 /v1/chat/completions）都会命中路由 B，路由 A、C 永远不生效。

场景三：路径存在包含关系

例如路由 X 配置 /v1 前缀匹配，路由 Y 配置 /v1/chat 前缀匹配，两个版本行为不同：

• v2：匹配规则相同时路径越长优先级越高，请求 /v1/chat/xxx 会优先命中更具体的路由 Y（/v1/chat），无论创建顺序如何，无需额外处理。
• v1：按创建时间排序，若更宽泛的路由 X（/v1）先创建，会先命中并"吞掉"全部 /v1 开头的流量，导致路由 Y 永远不会被匹配到。此时建议先创建更具体的路径（/v1/chat），或通过 Header / Query 在更具体的路由上增加 AND 条件加以区分。

场景四：路径相同

多条路由配置完全相同的路径时，需要为路由配置 Header 或 Query 条件进行区分。

配置示例：

路由	路径配置	额外条件	目标服务
路由 A	精确匹配 /v1/chat/completions	Header X-Model = gpt-4	GPT-4 服务
路由 B	精确匹配 /v1/chat/completions	Header X-Model = claude	Claude 服务
路由 C	精确匹配 /v1/chat/completions	未配置	默认服务

v2 匹配结果：配置了 Header 的路由 A、B 优先级高于未配置 Header 的路由 C，与创建顺序无关。

• 请求带 X-Model: gpt-4 → 命中路由 A，转发到 GPT-4 服务。
• 请求带 X-Model: claude → 命中路由 B，转发到 Claude 服务。
• 请求未带 X-Model → 路由 A、B 不匹配，命中路由 C，转发到默认服务。

v1 匹配结果：完全取决于创建顺序。若未配置 Header 的路由 C 先创建，所有请求都会被路由 C 先命中（C 只看路径），导致路由 A、B 永远不生效——看起来像"Header 匹配没生效"，本质是路由顺序与匹配逻辑不匹配导致的。v1 逻辑下必须保证带 Header / Query 条件的路由先于无条件的兜底路由创建。

最佳实践

为避免线上出现"路由配了但不生效"的常见问题，建议：

• 优先使用 v2 匹配逻辑：v2 按"更精确者优先"排序，路径包含、Header / Query 区分等场景均无需关心创建顺序，行为更符合直觉。存量 v1 实例如需切换到 v2，请提交工单联系技术人员处理。
• v1 实例注意创建顺序：更具体的路径、带 Header / Query 条件的路由需先于宽泛路由创建；如果新增路由因创建时间靠后无法生效，可考虑删除并重新创建以调整顺序，或在更早的路由上补充 AND 条件让其"让路"。
• 路径完全相同的多条路由：为每条配置不同的 Header 或 Query 条件，并确保客户端请求一定会带上区分字段；如需兜底，可增加一条不带额外条件的同路径路由（v1 实例需最后创建）。