JSON 格式化完全指南：从入门到精通

前年我们对接一个第三方支付回调，联调了整整三天才发现问题：我们这边字段全是 orderId、payTime 这种 camelCase，对方文档里写的却是 order_id、pay_time。两边各写各的，谁也没去翻对方的样例报文，结果就是回调进来字段全取成 undefined，订单状态死活不更新。最后排查到根因，会议室里还为「到底该 camelCase 还是 snake_case」吵了半小时——其实争的根本不是技术，是没人在动手前把约定定下来。

那次之后我对 JSON 的理解变了。格式化、缩进这些是表面功夫，真正会让你加班的是约定：字段怎么命名、空值用 null 还是干脆不返回、日期写时间戳还是 ISO 字符串。这篇就按我自己踩过的顺序，从格式化基础讲到这些 API 约定里的暗坑。如果你也常和接口、配置文件打交道，应该能对上不少号。

为什么需要 JSON 格式化？

在实际开发中，我遇到过无数次这样的场景：

真实案例 1：调试微信小程序 API

去年在开发一个电商小程序时，后端返回的订单数据是这样的：

{
  "code": 0,
  "data": {
    "orderId": "202601071234567",
    "items": [
      { "productId": "P001", "name": "iPhone 15 Pro", "price": 7999, "quantity": 1 },
      { "productId": "P002", "name": "AirPods Pro 2", "price": 1899, "quantity": 2 }
    ],
    "totalAmount": 11797,
    "status": "pending"
  }
}

这一大串压缩的 JSON 根本没法看！使用格式化工具后：

{
  "code": 0,
  "data": {
    "orderId": "202601071234567",
    "items": [
      {
        "productId": "P001",
        "name": "iPhone 15 Pro",
        "price": 7999,
        "quantity": 1
      },
      {
        "productId": "P002",
        "name": "AirPods Pro 2",
        "price": 1899,
        "quantity": 2
      }
    ],
    "totalAmount": 11797,
    "status": "pending"
  }
}

立刻就能看出数据结构，发现 totalAmount 计算错误（应该是 11797，实际返回的是对的，但如果错了就能一眼看出）。

节省时间：从 10 分钟手动查找缩短到 30 秒定位问题。

API JSON 约定：四个最容易扯皮的点

格式化能解决「看不清」，但解决不了「双方理解不一致」。下面这张表是我从几次联调事故里攒出来的——每一行背后都有一次返工。前后端、或者跟第三方对接前，最好先把这几栏在文档里钉死，别等报文进来再吵。

约定项	常见分歧	踩过的坑	我的倾向
字段命名	camelCase vs snake_case	两边各写各的，字段全取成 `undefined`	全链路统一一种，写进接口规范第一条
空值表达	返回 `null` vs 直接不返回这个字段	前端 `obj.addr.city` 直接报 `cannot read of null`	可选字段宁可缺字段，也别给一堆 `null`
日期格式	时间戳(秒/毫秒) vs ISO 字符串	秒当毫秒用，时间差了 1970 年	对外一律 ISO 8601，少踩时区的坑
数字类型	大整数 ID 用 number vs string	JS `Number` 精度丢失，订单号末尾变 `000`	超过 16 位的 ID 一律按字符串传

最后这条「大整数精度」特别阴险，平时小 ID 都正常，等业务跑久了 ID 涨到 19 位，末几位悄悄变 0，根本不报错。这种坑光靠格式化看不出来，得靠约定提前拦住。

JSON 格式化的核心原理

1. 缩进规则

标准的 JSON 格式化使用 2 个空格 或 4 个空格 作为缩进。为什么？

// 2 空格缩进（推荐）
{
  "user": {
    "name": "张三",
    "age": 28
  }
}

// 4 空格缩进
{
    "user": {
        "name": "张三",
        "age": 28
    }
}

我的建议：

前端项目：2 空格（节省屏幕空间）
后端项目：4 空格（更易阅读）
团队协作：统一使用 .editorconfig 配置

