适用读者：所有 Node.js 开发者，特别是那些需要构建 Web 客户端、API 服务、或任何需要与 URL 打交道的应用的工程师
目标：深入理解 WHATWG URL 标准，掌握 URL 和 URLSearchParams 的强大功能，并能编写出健壮、可预测的 URL 处理代码

---

1. 统一的时代：从 url.parse() 到 new URL()

在 Node.js 的早期，处理 URL 主要使用 require('url').parse()。这个方法返回一个普通的 JavaScript 对象，其行为在 Node.js 和浏览器之间并不完全一致，这在处理边缘情况时可能导致问题。
为了解决这个问题，WHATWG URL 标准应运而生。这是一个被所有现代浏览器和 Node.js 共同采纳的标准，它提供了一个统一的、可预测的 API。在 Node.js 中，这个标准通过全局的 URL 类来实现。
重要警告：url.parse() 已被标记为遗留。虽然为了向后兼容它仍然存在，但强烈建议在所有新项目中使用 new URL()。

2. 解构 URL：理解 URL 对象的属性

URL 构造函数接收一个 URL 字符串作为参数，并返回一个功能丰富的 URL 对象。这个对象包含了 URL 的每一个组成部分。
URL 结构分解图：

https://user:pass@example.com:8080/path/to/page?query=string#hash
\___/   \___/ \_____________________/ \__/\________________/ \______/
  |       |            |               |          |              |
protocol  auth         hostname        port      pathname       hash
          \___________________________/            \__________/
                     |                               |
                   origin                           search

代码示例：探索 URL 对象

const myURL = new URL('https://user:pass@example.com:8080/path/to/page?query=string#hash');
// 基础属性
console.log('href:', myURL.href);        // 完整的 URL
console.log('origin:', myURL.origin);    // 'https://example.com:8080'
console.log('protocol:', myURL.protocol); // 'https:'
console.log('username:', myURL.username); // 'user'
console.log('password:', myURL.password); // 'pass'
// 认证信息
console.log('host:', myURL.host);        // 'example.com:8080'
console.log('hostname:', myURL.hostname); // 'example.com'
console.log('port:', myURL.port);        // '8080'
// 路径与查询
console.log('pathname:', myURL.pathname); // '/path/to/page'
console.log('search:', myURL.search);     // '?query=string'
console.log('hash:', myURL.hash);         // '#hash'
// 强大的 searchParams 属性！
console.log('searchParams:', myURL.searchParams); // URLSearchParams 对象
console.log('Query value:', myURL.searchParams.get('query')); // 'string'

---

3. 核心特性：基础路径 与不可变性

3.1 使用基础路径 解析相对 URL

URL 构造函数的第二个可选参数 base 非常强大，它允许你解析一个相对 URL，就像在浏览器中一样。

const baseUrl = 'https://example.com/path/to/';
// 解析相对路径
const relativeURL = new URL('../other/page.html', baseUrl);
console.log(relativeURL.href); // 'https://example.com/path/other/page.html'
// 解析绝对路径（会忽略 base）
const absoluteURL = new URL('https://another.com/index.html', baseUrl);
console.log(absoluteURL.href); // 'https://another.com/index.html'

这个功能在构建 Web 爬虫或 API 客户端时极其有用，当你需要根据页面的 <a> 标签解析出完整的链接时。

3.2 不可变性

URL 对象的属性大多是只读的。你不能直接修改 href、origin 等。要改变 URL，你需要修改其可写属性（如 pathname, search, hash），或者创建一个新的 URL 实例。

const myURL = new URL('https://example.com/path');
// 正确的修改方式
myURL.pathname = '/new/path';
myURL.search = '?id=123';
console.log(myURL.href); // 'https://example.com/new/path?id=123'
// 错误的修改方式（会静默失败或报错）
// myURL.href = 'https://google.com'; // 在某些版本中会报错

---

4. 实战：动态构建和修改 URL

