JavaScript GET请求怎么正确拼接URL查询参数

图 0：GET 请求 URL 查询参数拼装模型概览

一、为什么不建议用字符串直接拼接？

在早期开发或快速原型编写中，许多开发者习惯使用加号 + 或 ES6 模板字符串来拼凑 URL，例如 url + '?id=' + id + '&keyword=' + keyword。这种方式看似简单，但在实际生产场景中存在三个极易引发隐蔽 Bug 的严重缺陷：

• 特殊字符截断与数据失真：如果用户输入的搜索词或参数值中包含 &、=、+、空格、问号或中文，在没有逐个执行 encodeURIComponent 的情况下，浏览器和后端服务器会直接将 & 当作参数分隔符、将 = 当作键值对关联符，导致原本完整的参数被生生截断。例如传入 { keyword: "C++ & Go" }，手动拼成 ?keyword=C++ & Go 后，后端收到的 keyword 会变成 "C "，而 Go 被当成了未定义值的多余键名。
• 分隔符（? 与 &）逻辑判断脆弱：目标接口的基础 URL（Base URL）可能是动态配置的。如果基础 URL 已经预设了内置参数（如 https://api.example.com/items?version=2），直接用 ? 拼接就会产生 items?version=2?page=1 的双问号非法语法；反之若每次都做 url.includes('?') 判断，代码会迅速变得冗余且脆弱。
• 锚点（Hash）位置错乱：根据 RFC 3986 统一资源标识符规范，URL 的查询字符串（Query）必须位于路径与参数之间，而哈希锚点（#section）必须且只能位于整个 URL 的最末尾。如果对一个带有 #intro 锚点的链接直接在末尾拼加查询参数，该参数就会被完全当作客户端锚点的一部分，发送 GET 请求时根本不会提交到后端接口中。

图 1：手写字符串拼接缺陷与 URLSearchParams 原理对比

二、现代标准方案：URL 与 URLSearchParams 原生 API

现代主流运行环境（Chrome、Edge、Firefox、Safari、Node.js 10+、Deno、Bun 等）均已全面原生支持 WHATWG URL 规范及其配套的 URLSearchParams 接口。不需要引入额外依赖包，即可通过规范、语义化的方式管理 URL。

1. 标准四步构建法

拼接一个健壮的 GET 请求地址通常分为四个标准步骤：

1. 创建 URL 实例：基于基础请求地址构造 new URL(base)。
2. 空值过滤：在遍历待拼接的参数对象时，剔除值为 undefined 或 null 的项，避免被强制转成字符串 "undefined"。
3. 写入参数：利用 url.searchParams.set() 进行键值写入，若有同名多值需求则使用 url.searchParams.append()。
4. 输出或直接调用：URL 实例可直接作为 fetch() 的首参数，也可以调用 url.toString() 或 url.href 取得最终完整字符串。

图 2：使用 URL 与 URLSearchParams 拼接参数的标准四步流程

2. 基础绝对路径拼接示例

以下示例展示了如何在发起 fetch 请求前安全构建包含中文、空格及特殊符号的 GET 查询参数：

// 1. 初始化基础请求地址
const url = new URL('https://api.example.com/v1/articles');

// 2. 写入常规参数（自动处理转义）
url.searchParams.set('page', 1);
url.searchParams.set('limit', 20);
url.searchParams.set('keyword', 'JavaScript & 前端开发'); // 包含中文、& 符号和空格

// 3. 打印组装后的规范 URL
console.log(url.toString());
// 示例输出结果：
// https://api.example.com/v1/articles?page=1&limit=20&keyword=JavaScript+%26+%E5%89%8D%E7%AB%AF%E5%BC%80%E5%8F%91

// 4. 直接发起原生 GET 请求
fetch(url)
  .then(response => response.json())
  .then(data => console.log('请求成功：', data))
  .catch(err => console.error('请求失败：', err));

3. 处理相对路径：解决 TypeError: Invalid URL

直接执行 new URL('/api/v1/users') 会在浏览器控制台抛出 TypeError: Invalid URL 异常，因为 URL 构造函数必须能解析出协议（Protocol）与主机名（Host）。如果业务中使用的是相对路径或接口路径，只需传入第二个参数 base 即可解决：

// 针对浏览器端相对路径，使用 window.location.origin 作为基准
const relativePath = '/api/v1/products';
const url = new URL(relativePath, window.location.origin);

url.searchParams.set('category', 'laptops');
url.searchParams.set('sort', 'price_asc');

// 获取相对路径带参数字符串（如用在 axios 或特定客户端）：
const fullRelativeUrl = url.pathname + url.search;
console.log('完整相对路径：', fullRelativeUrl); 
// 示例输出：/api/v1/products?category=laptops&sort=price_asc

// 若直接发 fetch，直接传 url 对象即可：
fetch(url);

三、复杂参数场景：数组、对象与多选值