2. 换行策略

对象和数组的换行有讲究：

// ✅ 推荐：每个属性一行
{
  "name": "张三",
  "age": 28,
  "skills": ["JavaScript", "Python", "Go"]
}

// ❌ 不推荐：所有属性在一行
{"name":"张三","age":28,"skills":["JavaScript","Python","Go"]}

// ⚠️ 特殊情况：简单数组可以一行
{
  "coordinates": [120.15, 30.28]
}

3. 键值对排序

虽然 JSON 规范不要求键的顺序，但排序后更易维护：

// 按字母排序
{
  "age": 28,
  "email": "zhang@example.com",
  "name": "张三"
}

// 按重要性排序（推荐）
{
  "name": "张三",
  "age": 28,
  "email": "zhang@example.com"
}

常见的 JSON 格式化错误

错误 1：尾随逗号

// ❌ 错误：最后一项有逗号
{
  "name": "张三",
  "age": 28,  // ← 这个逗号会导致解析失败
}

// ✅ 正确
{
  "name": "张三",
  "age": 28
}

为什么会犯这个错误？ JavaScript 对象允许尾随逗号，但 JSON 不允许。很多开发者混淆了两者。

错误 2：使用单引号

// ❌ 错误
{
  'name': '张三'
}

// ✅ 正确
{
  "name": "张三"
}

错误 3：注释

// ❌ 错误：JSON 不支持注释
{
  "name": "张三",  // 用户姓名
  "age": 28
}

// ✅ 正确：使用特殊字段存储注释
{
  "_comment": "用户基本信息",
  "name": "张三",
  "age": 28
}

性能优化技巧

1. 大文件处理

处理超过 10MB 的 JSON 文件时：

// ❌ 不推荐：一次性加载
const data = JSON.parse(hugeJsonString);

// ✅ 推荐：流式处理
const stream = fs.createReadStream('huge.json');
const parser = JSONStream.parse('*');
stream.pipe(parser);
parser.on('data', (chunk) => {
  // 处理每个数据块
});

2. 压缩 vs 格式化

什么时候压缩，什么时候格式化？

场景	建议	原因
生产环境 API	压缩	减少网络传输
开发环境调试	格式化	便于阅读
配置文件	格式化	便于维护
日志存储	压缩	节省空间

3. 在线工具 vs 本地工具

在线工具的问题：

数据上传到第三方服务器（隐私风险）
依赖网络连接
大文件处理慢

本地工具的优势（如我们的 JSON 格式化工具）：

✅ 数据不离开浏览器，100% 隐私安全
✅ 毫秒级响应，无需等待
✅ 支持离线使用
✅ 无文件大小限制（取决于浏览器内存）

实战案例分析

案例 1：API 响应调试

场景：电商网站的商品搜索 API 返回异常

原始响应：

{
  "status": "success",
  "data": {
    "products": [
      { "id": 1, "name": "iPhone 15", "price": 5999, "stock": 0 },
      { "id": 2, "name": "iPad Pro", "price": 6799, "stock": 15 }
    ],
    "total": 2
  }
}

格式化后发现问题：

{
  "status": "success",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "iPhone 15",
        "price": 5999,
        "stock": 0 // ← 库存为 0，但前端仍显示"可购买"
      },
      {
        "id": 2,
        "name": "iPad Pro",
        "price": 6799,
        "stock": 15
      }
    ],
    "total": 2
  }
}

解决方案：

// 前端添加库存检查
if (product.stock > 0) {
  showBuyButton();
} else {
  showOutOfStockLabel();
}

案例 2：配置文件迁移

场景：将旧项目的配置从 XML 迁移到 JSON

步骤：

使用工具将 XML 转换为 JSON
格式化 JSON，检查数据结构
手动调整不合理的嵌套
验证所有配置项

迁移前（XML）：

<config>
  <database>
    <host>localhost</host>
    <port>3306</port>
  </database>
