URI匹配与查询：从路径匹配到参数解析的完整避坑指南

做后端和网关这些年，我发现自己大部分时间不是在写业务逻辑，而是在跟 URI 打交道。路由匹配、query 参数解析、路径归一化，这些听起来很基础的东西，恰恰是线上事故的高发区。就拿 URI 匹配与查询这个主题来说，从 Nginx location 怎么命中、Spring 路由怎么匹配，到查询字符串里的加号会不会被解析成空格，每一环都藏着不少坑。前阵子我调试一个接口，明明路由规则看着没问题，可请求就是 404，从下午排查到快下班，最后发现是 query 里一个 + 号被解析成了空格，参数值整个错位，匹配链路上自然就断了。

后来我把这类问题系统梳理了一遍，发现不管是前端路由、后端框架还是网关层，只要是做 URI 匹配与查询，就逃不开几个核心问题：路径怎么匹配、参数怎么解析、编码怎么统一、冲突怎么处理。今天就把这套完整链路从头到尾拆开聊一聊，里面既有基础概念，也有我第一次踩坑时的完整记录，希望能帮正在跟路由和查询参数较劲的朋友省点时间。

1. 先把概念理清：URL、URI 和 URN，别再混着叫了

1.1 URI 的标准长相与组成

很多人在日常开发里把 URL 和 URI 当成一回事，这其实没什么大问题，但一旦深入到路由匹配和参数解析的细节，你迟早会碰上一个概念边界模糊导致的 bug。URI（Uniform Resource Identifier）其实是一个总称，URL（Uniform Resource Locator）和 URN（Uniform Resource Name）是它的两种具体形态。我们日常写的 https://api.example.com/users/123?page=1&size=20 严格来说是一个 URL，但说它是 URI 也完全正确，因为 URL 本身就是 URI 的子集。

URI 的标准结构在 RFC 3986 里定义得很清楚，大概是这个样子：

text复制URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment]

拆开细看其实并不复杂。以 https://user:pass@api.example.com:8080/users/123?page=1&size=20#top 为例，https 是 scheme（协议方案），user:pass 是用户信息，api.example.com 是 host（主机名），8080 是端口，/users/123 是 path（路径），page=1&size=20 是 query（查询串），top 是 fragment（片段）。fragment 比较特殊，它不会发送到服务器端，纯属浏览器端锚点定位用的，所以后端拿到的 URI 实际上只有 scheme、authority、path 和 query 这几部分。

这里有一个很关键的认知：在做路由匹配时，绝大多数框架和网关默认只关心 path 部分，query 参数是不参与路径匹配的。也就是说，/users/123?page=1 和 /users/123?page=2 会命中同一条路由规则，但如果你在网关层写了一个“完整 URI 匹配”的策略，那么 query 不同就会被当成不同的请求，这就是很多网关路由事故的根源之一。

1.2 为什么“匹配”之前必须先明确边界

我见过不少线上事故，根源在于匹配的是“完整 URI”还是“路径”，没有统一规范。比如 Nginx 的 $request_uri 是包含 query 的完整原始 URI，而 $uri 则是不带 query、已经解码归一的路径。如果你在配置里搞混了这两个变量，那么写出来的匹配规则可能看起来对，实际运行时却完全不是你想的那样。

具体来说，$request_uri 永远保持客户端请求时的原始样子，不做任何解码和归一化；而 $uri 是 Nginx 内部经过解码、路径压缩、处理 ../ 等操作后的结果。举个例子，客户端请求 GET /static/../api/user?id=1 HTTP/1.1，此时 $request_uri 是 /static/../api/user?id=1，而 $uri 可能已经变成了 /api/user。如果你在 location 匹配里用了 $request_uri，那匹配的是带 .. 的原始路径；如果用 $uri，匹配的是归一化后的路径。两个结果完全不同，配置失误会导致路径穿越风险或路由命中的不确定性。

所以做匹配之前，一定要先问清楚三个问题：匹配对象是什么（完整 URI 还是 path）、匹配前是否做了解码、是否做了路径归一化。这三点的组合，基本决定了匹配行为的正确性。我在设计后端接口时，一般会定一条硬性规范：路由匹配一律基于 path 部分，query 只在业务代码里解析，不参与路由判断。这样既简单又不容易出错。

1.3 匹配问题在工程里的真实分布

