JS解析嵌套对象或数组格式的复杂查询字符串

在前后端交互或富交互单页应用中，经常需要把过滤条件、多选列表或分层筛选参数通过 URL 进行传递，例如 user[name]=Ada&user[profile][city]=Beijing&tags[]=1&tags[]=2。然而，浏览器原生内置的 URLSearchParams 仅支持将键值对解析为扁平的字符串映射，遇到方括号（Bracket Notation）或点号（Dot Notation）的多层结构时，无法自动将其反序列化为深层对象或数组。本文将深入分析原生 API 的适用边界，解释键路径切分与对象树回填的完整算法，并给出兼顾安全防护（防原型链污染）的纯 JavaScript 解决方案与工程级库选型建议。

一、原生 URLSearchParams 的能力边界与常见误区

不少开发者初次处理 URL 参数时，常误以为 URLSearchParams 是万能的查询字符串解析器。事实上，W3C 与 WHATWG 的 URL 规范只定义了键值均为空或字符串的一维列表结构，并未在规范层面规定类似 a[b][c] 的深层语法。方括号嵌套语法最初由 PHP、Ruby on Rails 等后端框架约定，后来成为 Web 前后端传递复杂复合参数的事实标准。

来看一个直观的反例。假设我们有一个包含多维对象与数组的 URL 参数：

const query = "?user[name]=Ada&user[age]=28&skills[]=JS&skills[]=Rust";
const params = new URLSearchParams(query);

console.log(params.get("user")); // 输出 null
console.log(params.get("user[name]")); // 输出 "Ada"
console.log(params.get("skills[]")); // 仅能输出 "JS"，丢失了第二个值（需调 getAll）

从上面的结果可以看出，URLSearchParams 仅仅把整段 user[name] 和 skills[] 当作不可分割的普通字符串键。它既不会创建 user 父对象，也不会把带空方括号的 skills[] 自动识别为数组。如果直接在业务中依赖 Object.fromEntries(params)，不仅深层对象全部退化为包含方括号的扁平键，同名数组参数还会直接被后一个值覆盖。

二、常见嵌套查询语法与 Token 路径分析

在动手编写解析函数之前，必须先理清常见复杂查询字符串的语法约定。常见形式有以下四类：

• 显式对象方括号语法：例如 filter[price][min]=10&filter[price][max]=100。外层为 filter，中层为 price，叶子节点分别为 min 和 max。
• 无索引数组空括号：例如 colors[]=red&colors[]=blue。每次出现空括号 []，代表在当前数组末尾追加一个元素。
• 带数字索引的数组：例如 items[0]=apple&items[1]=banana 或 items[0][name]=book。括号内是正整数，表示特定下标。
• 点号分隔语法：部分框架（如 MongoDB 查询或某些 REST 客户端）会采用点号表示路径，例如 user.profile.age=20。

解析的核心思想，就是将形如 user[roles][0][name] 的复合键名，逐层分解为一个路径切片列表（Token List）：['user', 'roles', 0, 'name']。只有将连续的字符串转换成了结构化的 Token 数组，后续的对象树构造才能按步就班地进行。

三、算法实现：纯 JavaScript 解析嵌套结构与数组

要构建一个鲁棒的解析器，核心逻辑分为三步：

1. 预处理与键值提取：剔除开头的 ? 或 #，按 & 分割每一对参数。对分离出来的原始 Key 与 Value 分别执行 decodeURIComponent 解码。
2. 安全阻断（防原型污染）：在进入深层赋值前，严格检查 Key 中是否包含 __proto__、constructor 或 prototype。一旦允许这类键修改对象属性，恶意构造的 URL 将导致全局对象原型链污染，引发严重安全隐患。
3. 路径遍历与动态容器推导：沿着 Token 依次移动指针。遇到尚未创建的中间节点时，需要向前“预窥”（Lookahead）下一个 Token：如果下一个 Token 是纯数字或空括号，当前节点必须初始化为数组 []；否则初始化为普通对象 {}。

完整解析函数代码实现

下面是一个经过严格测试、支持深层嵌套、方括号数组与点号语法的纯 JavaScript 实现函数 parseComplexQuery：

/**
 * 解析包含嵌套对象或数组语法的复杂查询字符串
 * @param {string} queryString - 待解析的 URL 查询字符串（带或不带开头的 '?'）
 * @returns {Record<string, any>} 解析后的嵌套 JavaScript 对象
 */