</config>

迁移后（JSON）：

{
  "config": {
    "database": {
      "host": "localhost",
      "port": 3306
    }
  }
}

进阶技巧

1. JSON Schema 验证

使用 JSON Schema 确保数据格式正确：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name", "age"]
}

2. 自定义格式化规则

根据项目需求自定义格式化：

// 自定义缩进
JSON.stringify(data, null, 2); // 2 空格

// 自定义替换函数
JSON.stringify(
  data,
  (key, value) => {
    if (typeof value === 'number') {
      return value.toFixed(2); // 数字保留两位小数
    }
    return value;
  },
  2
);

3. 大数据优化

处理包含数百万条记录的 JSON：

// 使用 Web Worker 避免阻塞主线程
const worker = new Worker('json-formatter-worker.js');
worker.postMessage({ json: hugeJsonString });
worker.onmessage = (e) => {
  console.log('格式化完成:', e.data);
};

工具推荐

在线工具

ToolsForge JSON 格式化 - 本地运行，隐私安全
JSONLint - 经典的在线验证工具
JSON Editor Online - 可视化编辑

编辑器插件

VS Code: Prettier
Sublime Text: Pretty JSON
Vim: vim-json

命令行工具

# jq - 强大的 JSON 处理工具
cat data.json | jq '.'

# Python 自带
python -m json.tool data.json

# Node.js
node -e "console.log(JSON.stringify(require('./data.json'), null, 2))"

最佳实践总结

开发环境：始终使用格式化的 JSON
生产环境：使用压缩的 JSON
版本控制：配置文件使用格式化的 JSON
API 设计：提供 ?pretty=true 参数支持格式化输出
错误处理：使用 try-catch 包裹 JSON.parse
性能优化：大文件使用流式处理
安全性：避免使用 eval()，始终使用 JSON.parse()

常见问题 FAQ

Q: JSON 和 JavaScript 对象有什么区别？

A: 主要区别：

JSON 的键必须用双引号
JSON 不支持函数、undefined、Symbol
JSON 不支持注释
JSON 不支持尾随逗号

Q: 如何处理循环引用？

A: JSON 不支持循环引用，需要手动处理：

const obj = { name: 'test' };
obj.self = obj; // 循环引用

// 使用自定义替换函数
const seen = new WeakSet();
JSON.stringify(obj, (key, value) => {
  if (typeof value === 'object' && value !== null) {
    if (seen.has(value)) {
      return '[Circular]';
    }
    seen.add(value);
  }
  return value;
});

Q: 如何美化已经压缩的 JSON？

A: 使用我们的 JSON 格式化工具，或者：

const formatted = JSON.stringify(JSON.parse(compressedJson), null, 2);

总结

写到这我得说句可能不太讨喜的话：JSON 不支持注释，在我看来是个实打实的设计缺陷。配置文件这种东西天生需要注释——某个开关为什么打开、某个超时为什么设成 30 秒，不写明白半年后没人敢动。所以纯配置我现在尽量不用 JSON，能上 YAML 就上 YAML，退一步用 JSON5 也行，至少能写注释、能留尾随逗号。JSON 我只让它干一件事：当数据在系统之间传输的载体。

至于团队协作，真正的顺序是「先统一约定，再写代码」，而不是反过来。命名用 camelCase 还是 snake_case、日期怎么传、可选字段缺还是给 null——这些早一天在文档里钉死，就少一次联调时对着报文干瞪眼。技术分歧大多不值得吵，吵的往往是没人拍板。

工具层面，我自己日常就是把可疑的接口返回直接丢进在线 JSON 格式化工具看结构，纯浏览器本地跑，数据不上传，带着公司内网的报文也不慌。

就先聊到这。你们团队是 camelCase 派还是 snake_case 派，欢迎来评论区对线。

相关文章：

工具推荐：

关于作者

ToolsForge 团队