URL 对象和 URLSearchParams 的结合，使得动态构建和修改 URL 变得异常简单。

// 场景：构建一个分页 API 的 URL
function buildApiUrl(baseUrl, page, limit, filters = {}) {
  const url = new URL('/api/items', baseUrl);
  // 添加分页参数
  url.searchParams.set('page', page.toString());
  url.searchParams.set('limit', limit.toString());
  // 动态添加过滤条件
  for (const [key, value] of Object.entries(filters)) {
    url.searchParams.append(key, value);
  }
  return url.toString();
}
const apiBaseUrl = 'https://api.myapp.com';
const pageUrl = buildApiUrl(apiBaseUrl, 2, 20, { category: 'books', sort: 'desc' });
console.log(pageUrl);
// 输出: 'https://api.myapp.com/api/items?page=2&limit=20&category=books&sort=desc'

---

5. 实战：安全地验证和解析用户输入

当处理来自用户的 URL 时，必须非常小心。URL 构造函数可以帮助你进行基本的验证。

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;
  }
}
console.log(isValidUrl('https://example.com')); // true
console.log(isValidUrl('not-a-url'));           // false
// 场景：从用户输入中提取域名
function getHostnameFromInput(input) {
  try {
    const url = new URL(input);
    // 确保协议是 http 或 https，防止 javascript: 等伪协议
    if (url.protocol === 'http:' || url.protocol === 'https:') {
      return url.hostname;
    }
  } catch (e) {
    // 输入不是有效 URL
    return null;
  }
  return null;
}
console.log(getHostnameFromInput('https://user:pass@example.com:8080/path')); // 'example.com'
console.log(getHostnameFromInput('javascript:alert(1)')); // null

---

6. 总结与最佳实践

6.1 关键概念回顾

• new URL() 是现代、标准的 URL 处理方式，取代了 url.parse()。
• URL 对象提供了丰富的属性来访问 URL 的各个组成部分。
• 基础路径 功能可以方便地解析相对 URL。
• URL 对象是不可变的，需要通过修改其可写属性来改变 URL。
• URLSearchParams 是处理查询字符串的强大工具，与 URL 对象无缝集成。

6.2 URL 处理最佳实践清单

• ✅ 始终使用 new URL()：放弃 url.parse()，以获得跨平台的一致性和更好的错误处理。
• ✅ 利用 base 参数：在处理相对路径时，使用 base 参数，而不是手动拼接字符串。
• ✅ 使用 URLSearchParams：放弃手动拼接查询字符串，使用其提供的 .set(), .append(), .delete() 等方法。
• ✅ 验证用户输入：使用 try...catch 包裹 new URL() 来验证用户输入的 URL 是否有效。
• ✅ 检查协议：在处理不受信任的 URL 时，检查 protocol 属性，防止安全漏洞（如 javascript: 或 file: 协议）。

6.3 进阶学习路径

1. WHATWG URL 标准：阅读官方规范，了解 URL 解析的所有细节和边缘情况。
2. URL API 与 Fetch API：学习 URL 对象如何与 fetch API 结合使用，进行现代 Web 请求。
3. 国际化域名：了解 URL 对象如何处理 punycode 编码的国际化域名。
4. 自定义搜索参数：探索如何通过继承 URLSearchParams 来创建自定义的查询参数处理逻辑。

6.4 资源推荐

• Node.js 官方文档：URL
• WHATWG URL Standard：https://url.spec.whatwg.org/
• MDN：URL
  最终建议：URL 是 Web 的寻址系统，处理 URL 是 Web 开发的基础。new URL() 和 URLSearchParams 的出现，标志着 Node.js 在这一基础领域与浏览器标准实现了完全的统一。这不仅让代码更具可移植性，也大大降低了心智负担。当你能熟练地使用这些现代 API 来构建、解析和验证 URL 时，你的代码将变得更加健壮、安全和易于维护。这是每一位现代 Node.js 开发者都应该掌握的核心技能。