URI 匹配与查询的问题并不是某一个环节特有的，它在一条完整请求链路里至少会出现三四次：客户端路由、反向代理、网关路由、后端框架路由，每一层都在做匹配，每一层对 URI 的“理解”可能还不太一样。

前端路由匹配的是路径，SPA 应用里由 history API 接管；Nginx 这类反向代理在 location 阶段做路径前缀或正则匹配；微服务网关（比如 Spring Cloud Gateway、Kong）通常用路径断言把请求转发到具体服务；最后到了后端框架，Spring MVC、Flask、Express 又会做一次路径映射和参数绑定。任何一层的匹配逻辑出错，最终表现都是 404 或者 502，但真正出问题的地方可能藏在很深的某一层。

我通常会把请求链路里每一层的匹配规则都打印到日志里，用真实请求走一遍，看看到底是在哪一层断掉的。这个方法听着土，但定位效率非常高，比对着配置文档猜快得多。

2. 路径匹配的几种姿势：从精确匹配到参数化路由

2.1 精确匹配与静态映射：最简单也最容易翻车

精确匹配是最直观的路径匹配方式，就是拿请求路径和配置的路径做字符串相等比较。比如 Nginx 里的 location = /api/v1/health，只有请求路径完全等于 /api/v1/health 时才会命中，/api/v1/health/、/api/v1/health?x=1 都不会匹配成功（query 不参与判断）。

为什么说它最容易翻车呢？因为字符串比较有个隐藏的“编辑器陷阱”——末尾斜杠。我见过一个非常典型的案例：后端服务注册的健康检查路径是 /health，但运维在负载均衡里把健康检查配置成了 /health/，多了一个斜杠，精确匹配永远命中不了，健康检查持续失败，服务被摘流，业务方一脸懵。

在 Spring MVC 里精确匹配通常写法是：

java复制@GetMapping("/health")
public String health() {
    return "ok";
}

这样配置之后，/health 能命中，/health/ 默认也能命中（Spring 的末尾斜杠匹配默认是开启的），但这恰恰又带来另一个问题：不同框架对末尾斜杠的处理不一致。Nginx 精确匹配区分末尾斜杠，Spring 默认不区分，如果两者在链路里共存，就可能出现网关层通不过、后端却能通过的情况。

所以我的建议是：精确匹配的场景尽量少用，它看着简单，但对边界条件要求极高。真正适合精确匹配的往往只有那些固定的静态端点，比如健康检查、版本号接口、固定的跳转地址。业务接口应该用更灵活的参数化匹配。

2.2 前缀匹配与 Ant 风格的 Path Pattern

前缀匹配是生产环境里应用最广的一种路径匹配方式。Nginx 的 location /api/ 就是一种前缀匹配，只要请求路径以 /api/ 开头，就会进入这个 location。前缀匹配的好处是直观、性能好，不需要复杂的字符串分析，代价是边界容易模糊，比如 location /api 会同时匹配 /api 和 /api/v1/user，而 location /api/ 不会匹配 /api 本身（缺少末尾斜杠）。

Spring 框架里的 AntPathMatcher 更复杂一些，支持 ?、*、** 三种通配符，以及 {变量} 形式的路径变量。举个例子：

java复制@GetMapping("/api/**/user")
public String getUser() {
    return "user";
}

