Undici 拦截器匹配问题：URL 结尾斜杠的影响分析

在 Node.js 生态系统中，Undici 作为高性能的 HTTP/1.1 客户端库，其 MockAgent 功能为开发者提供了便捷的测试手段。然而，一个容易被忽视的细节是 URL 结尾斜杠对拦截器匹配的影响。

问题现象

当使用 Undici 的 MockAgent 进行测试时，如果 origin URL 以斜杠结尾，会导致拦截器无法正确匹配请求路径。例如：

const mockAgent = new MockAgent();
mockAgent.disableNetConnect();
const pool = mockAgent.get("https://localhost/");  // 注意结尾斜杠

pool.intercept({ path: "/api/some-path" }).reply(200, { ok: true });

这种情况下，对 https://localhost/api/some-path 的请求会失败，因为拦截器无法正确识别路径匹配。

技术原理

Undici 在处理 URL 匹配时，会对 origin 和路径进行严格的字符串拼接。当 origin 包含结尾斜杠时：

1. 实际请求 URL 变为 https://localhost//api/some-path（双斜杠）
2. 拦截器期望的路径模式仍然是单斜杠开头的 /api/some-path
3. 这种不匹配导致 MockNotMatchedError 错误

解决方案

目前有两种推荐做法：

1. 规范化 URL：在使用前确保 origin 不包含结尾斜杠

   const origin = "https://localhost".replace(/\/$/, "");
   const pool = mockAgent.get(origin);
   

2. 调整拦截器路径：如果必须保留结尾斜杠，可以修改拦截器路径

   pool.intercept({ path: "api/some-path" }).reply(200, { ok: true });
   

最佳实践

1. 在测试代码中建立 URL 规范化函数，确保所有测试用例使用统一格式
2. 考虑在 MockAgent 封装层自动处理 URL 规范化
3. 编写测试时注意检查 URL 格式，特别是从配置文件或环境变量读取的情况

总结

URL 格式的细微差别可能导致测试失败，这是 Web 开发中常见的陷阱。理解 Undici 拦截器的工作原理，并采用一致的 URL 处理策略，可以避免这类问题。对于测试框架开发者来说，考虑在内部自动处理这类规范化问题，将大大提升开发体验。