我们是一支开发者小团队，负责构建和维护 ToolsForge —— 150+ 个完全在浏览器本地运行、隐私优先的工具。这些文章来自我们日常的工程实践，而不是纸上谈兵。

了解我们

JSON 格式化完全指南：从入门到精通

为什么需要 JSON 格式化？

在实际开发中，我遇到过无数次这样的场景：

真实案例 1：调试微信小程序 API

去年在开发一个电商小程序时，后端返回的订单数据是这样的：

{
  "code": 0,
  "data": {
    "orderId": "202601071234567",
    "items": [
      { "productId": "P001", "name": "iPhone 15 Pro", "price": 7999, "quantity": 1 },
      { "productId": "P002", "name": "AirPods Pro 2", "price": 1899, "quantity": 2 }
    ],
    "totalAmount": 11797,
    "status": "pending"
  }
}

这一大串压缩的 JSON 根本没法看！使用格式化工具后：

{
  "code": 0,
  "data": {
    "orderId": "202601071234567",
    "items": [
      {
        "productId": "P001",
        "name": "iPhone 15 Pro",
        "price": 7999,
        "quantity": 1
      },
      {
        "productId": "P002",
        "name": "AirPods Pro 2",
        "price": 1899,
        "quantity": 2
      }
    ],
    "totalAmount": 11797,
    "status": "pending"
  }
}

立刻就能看出数据结构，发现 totalAmount 计算错误（应该是 11797，实际返回的是对的，但如果错了就能一眼看出）。

节省时间：从 10 分钟手动查找缩短到 30 秒定位问题。

API JSON 约定：四个最容易扯皮的点

约定项	常见分歧	踩过的坑	我的倾向
字段命名	camelCase vs snake_case	两边各写各的，字段全取成 `undefined`	全链路统一一种，写进接口规范第一条
空值表达	返回 `null` vs 直接不返回这个字段	前端 `obj.addr.city` 直接报 `cannot read of null`	可选字段宁可缺字段，也别给一堆 `null`
日期格式	时间戳(秒/毫秒) vs ISO 字符串	秒当毫秒用，时间差了 1970 年	对外一律 ISO 8601，少踩时区的坑
数字类型	大整数 ID 用 number vs string	JS `Number` 精度丢失，订单号末尾变 `000`	超过 16 位的 ID 一律按字符串传

JSON 格式化的核心原理

1. 缩进规则

标准的 JSON 格式化使用 2 个空格 或 4 个空格 作为缩进。为什么？

// 2 空格缩进（推荐）
{
  "user": {
    "name": "张三",
    "age": 28
  }
}

// 4 空格缩进
{
    "user": {
        "name": "张三",
        "age": 28
    }
}

我的建议：

前端项目：2 空格（节省屏幕空间）
后端项目：4 空格（更易阅读）
团队协作：统一使用 .editorconfig 配置

2. 换行策略

对象和数组的换行有讲究：

// ✅ 推荐：每个属性一行
{
  "name": "张三",
  "age": 28,
  "skills": ["JavaScript", "Python", "Go"]
}

// ❌ 不推荐：所有属性在一行
{"name":"张三","age":28,"skills":["JavaScript","Python","Go"]}

// ⚠️ 特殊情况：简单数组可以一行
{
  "coordinates": [120.15, 30.28]
}

3. 键值对排序

虽然 JSON 规范不要求键的顺序，但排序后更易维护：

// 按字母排序
{
  "age": 28,
  "email": "zhang@example.com",
  "name": "张三"
}

// 按重要性排序（推荐）
{
  "name": "张三",
  "age": 28,
  "email": "zhang@example.com"
}

常见的 JSON 格式化错误

错误 1：尾随逗号

// ❌ 错误：最后一项有逗号
{
  "name": "张三",
  "age": 28,  // ← 这个逗号会导致解析失败
}

// ✅ 正确
{
  "name": "张三",
  "age": 28
}

为什么会犯这个错误？ JavaScript 对象允许尾随逗号，但 JSON 不允许。很多开发者混淆了两者。