这里的 ** 可以匹配任意多级路径，/api/v1/user、/api/v1/v2/user 都能命中。而单个 * 只能匹配一级路径段，/api/*/user 只能命中 /api/v1/user，无法命中 /api/v1/v2/user。这个语义差异在写规则时很容易搞混，尤其是从 Nginx 切到 Spring，或者反过来，通配符含义完全不同。

我在写通用匹配规则时有一个习惯：前缀匹配的边界一定带上末尾斜杠，比如 /api/v1/ 而不是 /api/v1，这样就能避免匹配到 /api/v1abc 这类路径。这个细节很多人看不起，觉得无所谓，但一旦接口路径多起来，这种边界模糊会导致请求被错误路由到不需要 token 校验的接口上，形成越权风险。

2.3 正则匹配：灵活背后的三重风险

当前缀匹配和通配符匹配都不够用的时候，就该上正则了。Nginx 里用 location ~ 表示区分大小写的正则匹配，location ~* 表示不区分大小写的正则匹配。比如拦截所有数字 ID 的用户接口，可以写：

nginx复制location ~ ^/api/users/(\d+)/orders$ {
    proxy_pass http://backend;
}

用正则做匹配最大的好处是表达能力强，一条规则可以涵盖多种路径形态，但它的代价也很明显。第一重风险是性能，正则表达式在极端情况下可能出现灾难性回溯，CPU 被打满，整个服务响应变慢；第二重风险是可读性，几个月后回来看一条复杂正则，连写的人都要重新理解一遍；第三重风险是优先级，正则匹配和前缀匹配混合使用时，Nginx 有一套特殊的匹配顺序规则，一旦搞错，匹配结果就可能不是你以为的那条规则。

关于 Nginx location 匹配顺序，官方文档有个明确的决策表，我自己的理解可以简化为：先精确匹配（=），然后是 ^~ 前缀匹配（命中后不再进行正则检查），再按顺序检查正则，最后是普通前缀匹配（最长匹配原则）。所以如果你写了一个 location ~ 正则匹配，但前面的 ^~ 前缀已经命中，那么正则根本不会执行。这个坑我踩过，那次线上配置看起来没问题，但始终命中不了预期的正则规则，后来翻文档才发现是 ^~ 在“吃”路由。

2.4 参数化匹配：把路径变成变量

参数化匹配是现代后端框架的标准能力，它把路径中的某一段声明成变量，在业务代码里直接获取。比如 Spring Boot 里的写法：

java复制@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(@PathVariable Long userId,
                      @PathVariable Long orderId) {
    return orderService.findOrder(userId, orderId);
}

Flask 的写法也类似：

python复制@app.route('/users/<int:user_id>/orders/<int:order_id>')
def get_order(user_id, order_id):
    return order_service.find_order(user_id, order_id)

参数化匹配和正则匹配本质上是一回事，只是框架帮你封装了变量提取。但你有没有想过，/users/123/orders/456 和 /users/abc/orders/xyz 都能匹配上面那条规则，参数类型转换会在框架层报错，返回一个 400 而不是 404。这个行为差异值得注意，因为从客户端视角看，它请求了一个不存在的资源，期望的是 404，但服务端把值类型校验放在了路径匹配之后，返回的是参数错误。

参数化匹配还有一个性能上的小技巧：路径参数传递到业务层后，如果要作为数据库查询条件，一定要用参数化 SQL，绝对不能拼字符串，否则 userId 传一个 1 or 1=1 进来就是经典的 SQL 注入点。这类问题在 URI 匹配与查询里并不少见，因为路径参数和 query 参数都是直接从 URL 上读来的，安全性天然比 POST body 差一截。

2.5 匹配思想的跨界联系：规则引擎与模板匹配

聊到匹配，其实不止是 URI 路径。像规则引擎 Drools 里的 Rete 算法，本质就是在做事实与规则的匹配，它把规则条件拆成网络节点，让事实在节点上流动复用，避免重复计算；图像识别的 Halcon 模板匹配，也是在模板图像和目标图像之间做相似度匹配。这些看似风马牛不相及的领域，底层的匹配思想是一致的：定义好模式空间，然后找出所有符合模式的目标。

路径匹配也是一样，前端路由、网关路由、后端路由本质上都是“把请求映射到处理器”的规则系统。理解这一点对架构设计很有帮助，你会发现当你给 API 网关写一堆路由规则时，你其实是在维护一个轻量级的规则引擎。规则越多，规则之间越可能冲突，优先级设计就越重要。这也是为什么我在后面专门讲匹配优先级和冲突排查，那是所有匹配系统里最容易出事故的地方。

3. 查询参数的解析：query string 没有你想的那么简单

3.1 查询字符串的编码规则与反直觉细节

query string（查询字符串）是 URI 中 ? 之后的部分，结构上是一组键值对，用 & 分隔。标准格式长这样：

text复制?q=keyword&page=1&size=20&sort=desc

但这里的键和值并不是普普通通的文本，它们经过了一套编码规则。RFC 3986 规定 URI 里只允许 ASCII 字符集的部分字符直接出现，中文、空格、特殊符号都必须做百分号编码（percent-encoding），也就是 %XX 形式。比如中文“查询”的 UTF-8 编码是 E6 9F A5 E8 AF A2，所以在 URL 里一般显示成 %E6%9F%A5%E8%AF%A2。

这里有一个反直觉的细节：HTML 表单的 application/x-www-form-urlencoded 编码规则中，空格除了可以编码成 %20，还可以编码成 +。很多解析库在处理 query string 时，会把 + 也当作空格解码。这意味着 ?q=hello+world 解析出来可能是 q=hello world（空格）。这个问题在 Java 的 Servlet 参数解析和 JavaScript 的 URLSearchParams 里都做了处理，但如果你手写一个 split("&") 再 split("=") 然后 decodeURIComponent，你就会发现 + 解不出来，直接被当成了普通加号。

我踩过的一个真实坑就是这个：前端把用户输入的邮箱 a+b@example.com 用 URLSearchParams 编码成了 a%2Bb%40example.com，网关层正常解码后传给后端，但后端是另一个老项目，用 split("&") 手动解析，%2B 被解码成 +，结果到了某个参数解析器里又被当作空格截断了，整条数据链就断了。这个问题从现象到根因，不排查到那一层根本看不出来。

3.2 解析参数时的策略选择：单值、多值与嵌套

query string 的语法看起来很简单，但设计一个健壮的解析策略要处理不少边界情况。比如同一个 key 出现多次，应该怎么处理？

text复制?tag=java&tag=web&tag=cloud

一种策略是取最后一个值，常见于很多后端框架的默认行为；另一种策略是解析成数组，比如 JavaScript 的 URLSearchParams 的 getAll() 方法就是返回所有值。Java 的 Servlet 规范里，getParameter("tag") 返回第一个值，getParameterValues("tag") 返回数组。如果你在做网关层参数透传，一定要明确策略，否则可能把用户的多选标签参数从数组变成单值，业务数据直接丢失。

还有一种更极端的嵌套形式，PHP 风格的参数命名：

text复制?filter[name]=tom&filter[age]=18

这种写法在 JavaScript 和 Java 的原生解析库里并不直接支持，需要自己写解析逻辑来还原嵌套对象。做网关或 BFF 层时遇到这种参数，用框架自带的解析工具根本无法正确处理，必须针对业务预设方案。

我的建议是：如果项目是内部系统，约定参数格式一律扁平化，嵌套结构走 JSON body；如果是兼容外部系统的网关，那么对 query string 的解析要单独写工具类或者引成熟的库，比如 Python 的 urllib.parse.parse_qs、JavaScript 的 qs 库，千万不要自己拿 split 硬解。

3.3 参数安全：从解码到传给后端的一条红线

query 参数的安全性是一个老生常谈但永远不能忽略的话题。最常见的两类风险，一个是 SQL 注入，一个是路径穿越。SQL 注入的场景我就不展开了，反正记住一条铁律：从 URL 里取到的任何参数，绝对禁止直接拼接 SQL。另一个容易忽略的是路径穿越，比如一个下载接口：

text复制GET /download?file=../../etc/passwd

如果后端直接把 file 参数值和下载目录拼接成文件路径，那么用户就可以读到任意文件。Java 和 Python 里都有 normalize 类似的方法来做路径标准化，但在做路径检查前，你要先意识到 query 参数本身就可能携带恶意内容，不能因为对方来自 URL 参数就觉得“无非是字符串”。

query 参数还经常被用来做缓存键。一个常见的反模式是把原始 query string 直接当缓存键，比如：

javascript复制const cacheKey = req.url; // 包含 query string

这样看似没问题，但 ?a=1&b=2 和 ?b=2&a=1 会生成两个不同的缓存键，缓存命中率下降，而且如果参数里带着无意义的 _t=时间戳，每次请求都不同，缓存就彻底失效了。更危险的是，如果缓存键没做签名校验，用户可以通过修改参数值来破坏缓存内容。比如 CDN 缓存一个 HTML 页面时，完全可以通过在 URL 后面加参数来绕过缓存，直接回源。

我在做缓存键设计时有一条规范：把 query 参数按 key 排序后拼接，剔除业务无关的参数（比如埋点参数 utm_source），只保留真正影响内容的参数。这样既能提高缓存命中率，也能避免参数顺序引起的垃圾缓存。

3.4 查询参数与匹配的联动：缓存键和日志跟踪

前面说了路径匹配和参数解析，这里再补一个它们联动的点：日志跟踪。当你的服务收到一个请求，排查问题时你首先想要的是完整的 URI，包括 path 和 query。但很多框架默认的访问日志只打印 method 和 path，不打印 query。这就导致一个问题：同一个路径，因为 query 参数不同，行为可能完全不同，但日志里看不到 query，没法定位。

我自己的做法是在网关层统一记录 $request_uri 完整 URI，同时在日志里输出请求 ID（traceId），下游所有服务通过请求 ID 串联。这样哪怕一个请求要经过四五个服务，我也可以通过链路把每一层的匹配结果和参数解析结果都串起来看。之前排查一个偶发性的 404，就是在日志里发现相同的 path 但不同的 query，其中某个值带特殊字符导致网关路由断言异常，如果日志里只看 path，这个问题几乎不可能定位到。

4. 匹配链路中的工程细节与踩坑实录

4.1 路由优先级：谁先匹配谁说了算

路由优先级的混乱是 URI 匹配里最常见的事故来源之一。Nginx 的 location 匹配顺序我已经在 2.3 节提过，但网关层和后端框架层同样存在优先级问题。Spring Cloud Gateway 的路由是按配置顺序匹配的，先声明的路由优先级更高，命中了就不会继续往下匹配。如果你有两个路由规则：

yaml复制spring:
  cloud:
    gateway:
      routes:
        - id: user-route
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
        - id: admin-route
          uri: lb://admin-service
          predicates:
            - Path=/api/admins/**

那么 /api/users/1 会走 user-route，/api/admins/1 走 admin-route，看起来没问题。但如果你再加一条更宽泛的路由：

yaml复制        - id: default-route
          uri: lb://default-service
          predicates:
            - Path=/**

这一条执行顺序往后放，最后才匹配，所以前面的精确路由优先。但如果把它排在最前面，那么所有请求都会被 default-route 拦截，后面的路由全部失效。这类问题在配置逐渐变多、多人协作时特别容易出现。我的建议是：宽泛兜底路由永远放最后，并加上严格的路径前缀策略，不要把 /** 这种放到中间。

4.2 尾部斜杠、大小写和百分号编码的坑

这三个看着是细节，实际上每一个都能让一个服务从 200 变成 404。

先看尾部斜杠。Nginx 和 Spring 的行为不一致，前面已经提过。在后端设计接口规范时，最好把“尾部斜杠是否允许”写进接口文档，并由网关层统一处理。我的做法是在网关层做一个规则：/api/v1/user 和 /api/v1/user/ 都可以匹配到同一个路由，但选择其中一个作为标准格式，另一个自动 301 重定向到标准格式。这样下游服务就不用关心这个差异，路由匹配行为统一。

再看大小写。Linux 文件系统对路径大小写敏感，所以默认后端服务对 path 也是大小写敏感的。但有些浏览器或客户端会把 URL 的 host 部分转成小写，path 保持不变。如果你在路由规则里写正则 ~* 表示不区分大小写，那么 /API/USERS 也能命中；如果写 ~ 区分大小写，那么 /API/USERS 就会 404。这个没有标准答案，关键是在整条链路里保持一致。我自己倾向于 path 区分大小写，这样语义清晰，也避免大小写不敏感导致的路由歧义。

最后是百分号编码。%2F 表示斜杠，%2f 表示同一个字符。但有些网关在匹配路径时，会先对 URI 做一次解码再匹配，那么 %2F 就会变成 /，从而改变路径结构，可能绕过某些安全规则。这就是著名的斜杠编码绕过问题。举个简单的例子，安全规则拦截 /admin，但攻击者传 /ad%6din，如果解码发生在匹配之前，%6d 被解码成 m，那么这条路径就变成了 /admin，可以被拦截；但如果解码发生在匹配之后，安全规则看到的是 /ad%6din，安然放行，后端拿到原始 URL 后再解码，就访问到了 /admin。这类解码顺序漏洞在安全审计里非常常见，设计网关时一定要明确：路径匹配基于解码前还是解码后。

4.3 安全三件套：路径穿越、开放重定向与参数污染

做过 Web 安全的朋友应该对这三个词不陌生，它们基本都跟 URI 匹配与查询直接相关。

路径穿越我已经在 3.3 节提过，这里再多说一句：除了文件下载场景，请求转发和代理场景也容易出问题。如果网关根据 query 参数里的 target 字段做转发，攻击者可以构造一个 target=//evil.com，把请求转发到恶意站点，这就是开放重定向或代理型攻击。

参数污染是另一个很有意思的点。同样的 key 出现多次时，不同的解析器会选择不同的值，借用这个差异可以绕过鉴权。举个例子，一个接口用 WAF 层的参数解析判断用户角色，取第一个参数值，而后端取最后一个，攻击者就可以构造 ?role=admin&role=guest，WAF 认为 role 是 admin，放行；后端认为 role 是 guest，也放行？不对，这样就产生了鉴权绕过。更常见的是取反：WAF 拦截的是 role=admin，但攻击者传 role=guest&role=admin，WAF 取第一个值是 guest，放行，后端取最后一个值是 admin，攻击成功。所以设计参数解析策略时，全链路必须统一，不能各层各抽各的风。

4.4 常见问题速查表

我把日常工作中经常遇到的一些 URI 匹配与查询相关的问题整理成了表格，方便大家排查时快速对照。

这张表只是一个起点，实际排查的时候还要结合具体的框架特性。我的经验是：遇到 URI 相关的问题，不要一上来就改代码，先把请求从客户端到服务器的完整链路日志拉出来，看每一层拿到的 URI 长什么样、匹配到了哪条规则、解析出了哪些参数，逐步缩小范围，通常很快就能定位到问题。

5. 一次真实排查：一个 404 背后藏着三处问题

5.1 现象与第一反应

之前有一个老项目找我帮忙排查问题，现象很有意思：客户端调用一个查询接口，偶尔 404，不是必现，也不是稳定的某种参数组合，看起来毫无规律。第一反应当然是看代码，但代码里路由规则很简单，就一个 @GetMapping("/api/v1/orders")，怎么想都不应该 404。

于是我先在网关层打了日志，发现请求确实到达了网关，URI 是 /api/v1/orders?userId=123&orderNo=a%2Bb%40123.com。问题出现了，orderNo 参数里有一个邮箱格式的值，里面包含 +，编码后是 %2B。网关层的日志显示这个请求被匹配到了另一个路由上，而不是 /api/v1/orders 对应的路由。

为什么会被匹配到其他路由？因为网关路由配置里有两条规则，一条是精确的 /api/v1/orders，另一条是一个兜底规则 /api/**/{segment}，原本是用来处理某些多级路径的特殊情况的。在网关的路径匹配器里，它认为 /api/v1/orders 也能被 /api/**/{segment} 匹配，而且因为两条规则的优先级配置不当，兜底规则反而先命中了。