在实际项目（如筛选列表、多标签过滤、批量 ID 查询）中，GET 请求经常需要传递数组或多个相同键名的参数。不同后端框架（如 Java Spring Boot、Python Django、PHP、Express 等）对数组的解析要求有所不同。

图 3：不同数据类型在 URL 查询参数中的序列化规范

1. 数组的三种常见后端格式与实现方式

• 重复键名模式（如 tag=react&tag=vue）：
  这是 HTTP 规范最标准的集合传参方式，Spring Boot 和 Django 原生支持。使用 url.searchParams.append(key, value) 遍历添加即可：

  const tags = ['react', 'vue', 'nodejs'];
  tags.forEach(tag => url.searchParams.append('tag', tag));
  // 序列化结果：?tag=react&tag=vue&tag=nodejs

• 逗号分隔模式（如 ids=101,102,103）：
  适用于传递纯 ID 列表。先使用数组原生的 join(',') 合并，再通过 set() 设置：

  const ids = [101, 102, 103];
  url.searchParams.set('ids', ids.join(','));
  // 序列化结果：?ids=101%2C102%2C103 （部分服务端支持直接解码逗号）

• 带方括号模式（如 filter[]=a&filter[]=b）：
  PHP、Ruby on Rails 及部分使用 qs 库的 Node.js 服务端要求在键名后添加 []：

  const categories = ['book', 'tech'];
  categories.forEach(item => url.searchParams.append('filter[]', item));
  // 序列化结果：?filter%5B%5D=book&filter%5B%5D=tech

四、通用工具函数封装：支持对象传入与空值净化

在团队协作或项目中，最舒适的体验通常是将一个普通的 JavaScript 对象转换为带查询参数的完整 URL。我们可以封装一个健壮、纯净且无第三方依赖的 buildQueryUrl 工具函数：

/**
 * 规范拼接 GET 请求的 URL 与查询参数
 * @param {string} baseUrl 目标 URL（支持完整域名或相对路径）
 * @param {Record} params 参数键值对象
 * @param {Object} options 配置项：arrayFormat 可选 'repeat' | 'comma' | 'bracket'
 * @returns {string} 拼接好且符合规范的完整 URL
 */
function buildQueryUrl(baseUrl, params = {}, options = {}) {
  const { arrayFormat = 'repeat' } = options;
  
  // 兼顾相对路径与绝对路径
  const isRelative = !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(baseUrl);
  const dummyOrigin = 'http://localhost';
  const url = isRelative 
    ? new URL(baseUrl, typeof window !== 'undefined' ? window.location.origin : dummyOrigin)
    : new URL(baseUrl);

  // 遍历并规范写入参数
  Object.entries(params).forEach(([key, val]) => {
    // 防御性过滤：忽略 undefined 与 null
    if (val === undefined || val === null) {
      return;
    }

    // 处理数组
    if (Array.isArray(val)) {
      if (arrayFormat === 'comma') {
        url.searchParams.set(key, val.join(','));
      } else if (arrayFormat === 'bracket') {
        val.forEach(item => url.searchParams.append(`${key}[]`, String(item)));
      } else {
        // 默认 'repeat'
        val.forEach(item => url.searchParams.append(key, String(item)));
      }
      return;
    }

    // 普通标量直接写入
    url.searchParams.set(key, String(val));
  });

  // 若入参本是相对路径，则仅截取相对部分，保留 pathname + search + hash
  if (isRelative) {
    return url.pathname + url.search + url.hash;
  }

  return url.toString();
}

// 测试验证用例：
const queryUrl = buildQueryUrl('/api/search#result', {
  q: 'vue 3 & vite',
  status: 'published',
  tags: ['web', 'front'],
  emptyVal: null,        // 自动被过滤
  undefinedVal: undefined // 自动被过滤
});

console.log(queryUrl);
// 示例输出结果：
// /api/search?q=vue+3+%26+vite&status=published&tags=web&tags=front#result

五、避坑要点与总结

图 4：JavaScript GET 请求参数拼接全景决策与避坑指南

在日常编写与重构 GET 请求逻辑时，请牢记以下关键原则：

• 严禁混用 set() 与 append()：如果处理分页筛选（如点击页码切换到第 2 页），必须使用 set('page', 2) 替换旧值；若误用 append('page', 2)，原有参数中若已有 page=1，就会产生 page=1&page=2 的冲突请求。
• 不要在原生 API 前后执行重复转码：使用 URLSearchParams 后，请信任引擎的编解码机制，不要在调用 set() 时传入 encodeURIComponent(value)。
• 第三方库（如 Axios）的协作：如果项目使用 Axios，可以通过 params 配置项直接传递普通对象，Axios 内部会调用自身的序列化逻辑。如果需要自定义数组格式，可配置 paramsSerializer 配合 new URLSearchParams() 或 qs 库使用。而在 Fetch 环境下，原生 URL 是毫无疑问的首选标准。