JSON 扁平化与反扁平化工程实战：从嵌套结构到一维键值对的算法实现

在一次真实的微服务迁移项目中，我需要将一个 6 层嵌套的 JSON 配置文件（2800+ 行）导入到只支持一维键值对的环境变量管理系统中——手写了 3 小时的转换脚本后，我发现 npm 上 flat 这个包的周下载量已经超过 2200 万次，说明「JSON 扁平化」是一个极其高频的工程需求。从 Kubernetes ConfigMap 的键值限制、到数据库的 EAV 模型存储、再到前端表单的扁平数据提交，嵌套 JSON 与一维键值对之间的转换无处不在。但大多数开发者对 flat 的理解停留在 flatten(obj) 一行调用——当遇到数组嵌套、循环引用、特殊键名、类型保持等问题时，这行代码会让你在生产环境付出惨痛代价。

本文将从零实现一个生产级的 JSON 扁平化/反扁平化引擎，覆盖点号路径（Dot Notation）与括号路径（Bracket Notation）两种方案，深入处理数组、循环引用、BigInt、Date 等边界场景，并与 flat、flatley、underscore 等主流库做性能基准对比。

🔄 一、JSON 扁平化的核心算法

1.1 什么是 JSON 扁平化？

JSON 扁平化（Flatten）是将嵌套的 JSON 对象转换为一维键值对的过程，其中键（Key）用路径表示嵌套关系：

// 扁平化前：嵌套 JSON
const nested = {
  server: {
    host: "localhost",
    port: 3000,
    database: {
      primary: { url: "postgres://...", pool: { min: 5, max: 20 } },
      replica: { url: "postgres://..." }
    }
  },
  features: ["auth", "logging", "cache"]
};

// 扁平化后：一维键值对（点号路径）
const flattened = {
  "server.host": "localhost",
  "server.port": 3000,
  "server.database.primary.url": "postgres://...",
  "server.database.primary.pool.min": 5,
  "server.database.primary.pool.max": 20,
  "server.database.replica.url": "postgres://...",
  "features.0": "auth",
  "features.1": "logging",
  "features.2": "cache"
};

💡 提示： 扁平化后的键路径有两种主流表示法——点号路径（a.b.c）和括号路径（a[b][c]）。点号路径更简洁，括号路径能处理含点号的键名。本文两种都会实现。

1.2 递归扁平化算法实现

核心思路是深度优先遍历（DFS）：遇到基本类型就记录路径和值，遇到对象或数组就递归展开。

// JSON 扁平化引擎 — 支持点号路径和括号路径
function flatten(obj, options = {}) {
  const {
    delimiter = ".",          // 路径分隔符
    bracket = false,          // 是否使用括号路径 a[0][b]
    maxDepth = 20,            // 最大递归深度（防栈溢出）
    preserveArrays = false,   // true = 数组不展开，保持为值
    transformKey = null,      // 自定义 key 转换函数
  } = options;

  const result = {};

  function _flatten(value, path, depth) {
    // 防止栈溢出
    if (depth > maxDepth) {
      result[path] = value;
      return;
    }

    // null/undefined 直接赋值
    if (value === null || value === undefined) {
      result[path] = value;
      return;
    }

    // 基本类型直接赋值
    if (typeof value !== "object") {
      result[path] = value;
      return;
    }

    // Date、RegExp 等特殊对象直接赋值
    if (value instanceof Date || value instanceof RegExp || value instanceof Error) {
      result[path] = value;
      return;
    }

    // 数组处理
    if (Array.isArray(value)) {
      if (preserveArrays) {
        result[path] = value;
        return;
      }
      for (let i = 0; i < value.length; i++) {
        const key = bracket ? `[${i}]` : `${delimiter}${i}`;
        const newPath = path ? `${path}${key}` : `${i}`;
        _flatten(value[i], newPath, depth + 1);
      }
      return;
    }

    // 对象处理
    for (const [k, v] of Object.entries(value)) {
      // 处理含分隔符或特殊字符的键名
      const escapedKey = bracket
        ? `[${k}]`
        : (k.includes(delimiter) || k.includes(" ") || k.includes("["))
          ? `${delimiter}["${k}"]`
          : `${delimiter}${k}`;

      const newPath = path ? `${path}${escapedKey}` : k;
      const finalKey = transformKey ? transformKey(k, newPath) : newPath;
      _flatten(v, finalKey, depth + 1);
    }
  }

  _flatten(obj, "", 0);
  return result;
}

// 测试
const config = {
  db: { host: "localhost", port: 5432 },
  cache: { redis: { url: "redis://localhost" } }
};

console.log(flatten(config));
// { "db.host": "localhost", "db.port": 5432, "cache.redis.url": "redis://localhost" }