5.2 排查链路与定位过程

定位过程主要分三步走。

第一步，对比正常请求和异常请求的原始 URI。正常请求的 orderNo 是普通的数字，比如 orderNo=10086；异常请求的 orderNo 里带着邮箱，编码后出现了 %2B。这里的关键在于，网关的路径匹配器拿到原始 URI 后，有可能对 query 部分做了解码，把它当作路径的一部分参与匹配，导致路径结构发生了细微变化。

第二步，检查网关层路由优先级。我发现配置里那条兜底路由写在精确路由前面，这在多数框架里是致命问题，因为路由匹配是顺序制的，先声明先匹配，精确路由反而被兜底规则抢了先。

第三步，检查参数解析逻辑。网关把请求转发到后端后，后端是一个老项目，query 参数是手写解析的，没有对 + 做空格解码，导致 a%2Bb%40123.com 被解码成了 a+b@123.com 之后，又被后续某段逻辑误认为是一个路径片段，拼接到了转发的 URI 里，最终后端收到的请求变成了类似 /api/v1/orders/a+b@123.com 的伪路径，路由匹配失败直接 404。

5.3 修复方案与复盘

这个案例最后做了三处修复。

第一处，调整网关路由顺序，把精确匹配的路由全部放在兜底路由之前，避免兜底规则抢占精确路径。这属于配置层面的修复，最直接。

第二处，在网关层统一 path 匹配的边界，明确路径匹配只针对 path 部分，query 参数在匹配阶段一律忽略，避免解码后的 query 值参与路径匹配。

第三处，把后端手写解析 query 的代码换成标准库解析，确保 + 和 %2B 的语义一致，并且对邮箱这类可能携带特殊字符的值做了统一编解码校验。顺带把这个项目的访问日志补上了 $request_uri 和 traceId，下次再遇到问题就不用靠猜了。

复盘下来，这个 404 其实不是某一个环节的单一 bug，而是三层问题的串行叠加：路由优先级不当、路径与 query 边界模糊、参数解析不规范。每一层单独看都不致命，但连在一起就变成了一个偶发性的疑难杂症。这个案例让我深刻体会到，URI 匹配与查询这种看似基础的环节，恰恰是架构设计里最需要统一约定和规范化的地方。现在我在每一个项目开始前，都会先花半小时把路径匹配规则、query 解析策略、日志打印格式这三件事定成规范写进 README，后续省下来的排查时间远远超过这半小时。