错误 2：使用单引号

// ❌ 错误
{
  'name': '张三'
}

// ✅ 正确
{
  "name": "张三"
}

错误 3：注释

// ❌ 错误：JSON 不支持注释
{
  "name": "张三",  // 用户姓名
  "age": 28
}

// ✅ 正确：使用特殊字段存储注释
{
  "_comment": "用户基本信息",
  "name": "张三",
  "age": 28
}

性能优化技巧

1. 大文件处理

处理超过 10MB 的 JSON 文件时：

// ❌ 不推荐：一次性加载
const data = JSON.parse(hugeJsonString);

// ✅ 推荐：流式处理
const stream = fs.createReadStream('huge.json');
const parser = JSONStream.parse('*');
stream.pipe(parser);
parser.on('data', (chunk) => {
  // 处理每个数据块
});

2. 压缩 vs 格式化

什么时候压缩，什么时候格式化？

场景	建议	原因
生产环境 API	压缩	减少网络传输
开发环境调试	格式化	便于阅读
配置文件	格式化	便于维护
日志存储	压缩	节省空间

3. 在线工具 vs 本地工具

在线工具的问题：

数据上传到第三方服务器（隐私风险）
依赖网络连接
大文件处理慢

本地工具的优势（如我们的 JSON 格式化工具）：

✅ 数据不离开浏览器，100% 隐私安全
✅ 毫秒级响应，无需等待
✅ 支持离线使用
✅ 无文件大小限制（取决于浏览器内存）

实战案例分析

案例 1：API 响应调试

场景：电商网站的商品搜索 API 返回异常

原始响应：

{
  "status": "success",
  "data": {
    "products": [
      { "id": 1, "name": "iPhone 15", "price": 5999, "stock": 0 },
      { "id": 2, "name": "iPad Pro", "price": 6799, "stock": 15 }
    ],
    "total": 2
  }
}

格式化后发现问题：

{
  "status": "success",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "iPhone 15",
        "price": 5999,
        "stock": 0 // ← 库存为 0，但前端仍显示"可购买"
      },
      {
        "id": 2,
        "name": "iPad Pro",
        "price": 6799,
        "stock": 15
      }
    ],
    "total": 2
  }
}

解决方案：

// 前端添加库存检查
if (product.stock > 0) {
  showBuyButton();
} else {
  showOutOfStockLabel();
}

案例 2：配置文件迁移

场景：将旧项目的配置从 XML 迁移到 JSON

步骤：

使用工具将 XML 转换为 JSON
格式化 JSON，检查数据结构
手动调整不合理的嵌套
验证所有配置项

迁移前（XML）：

<config>
  <database>
    <host>localhost</host>
    <port>3306</port>
  </database>
</config>

迁移后（JSON）：

{
  "config": {
    "database": {
      "host": "localhost",
      "port": 3306
    }
  }
}

进阶技巧

1. JSON Schema 验证

使用 JSON Schema 确保数据格式正确：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name", "age"]
}

2. 自定义格式化规则

根据项目需求自定义格式化：

// 自定义缩进
JSON.stringify(data, null, 2); // 2 空格

// 自定义替换函数
JSON.stringify(
  data,
  (key, value) => {
    if (typeof value === 'number') {
      return value.toFixed(2); // 数字保留两位小数
    }
    return value;
  },
  2
);

3. 大数据优化

处理包含数百万条记录的 JSON：

// 使用 Web Worker 避免阻塞主线程
const worker = new Worker('json-formatter-worker.js');
worker.postMessage({ json: hugeJsonString });
worker.onmessage = (e) => {
  console.log('格式化完成:', e.data);
};

工具推荐

在线工具

ToolsForge JSON 格式化 - 本地运行，隐私安全
JSONLint - 经典的在线验证工具
JSON Editor Online - 可视化编辑

编辑器插件

VS Code: Prettier
Sublime Text: Pretty JSON
Vim: vim-json

命令行工具