console.log(flatten(config, { bracket: true }));
// { "db[host]": "localhost", "db[port]": 5432, "cache[redis][url]": "redis://localhost" }

1.3 两种路径表示法对比

📌 记住： 键名可能包含点号时（如 "user.name.first" 作为整体键名），务必使用括号路径或转义处理，否则反扁平化会产生歧义。

🏗️ 二、反扁平化算法与边界处理

2.1 从路径还原嵌套结构

反扁平化（Unflatten）是扁平化的逆操作：给定一组路径键值对，还原为嵌套 JSON 对象。核心难点在于路径解析和类型推断——"server.port": "3000" 中的 "3000" 应该还原为数字还是保持字符串？

// JSON 反扁平化引擎 — 从路径键值对还原嵌套结构
function unflatten(obj, options = {}) {
  const { delimiter = ".", autoType = false } = options;
  const result = {};

  // 解析点号路径为键数组（处理引号包裹的特殊键名）
  function parsePath(key) {
    const parts = [];
    const regex = /([^.\[\]"']+)|\["([^"]*)"\]|\['([^']*)'\]|(\d+)/g;
    let match;
    while ((match = regex.exec(key)) !== null) {
      if (match[1] !== undefined) parts.push(match[1]);
      else if (match[2] !== undefined) parts.push(match[2]);
      else if (match[3] !== undefined) parts.push(match[3]);
      else if (match[4] !== undefined) parts.push(parseInt(match[4], 10));
    }
    return parts;
  }

  // 自动类型推断："3000" → 3000, "true" → true
  function inferType(value) {
    if (typeof value !== "string") return value;
    if (value === "true") return true;
    if (value === "false") return false;
    if (value === "null") return null;
    if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
      const num = Number(value);
      if (!Number.isNaN(num)) return num;
    }
    return value;
  }

  for (const [rawKey, rawValue] of Object.entries(obj)) {
    const keys = parsePath(rawKey);
    const value = autoType ? inferType(rawValue) : rawValue;

    let current = result;
    for (let i = 0; i < keys.length - 1; i++) {
      const nextKey = keys[i + 1];
      const nextIsIndex = typeof nextKey === "number";
      if (current[keys[i]] == null) current[keys[i]] = nextIsIndex ? [] : {};
      current = current[keys[i]];
    }
    current[keys[keys.length - 1]] = value;
  }
  return result;
}

// 测试
const flat = {
  "server.host": "localhost",
  "server.port": "3000",
  "server.database.primary.url": "postgres://...",
  "features.0": "auth",
  "features.1": "logging"
};

console.log(unflatten(flat, { autoType: true }));
// {
//   server: { host: "localhost", port: 3000, database: { primary: { url: "postgres://..." } } },
//   features: ["auth", "logging"]
// }

⚠️ 警告： autoType 自动推断有风险。如果一个值恰好是 "12345"（本意是字符串），会被错误转为数字。在安全敏感场景中，建议关闭 autoType，或使用 JSON Schema 做显式类型声明。

2.2 数组 vs 对象的歧义问题

反扁平化中最经典的陷阱：给定 {"a.0": "x", "a.b": "y"}，a 应该还原为数组还是对象？主流库处理策略不同：flat v6+ 优先对象（更安全），flatley 优先数组（会静默丢弃非数字键的数据）。

⚠️ 警告： 如果数据可能包含歧义（数组索引和字符串键混合），永远不要使用优先数组策略——它会静默丢弃数据。推荐优先对象策略或智能推断（统计子键类型，多数决）。

🚀 三、生产级优化与实战场景

3.1 循环引用检测

在生产环境中，JSON 数据可能来自不可信来源。如果对象包含循环引用，递归扁平化会导致栈溢出：

// 循环引用检测版扁平化
function flattenSafe(obj, options = {}) {
  const { delimiter = ".", maxDepth = 20 } = options;
  const result = new Map(); // 使用 Map 保持插入顺序
  const visited = new WeakSet(); // 循环引用检测

  function _flatten(value, path, depth) {
    if (depth > maxDepth) {
      result.set(path, "[Max Depth Exceeded]");
      return;
    }

    if (value === null || value === undefined || typeof value !== "object") {
      result.set(path, value);
      return;
    }

    // 循环引用检测
    if (visited.has(value)) {
      result.set(path, "[Circular Reference]");
      return;
    }
    visited.add(value);

    // 特殊对象类型
    if (value instanceof Date) { result.set(path, value.toISOString()); visited.delete(value); return; }
    if (value instanceof RegExp) { result.set(path, value.toString()); visited.delete(value); return; }

    if (Array.isArray(value)) {
      for (let i = 0; i < value.length; i++) {
        _flatten(value[i], path ? `${path}${delimiter}${i}` : `${i}`, depth + 1);
      }
    } else {
      for (const [k, v] of Object.entries(value)) {
        const newPath = path ? `${path}${delimiter}${k}` : k;
        _flatten(v, newPath, depth + 1);
      }
    }

    visited.delete(value); // 回溯时释放，允许同值不同引用
  }

  _flatten(obj, "", 0);
  return Object.fromEntries(result);
}

// 测试循环引用
const circular = { name: "root" };
circular.self = circular; // 循环引用
circular.children = [{ parent: circular }];

console.log(flattenSafe(circular));
// { "name": "root", "self": "[Circular Reference]", "children.0.parent": "[Circular Reference]" }

3.2 性能基准对比

在 Node.js 22.x 环境下，对一个 3 层嵌套、1000 个叶子节点的 JSON 对象进行扁平化测试：

⚠️ 警告： flat 库在 v5 → v6 的升级中有破坏性变更——默认不再展开数组。如果你的项目依赖 flat 的旧行为，升级后会出现静默 Bug。建议在 CI 中添加序列化快照测试。

3.3 真实场景：环境变量管理

JSON 扁平化最常见的场景——.env 文件只支持一维 KEY=VALUE，不支持嵌套。用双下划线 __ 作为分隔符可以安全地转换：

// JSON → 环境变量（用双下划线分隔，避免与键名中的点号冲突）
function jsonToEnv(obj, prefix = "APP") {
  const flat = flattenSafe(obj, { delimiter: "__" });
  const env = {};
  for (const [key, value] of Object.entries(flat)) {
    const envKey = `${prefix}__${key}`.toUpperCase().replace(/\./g, "__");
    env[envKey] = value === null ? "null" : String(value);
  }
  return env;
}

const config = { server: { port: 3000 }, db: { url: "postgres://localhost" } };
console.log(jsonToEnv(config));
// { "APP__SERVER__PORT": "3000", "APP__DB__URL": "postgres://localhost" }

Docker Compose、Kubernetes ConfigMap、GitHub Actions 都支持将 JSON 配置以扁平化键值对注入环境变量。反向还原时，用 unflatten + autoType 即可自动恢复类型。

3.4 真实场景：EAV 模型与搜索索引

EAV（Entity-Attribute-Value）模型常用于存储动态结构的 JSON 数据。将嵌套 JSON 扁平化后，每个叶子节点对应 EAV 表的一行记录（entity_id + attribute_path + value），适合 MySQL/PostgreSQL 的属性表存储。反向还原时，根据 value_type 列做类型转换后调用 unflatten 即可。

在 Elasticsearch 中，嵌套 JSON 会自动以 dot notation 展开为字段路径（如 server.database.primary.url），这本质上就是自动扁平化。理解扁平化算法有助于你设计合理的 ES 索引映射和查询 DSL。

💡 提示： 如果你的数据需要支持动态 Schema（用户自定义字段），EAV + JSON 扁平化是比 JSONB 更灵活的方案，但查询性能会下降。建议在 PostgreSQL 中用 JSONB + GIN 索引作为折中。

📋 四、避坑指南与最佳实践

4.1 常见陷阱

4.2 何时使用扁平化 vs 不使用

✅ 推荐使用扁平化的场景：

• 环境变量管理（Docker、K8s、CI/CD）
• 数据库 EAV 模型存储
• 前端表单数据提交（React Hook Form 等）
• 配置文件差异对比（Diff）
• 搜索引擎索引（Elasticsearch 的 dot.notation 字段）
• URL 查询参数序列化

❌ 不推荐使用扁平化的场景：

• API 响应数据（保持嵌套结构更清晰）
• 需要保留元信息的场景（数组长度、类型标记）
• 数据量超过 100MB 的超大 JSON（应使用流式处理）
• 需要 JSON Schema 验证的场景（Schema 是嵌套结构）

4.3 选型建议

💡 总结

JSON 扁平化/反扁平化看似简单，但生产环境中涉及循环引用、数组歧义、特殊字符键名等边界处理。核心要点：

• ⚡ 关键结论： 选型优先考虑安全性（循环引用检测、歧义处理），而非性能。1000 节点的扁平化耗时不到 1ms，性能差异可忽略不计。
• ✅ 点号路径适合配置管理和环境变量，括号路径适合前端表单处理
• ⚠️ 反扁平化的数组/对象歧义是最容易出 Bug 的地方，建议用智能推断策略
• 📌 永远对不可信数据做循环引用检测

相关工具推荐：

• jsjson.com JSON 格式化工具 — 在线 JSON 格式化与校验
• jsjson.com JSON 对比工具 — 对比扁平化前后的差异
• flat npm 包 — 最流行的 JSON 扁平化库
• lodash.set / lodash.get — 用路径访问嵌套对象属性