JavaScript 中 URL 和 URLSearchParams 的陷阱

一切都始于一个错误

在 JavaScript 和 Node.js 中使用 URL 应该很简单，但是我们项目中最近的一个错误让我陷入了 URL 和 URLSearchParams API 中微妙怪癖的兔子洞。这篇文章将探讨这些怪癖，它们如何在您的代码中引起问题，以及您可以采取哪些措施来避免它们。

---

问题：使用 Axios 处理 URL

我们在生成 URL 并向其添加哈希签名时遇到了此问题。查询参数的百分比编码不一致，导致意外行为和错误的哈希签名。

很明显，URL 和 URLSearchParams 对象之间的交互需要格外小心。

---

陷阱#1：URL.search 与 URLSearchParams.toString()

第一个惊喜是 URL.search 和 URLSearchParams.toString() 之间的区别。

使用 .searchParams 修改 URL 时要小心，因为根据 WHATWG 规范，URLSearchParams 对象使用不同的规则来确定要对哪些字符进行百分比编码。例如，URL 对象不会对 ASCII 波形符 (~) 字符进行百分号编码，而 URLSearchParams 将始终对其进行编码。

// Example 1
const url = new URL("https://example.com?param=foo bar");
console.log(url.search); // prints param=foo%20bar
console.log(url.searchParams.toString()); // prints ?param=foo+bar

// Example 2
const myURL = new URL('https://example.org/abc?foo=~bar');
console.log(myURL.search);  // prints ?foo=~bar
// Modify the URL via searchParams...
myURL.searchParams.sort();
console.log(myURL.search);  // prints ?foo=%7Ebar

在我们的项目中，我们需要显式地重新分配 url.search = url.searchParams.toString() 以确保查询字符串的编码一致。

---

陷阱#2：加号困境

另一个问题是 URLSearchParams 如何处理字符。默认情况下，URLSearchParams 解释为空格，这在编码二进制数据或 Base64 字符串时可能会导致数据损坏。

const params = new URLSearchParams("bin=E+AXQB+A");
console.log(params.get("bin")); // "E AXQB A"

一种解决方案是在将值附加到 URLSearchParams 之前使用encodeURIComponent：

params.append("bin", encodeURIComponent("E+AXQB+A"));

更多详细信息请参阅 MDN 文档。

---

陷阱 #3：URLSearchParams.get 与 URLSearchParams.toString()

比较 URLSearchParams.get 和 URLSearchParams.toString 的输出时会出现另一个微妙之处。例如：

const params = new URLSearchParams("?key=value&key=other");
console.log(params.get("key")); // "value" (first occurrence)
console.log(params.toString()); // "key=value&key=other" (all occurrences serialized)

在多值场景中，get 仅返回第一个值，而 toString 则序列化所有值。

---

我们代码库中的修复

在我们的项目中，我们通过显式重新分配搜索属性解决了该问题：

url.search = url.searchParams.toString();
url.searchParams.set(
  "hash",
  cryptography.createSha256HmacBase64UrlSafe(url.href, SECRET_KEY ?? "")
);

这确保了在添加哈希值之前所有查询参数都已正确编码。

---

Node.js 查询字符串模块

WHATWG URLSearchParams 接口和 querystring 模块具有类似的用途，但 querystring 模块的用途更通用，因为它允许自定义分隔符（& 和 =）。另一方面，URLSearchParams API 纯粹是为 URL 查询字符串而设计的。

querystring 比 URLSearchParams 性能更高，但不是标准化 API。当性能不重要或需要与浏览器代码兼容时，请使用 URLSearchParams。

与 querystring 模块不同，使用 URLSearchParams 时，不允许数组值形式的重复键。数组使用 array.toString() 进行字符串化，它只是用逗号连接所有数组元素。

// Example 1
const url = new URL("https://example.com?param=foo bar");
console.log(url.search); // prints param=foo%20bar
console.log(url.searchParams.toString()); // prints ?param=foo+bar

// Example 2
const myURL = new URL('https://example.org/abc?foo=~bar');
console.log(myURL.search);  // prints ?foo=~bar
// Modify the URL via searchParams...
myURL.searchParams.sort();
console.log(myURL.search);  // prints ?foo=%7Ebar

使用querystring模块，查询字符串'foo=bar&abc=xyz&abc=123'被解析为：

const params = new URLSearchParams("bin=E+AXQB+A");
console.log(params.get("bin")); // "E AXQB A"

---

要点

1. 小心 URLSearchParams 处理特殊字符（例如 ~）和空格。必要时使用encodeURIComponent。

2. 了解 URL.search、URLSearchParams.get 和 URLSearchParams.toString 之间的区别，以避免意外行为。

3. 在 Node.js 中，如果要将重复的查询参数键解析为数组，请使用查询字符串模块。

以上是JavaScript 中 URL 和 URLSearchParams 的陷阱的详细内容。更多信息请关注PHP中文网其他相关文章！