# jq - 强大的 JSON 处理工具
cat data.json | jq '.'

# Python 自带
python -m json.tool data.json

# Node.js
node -e "console.log(JSON.stringify(require('./data.json'), null, 2))"

最佳实践总结

开发环境：始终使用格式化的 JSON
生产环境：使用压缩的 JSON
版本控制：配置文件使用格式化的 JSON
API 设计：提供 ?pretty=true 参数支持格式化输出
错误处理：使用 try-catch 包裹 JSON.parse
性能优化：大文件使用流式处理
安全性：避免使用 eval()，始终使用 JSON.parse()

常见问题 FAQ

Q: JSON 和 JavaScript 对象有什么区别？

A: 主要区别：

JSON 的键必须用双引号
JSON 不支持函数、undefined、Symbol
JSON 不支持注释
JSON 不支持尾随逗号

Q: 如何处理循环引用？

A: JSON 不支持循环引用，需要手动处理：

const obj = { name: 'test' };
obj.self = obj; // 循环引用

// 使用自定义替换函数
const seen = new WeakSet();
JSON.stringify(obj, (key, value) => {
  if (typeof value === 'object' && value !== null) {
    if (seen.has(value)) {
      return '[Circular]';
    }
    seen.add(value);
  }
  return value;
});

Q: 如何美化已经压缩的 JSON？

A: 使用我们的 JSON 格式化工具，或者：

const formatted = JSON.stringify(JSON.parse(compressedJson), null, 2);

总结

工具层面，我自己日常就是把可疑的接口返回直接丢进在线 JSON 格式化工具看结构，纯浏览器本地跑，数据不上传，带着公司内网的报文也不慌。

就先聊到这。你们团队是 camelCase 派还是 snake_case 派，欢迎来评论区对线。

相关文章：

工具推荐：

关于作者

ToolsForge 团队

了解我们

JSON 格式化完全指南：从入门到精通

JSON 格式化完全指南：从入门到精通

为什么需要 JSON 格式化？

真实案例 1：调试微信小程序 API

API JSON 约定：四个最容易扯皮的点

JSON 格式化的核心原理

1. 缩进规则

2. 换行策略

3. 键值对排序

常见的 JSON 格式化错误

错误 1：尾随逗号

错误 2：使用单引号

错误 3：注释

性能优化技巧

1. 大文件处理

2. 压缩 vs 格式化

3. 在线工具 vs 本地工具

实战案例分析

案例 1：API 响应调试

案例 2：配置文件迁移

进阶技巧

1. JSON Schema 验证

2. 自定义格式化规则

3. 大数据优化

工具推荐

在线工具

编辑器插件

命令行工具

最佳实践总结

常见问题 FAQ

总结

相关阅读

JSON数据处理实战指南：格式化、验证与转换

一张照片能做多少事：AI 改图工具实战指南

把脸保住：AI 改图提示词怎么写才不"换人"

JSON 格式化完全指南：从入门到精通

JSON 格式化完全指南：从入门到精通

为什么需要 JSON 格式化？

真实案例 1：调试微信小程序 API

API JSON 约定：四个最容易扯皮的点

JSON 格式化的核心原理

1. 缩进规则

2. 换行策略

3. 键值对排序

常见的 JSON 格式化错误

错误 1：尾随逗号

错误 2：使用单引号

错误 3：注释

性能优化技巧

1. 大文件处理

2. 压缩 vs 格式化

3. 在线工具 vs 本地工具

实战案例分析

案例 1：API 响应调试

案例 2：配置文件迁移

进阶技巧

1. JSON Schema 验证

2. 自定义格式化规则

3. 大数据优化

工具推荐

在线工具

编辑器插件

命令行工具

最佳实践总结

常见问题 FAQ

总结

相关阅读

JSON数据处理实战指南：格式化、验证与转换

一张照片能做多少事：AI 改图工具实战指南

把脸保住：AI 改图提示词怎么写才不"换人"