function parseComplexQuery(queryString) {
  if (typeof queryString !== "string" || !queryString.trim()) {
    return Object.create(null);
  }

  // 1. 移除开头的 '?' 或 '#'，去除首尾空白
  const cleanStr = queryString.trim().replace(/^[?#]/, "");
  if (!cleanStr) return Object.create(null);

  // 使用无原型对象存储，杜绝意外访问 Object 原型属性
  const result = Object.create(null);

  // 2. 切分键值对
  const pairs = cleanStr.split("&");
  for (const pair of pairs) {
    if (!pair) continue;
    const eqIdx = pair.indexOf("=");
    let rawKey = eqIdx === -1 ? pair : pair.slice(0, eqIdx);
    let rawVal = eqIdx === -1 ? "" : pair.slice(eqIdx + 1);

    // 替换 '+' 为空格并进行 URL 解码
    let key, val;
    try {
      key = decodeURIComponent(rawKey.replace(/\+/g, " "));
      val = decodeURIComponent(rawVal.replace(/\+/g, " "));
    } catch {
      // 容错处理：非法编码则保留原始内容
      key = rawKey;
      val = rawVal;
    }

    // 3. 原型污染防御：阻断危险键名
    if (/(__proto__|constructor|prototype)/.test(key)) {
      continue;
    }

    // 4. 解析路径 Token
    // 支持方括号 user[address][city] 与 点号 user.address.city
    const tokens = extractTokens(key);
    if (tokens.length === 0) continue;

    // 5. 逐层回填对象树
    insertValue(result, tokens, val);
  }

  return result;
}

/**
 * 将键名字符串提取为路径 Token 数组
 * 示例: "user[roles][0][name]" -> ["user", "roles", 0, "name"]
 * 示例: "tags[]" -> ["tags", ""]
 */
function extractTokens(key) {
  const tokens = [];
  // 正则匹配：主键 或 [键名/数字/空]
  const regex = /([^.\[\]]+)|\[([^\]]*)\]/g;
  let match;

  while ((match = regex.exec(key)) !== null) {
    if (match[1] !== undefined) {
      // 顶级属性名（包括点号分隔的情况）
      tokens.push(match[1]);
    } else if (match[2] !== undefined) {
      const bracketVal = match[2];
      if (bracketVal === "") {
        // 空括号：tags[]
        tokens.push("");
      } else if (/^\d+$/.test(bracketVal)) {
        // 纯数字下标：items[0]
        tokens.push(parseInt(bracketVal, 10));
      } else {
        // 字符串属性：user[name]
        tokens.push(bracketVal);
      }
    }
  }

  return tokens;
}

/**
 * 递归/游标回填值到目标对象中
 */
function insertValue(root, tokens, value) {
  let current = root;

  for (let i = 0; i < tokens.length; i++) {
    const token = tokens[i];
    const isLast = i === tokens.length - 1;

    // 如果到达路径末尾：执行写入
    if (isLast) {
      if (token === "") {
        // 空括号追加模式：arr[] = val
        if (!Array.isArray(current)) {
          // 当前不是数组则转换为数组
          return;
        }
        current.push(value);
      } else if (typeof token === "number") {
        current[token] = value;
      } else {
        if (current[token] === undefined) {
          current[token] = value;
        } else if (Array.isArray(current[token])) {
          current[token].push(value);
        } else {
          // 同名键自动合并为数组
          current[token] = [current[token], value];
        }
      }
      return;
    }

    // 尚未到达末尾：需要探查下一个 Token 的性质以决定当前层是创建 Array 还是 Object
    const nextToken = tokens[i + 1];
    const shouldBeArray = typeof nextToken === "number" || nextToken === "";

    if (token === "") {
      // 当前为空括号且还要继续下探，在数组末尾新建一个容器
      const nextContainer = shouldBeArray ? [] : Object.create(null);
      current.push(nextContainer);
      current = nextContainer;
    } else {
      if (current[token] === undefined || current[token] === null || typeof current[token] !== "object") {
        current[token] = shouldBeArray ? [] : Object.create(null);
      }
      current = current[token];
    }
  }
}

验证运行效果

我们可以使用多组覆盖复杂边界条件的输入，验证上述实现的正确性：

// 示例 1：对象深层嵌套与点号兼容
const q1 = "user[name]=Ada&user[contact][email]=ada@example.com&theme.mode=dark";
console.log(parseComplexQuery(q1));
// 示例输出:
// {
//   user: {
//     name: "Ada",
//     contact: { email: "ada@example.com" }
//   },
//   theme: { mode: "dark" }
// }

// 示例 2：空括号数组追加与数字索引对象数组
const q2 = "tags[]=es6&tags[]=web&items[0][id]=1&items[0][title]=Pen&items[1][id]=2";
console.log(parseComplexQuery(q2));
// 示例输出:
// {
//   tags: ["es6", "web"],
//   items: [
//     { id: "1", title: "Pen" },
//     { id: "2" }
//   ]
// }

// 示例 3：安全防护（原型链污染测试）
const q3 = "__proto__[isAdmin]=true&user[constructor][prototype][role]=hacker&safe=1";
console.log(parseComplexQuery(q3));
// 示例输出:
// { safe: "1" } 
// 恶意键被自动拦截过滤，全局 Object.prototype 未受任何污染

四、工程实践与第三方成熟库选型（qs 库）

在业务逻辑相对受控的小型前端项目、轻量 SDK 或对代码打包体积（Bundle Size）有苛刻要求的微前端场景下，使用上文约 80 行的轻量级解析函数完全能够满足需求。但在大型企业级项目、Node.js 服务端网关、或需要与第三方复杂接口对齐的场景下，推荐引入社区事实标准 qs 库。

成熟的 qs 库相比手写实现，增加了以下维度的防御与增强能力：

• 深度限制（depth）：默认将嵌套解析深度限制为 5 层，防止恶意用户构造诸如 a[b][c][d]...[z] 导致调用栈过深或内存耗尽。
• 数组上限（arrayLimit）：当解析到 items[1000000000]=1 时，原生数组会分配极大的稀疏槽位导致内存崩溃，qs 超过上限后会自动退化为普通对象而非真实数组。
• 参数数量上限（parameterLimit）：默认限制最多解析 1000 个参数，避免哈希碰撞或极多参数导致的拒绝服务（DoS）。

使用 qs 的标准调用方式如下：

// npm install qs
import qs from "qs";

const search = "?filter[status]=active&filter[categories][]=books&sort=desc";

const parsed = qs.parse(search, {
  ignoreQueryPrefix: true, // 自动剥离开头的 '?'
  allowDots: true,         // 支持 'a.b=1' 点号嵌套语法
  depth: 6,                // 允许的最大嵌套深度
  arrayLimit: 50,          // 数组索引的最大值限制
});

console.log(parsed);
// 输出规范解析后的嵌套对象

五、开发中必须注意的三个关键问题

1. 编码与特殊字符转换：查询字符串中的空格有时被序列化为 +，有时为 %20。在执行 decodeURIComponent 之前，建议先将 + 替换为常规空格，避免解码后丢失空格或产生意外符号。
2. 稀疏数组与超大索引攻击：如果客户端发送 list[99999999]=1，直接以纯数字下标创建原生 JavaScript 数组会导致引擎分配极大的内存槽位，严重时可导致页面假死或 Node 服务内存超限崩溃。因此手写解析器中如果遇到大于预期（如超过 1000）的索引，应抛出异常或降级为普通对象键名。
3. 类型自动转换的取舍：数字 "123" 和布尔 "true" 是否应在解析阶段自动转换为数值和布尔类型？通常建议保持字符串原生形态，或者仅由上层业务 Schema 校验器（如 Zod、Joi、TypeScript 接口）统一进行转换，避免因隐式类型转换把手机号、身份证号或以 0 开头的编码字符串破坏为数字。

六、总结

解析包含嵌套对象或数组格式的复杂查询字符串，本质上是将非标准的扁平路径标记（方括号或点号）逆向还原为层级树结构的过程。浏览器原生 URLSearchParams 适用于平铺的一维键值查询；当面对 user[profile][name] 或 tags[] 这类复合参数时，应通过正则提取路径 Token，结合深度预窥与原型链过滤安全回填对象。在注重体积的场景下推荐使用文中约 80 行的轻量算法，在企业级复杂系统中则优先使用带深度与数组上限控制的 qs 库，以获得兼顾功能完备与运行安全的最佳实践。