yeonghyeon · 2026年4月15日

什么是 JSON？写给非开发者店主的入门指南

您好，我是 yeonghyeon，负责 3Min API 的开发。

在上一篇 API 篇里，我说"API 就是以约定好的地址收发约定好形状消息的窗口"。当时特意把"消息的形状"留到了后面——今天就是那块最后的拼图。这篇要讲的，就是在器（数据库）和通道（API）之间真正往来的"消息"到底长什么样，也就是 JSON。

📚 写给非开发者的数据基础三部曲

数据库 — 装数据的器
API — 安全进出的窗口
JSON — 往来消息的形状（当前文章）

今天文章的目标不是"背下语法"。只要能达到"我可以把自己生意里的一件事写成一块 JSON"这种感觉，就够了。一旦有了这个感觉，以后和开发者、和 AI 对话时，彼此的语言就拉近了一大步。不需要任何前置知识。

什么是 JSON

先看一眼词典式的定义。维基百科把 JSON（JavaScript Object Notation）描述为"一种使用人类可读文本来表示由属性-值对和数组组成的数据对象的开放标准文件格式"。

用一句话收一下：

JSON = 按照约定的写法，把系统之间要交换的数据记下来的一段文本，人眼也能读得懂。

其实系统之间交换消息的方式不止 JSON 一种，还有 XML、YAML、Protocol Buffers 等等。那为什么今天的 Web API 几乎都选 JSON？原因很朴素：人能看懂，程序也能看懂，两头都直观。开发者用记事本打开就能读，服务器解析起来也很快。同时把这两件事做好的格式，并不多见。

为什么需要"约定好的形状"

在前两篇里，我们已经有了器（DB）和通道（API）这两样工具。可是光有工具，数据并不会自己流起来。如果每个来到窗口的人都拿张不同的纸、随便写点什么递进去，柜员连一件都处理不了。

所以银行会提前准备好制式表单——存款单、取款单、汇款申请单。表单一致，柜员才能快速核对，记录也才能自动留下。API 也是出于一模一样的理由：它提前把"进这个窗口的消息应该长这样"这条约定固定下来。把那种"形状"写出来的标准语法，就是 JSON。

JSON 成为事实标准之前，每个系统都自己一套消息格式。有的用逗号分隔的一行文本，有的用层层标签包起来的 XML，有的做一套只写在内部文档里的二进制格式。每接一个新的合作方，就要翻一轮文档、再写一遍解析代码。JSON 成了事实标准之后，"我们用 JSON 往来吧"这一句话，就能把大部分协作启动起来。

用 Excel 来理解 JSON

在直接看 JSON 语法之前，先从大家熟悉的 Excel 起步。想象一张 Excel 表：最上面一行是列名（商品名、数量、金额……），下面每一行代表一行就是一笔交易。

把这个结构原样搬到 JSON，对应得非常自然：

Excel 的列名 → JSON 的键（key）
一格里填的值 → JSON 的值（value）
Excel 的一行 → JSON 的一个对象（{}）
Excel 的多行 → JSON 的数组（[]）

假设订单表的一行长这样：

order_id	product	quantity	amount
A-2026-0001	Château Margaux 2020	2	480000

把这一行原样挪到 JSON 对象里，就是这样：

{
  "order_id": "A-2026-0001",
  "product": "Château Margaux 2020",
  "quantity": 2,
  "amount": 480000
}

名字后面一个冒号，项目之间一个逗号，外面用一对大括号包起来。规则就这么些。这一块就是装了跟 Excel 一行完全相同的信息的 JSON 对象。

那既然有 Excel，为什么还单独需要 JSON？差别在层级和灵活度两处。Excel 的一个格子里很难再塞一张表，而且行与行的列一旦不一致，管理马上就乱。JSON 则可以很自然地在值的位置再放进一个对象或数组，每一单可能不同的选项字段也能轻松装进去。如果说 Excel 像一本"平铺的账本"，JSON 就像一本"需要的时候能像文件夹一样折起来的账本"。

葡萄酒店店主的订单单

接着上一篇的场景继续。网店里新来了一笔订单。门店 POS 和合作餐厅也都看着同一个数据库，中间的通道就是 API。那我们现在就看看，真正飞到这个 API 窗口的消息到底是什么样。

网店给葡萄酒店的"创建订单 API"发来这么一块 JSON：

{
  "order_id": "A-2026-0412",
  "customer": {
    "id": "C-00871",
    "name": "Alex",
    "email": "alex@example.com"
  },
  "items": [
    {
      "sku": "WINE-MARGAUX-2020",
      "name": "Château Margaux 2020",
      "quantity": 2,
      "unit_price": 240000
    },
    {
      "sku": "WINE-OPUS-2019",
      "name": "Opus One 2019",
      "quantity": 1,
      "unit_price": 520000
    }
  ],
  "total_amount": 1000000,
  "ordered_at": "2026-04-15T14:23:00+09:00"
}

这一块里头，谁（customer）、买了什么（items）、花了多少（total_amount）、什么时候买的（ordered_at），全齐了。之前说的"不是平铺账本，是能折起来的账本"是什么意思，在这儿一眼就能看出来：顾客是一个带了自己明细（姓名、邮箱）的小块，购买的商品是一份两条的清单。如果用 Excel，这些信息得分别记在顾客表、订单表、订单明细表里；现在它们清清爽爽装在一个信封里。

API 窗口接到这个信封的第一件事，就是检查它是不是"约定好的形状"。order_id 空着、quantity 里塞了不是数字的东西、customer 里面少了 email——只要有任何一条不对，当场就拒收。这样一来，数据库里堆起来的订单永远是同一个形状，以后要拉统计、或者导到别的系统里，都不会手忙脚乱。

支付完成以后，支付公司又会往葡萄酒店另一个窗口送回一块 JSON，说"这单支付成功了"。像这种由对方系统先来告诉我们的方式，上一篇里提过，有个专门的名字叫 Webhook。Webhook 的正文也是 JSON。请求是 JSON，响应是 JSON，通知还是 JSON。系统之间来来往往的消息几乎全是同一种格式——正是这一点，让今天的互联网跑得这么顺。

JSON 语法：键、值、对象、数组

下面把语法非常简短地梳理一下。JSON 的规则少得让人吃惊。下面这四条记住，您就能读懂 99% 的 JSON 了。

1) 键-值对 — 最小单元

最基本的，就是把"名字"和"内容"用一个冒号串起来的一对。名字必须用双引号括起来。

"product": "Château Margaux 2020"

2) 值的种类 — 四种基础 + 两种结构

能放在"值"这个位置上的东西是定好的：

字符串：用双引号括起来的文字。例如："Alex"
数字：不加引号，直接写。例如：480000
布尔：true 或 false（不加引号）
空：null（表示"现在还没值"）
对象：用大括号 {} 包起来的一组键-值
数组：用方括号 [] 包起来的一串值

3) 对象 {} — 一束键-值

把几对键-值用逗号拼起来，外面再套一对大括号，就是一个对象。Excel 的一行就对应这样的一个对象。

{
  "name": "Alex",
  "email": "alex@example.com",
  "is_member": true
}

4) 数组 [] — 相同形状的并列

把若干个值用逗号并列起来，外面套一对方括号，就是数组。Excel 的多行就对应这样的一个数组。

[
  { "sku": "WINE-MARGAUX-2020", "quantity": 2 },
  { "sku": "WINE-OPUS-2019",    "quantity": 1 }
]

接下来这一点才是真正关键。您大概注意到了：刚才那个数组里的每个元素，本身又是一个对象。值的位置，既可以再放一个对象，也可以再放一个数组。就凭这一条递归规则，JSON 就能装下任意复杂的信息。葡萄酒店那张订单单之所以能写出"一单里有好几样商品，每样商品里又有名字、数量、单价……"这种结构，靠的就是这个。

用三层堆叠的立体方块表现 JSON 层级结构的示意图。最底层是 Nested Pairs（嵌套的键-值对），中间层是 Objects & Array（对象与数组），最上层是 Root Object（最外层对象），直观展示「小单元层层汇聚成更大结构」的 JSON 递归层级

一句话总结一下 JSON：键-值是最基本的一对，可以把若干对打包成对象，也可以把若干对象并列成数组。再加上值的位置还能再放进对象或数组。一整套语法其实就这一句话。

JSON 都用在哪里

除了葡萄酒店那张订单单，JSON 其实早已深深嵌进我们的日常生活，只是不显眼罢了：

手机 App 和服务器之间的通信：Instagram 的信息流、外卖 App 的店铺列表、股票 App 的行情 —— 几乎全是 JSON 在来回跑。
配置文件：VS Code 的设置，以及很多开发工具的配置文件，都是 JSON 格式。选 JSON 就是为了让人类自己能打开、自己改。
公共数据、开放数据：政府和公共机构开放出来的数据 API，相当一部分都用 JSON 回应。
SaaS 对接和 Webhook：支付公司、物流公司、消息平台、邮件服务发过来的通知，也都是一块 JSON。
AI / LLM 的结构化输出：让 ChatGPT、Claude 这类模型"结果按 JSON 给我"，它会返回一份可以直接拿来用的结构。JSON 同时也是 AI 与业务系统之间的通用语言。

有一件事千万别搞错：JSON 不是"格式随你写的资料"。恰恰相反。正如 Chae-won 在前一篇您的数据值得一个计划里强调的那样，JSON 真正发挥作用，靠的是事先把"这个接口的 JSON 有哪些字段"这个约定讲清楚。自由的是语法，字段设计并不自由。只要记住这个差别，围绕 JSON 的多数误解就会一扫而空。

到目前为止的整理 · 系列收尾

把三部曲放到一起总结一下：

第 1 篇：数据库 — 搭了一个把业务数据以同样形状堆起来的器。
第 2 篇：API — 给这个器搭了一个让外部能安全进出的通道（窗口）。
第 3 篇：JSON — 把这个窗口之间来往的消息的形状定了下来。

这三件事一齐到位的那一刻，您的生意第一次长出了就算人不在身边也能自己跑的系统的雏形。网店来了订单，一块 JSON 经过 API 窗口进到 DB；支付公司用一块 JSON 告诉我们结果；门店 POS 用一块 JSON 去减库存。店主睡觉的时候，这些消息也在同一套约定上悄悄地来回跑。"自动化"这三个字的真相，最后落到底就是这三个约定的组合。

更重要的是，只要把这三个概念拿稳了，以后碰到的所有新名词（GraphQL、事件流、MCP、AI Agent……），都不过是叠在这套骨架上的变体而已。骨架立住了，枝叶很快就会跟上。

今天就能动手试的事

既然是系列的最后一篇，今天的练习也设计成能和前两篇连起来。一张纸、一个 AI、一个浏览器，就够了。

Action 1. 把自己生意里的一件事写成 JSON

把您在上一篇 API 篇里挑出来的那件事（比如：下单、登记预约、收问询）拿出来。把里面涉及到的项目，一项一项挪到同一块 JSON 里就行。刚开始写成平铺的也没关系；熟了之后，把像顾客、商品这些会"膨胀起来"的地方折成对象里的对象。

{
  "reservation_id": "R-2026-0001",
  "customer": {
    "name": "Alex",
    "phone": "+86-138-xxxx-xxxx"
  },
  "date": "2026-05-12",
  "party_size": 4,
  "note": "希望靠窗座位"
}

这一块，就是把"我生意里的一件事"搬成系统能看懂的样子的结果。开发者写 API 规格的时候，也是从这一步开始的。

Action 2. 用 AI 和校验网站检查一下语法

把 Action 1 写好的 JSON 贴进 ChatGPT、Claude、Gemini 之类的 AI 里，用类似下面这段话请它帮忙检查：

请帮我检查下面的 JSON 在语法上是否正确。
看看有没有拼写错误、引号、逗号、大括号或方括号是否对得上，
并用非开发者也能看懂的话，告诉我要怎么修。

[把 Action 1 的 JSON 贴在这里]

如果还想再用眼睛复核一遍，把同一段 JSON 贴到 JSONLint 这种公开校验网站里就可以。看到绿色的 "Valid JSON"，语法这一关就算过了。哪怕只是反复做这两步，对 JSON 的眼力都会长得很快。

Action 3. 在自己的接口上故意把格式弄坏

上一篇 API 篇的快速入门里，应该有不少朋友已经在 3Min API 里做出了第一个接口。今天就请回到那个接口的详情页，对着同一个接口做两个小实验：

改一下字段结构 — 加一个必填字段，或者把某个字段改个名字，然后用新的 JSON 形状再调一次，看看能不能正常存下。
故意发一个坏掉的 JSON 过去 — 漏一个逗号，把必填字段留空，或者把本该是数字的地方塞进文字，再调一次。关键是要亲眼看到 API 窗口是用什么样的错误回过来的。

这些返回的错误消息是什么意思、该怎么处理，都整理在故障排查指南里了。从"一看到错误就慌"变成"看着错误码去缩小原因范围"的那一刻，您就已经学会了跟系统对话的语言。

👉 还没有接口？— 3 分钟快速入门

三部曲落幕 — 接下来您想走向哪里

读到这里，您手上已经握着三样工具：装业务数据的器、让外部安全进出的通道、以及在通道里来往的消息的形状。当然这三个主题里，还有更深的细节可以继续挖。但仅凭今天这个程度的理解，已经足以搭起一副骨架——让您的生意能走到更大的 IT 生态里去，甚至为 AI 时代做好准备。剩下的细节，等到需要的时候再往骨架上叠就行。

读到这里您可能会想："这不是开发者的活儿吗？"其实这几年，因为 AI 的缘故，开发者和非开发者之间的边界已经比以前模糊得多。我劝的不是您自己去写代码，而是请您把IT 运转的核心原理当作一种直觉收在手边。在这种直觉之上，再借助各种好工具的力量，就会开始一个循环：做一个小接口，调它一下，撞上错误，再改一改。这个循环一旦累积起来，"我生意里这一块其实也能自动化"这种念头就会自然浮出来。这种感觉，正是把生意推向更大市场的起点。

等骨架一立，还会遇到一件挺有趣的事。您最近听得最多的那些自动化工具，比如 n8n、Zapier、Make，打开看一眼就能发现：它们都跑在同一套API + JSON + DB骨架上。"往 Google 表格里加一行"不过是在调用 Google 提供的 Sheets API；"用 Gmail 发邮件"是在调用 Gmail API；"往 Drive 上传文件"是在调用 Drive API。这些工具说到底，只是把大量已经公开的 API 用 JSON 串起来的中介者。理解了这副骨架之后，同样的工具您可以用得比以前更主动。

那当下该做什么？我的建议是：既然已经大致看清了整条流程，就先小小地落地、跑一跑、撞一撞墙。等到规模大起来、需要变得明确，再来考虑自建系统也不迟。说实话，现在是过去从未有过的适合小步起步的时代。云服务、公开 API、LLM、无代码工具，都在为这第一步托底。

如果想对 AI 和生意之间的关系看得更宽一点，小型企业的 AI 准备 — 数据、API，以及现在该做的事可以作为接下来的延伸阅读。

器、通道、消息。在这三个约定之上，您的生意哪怕离开您的双手，也会继续自己走下去。感谢您一路读完这套三部曲。

← 上一篇：什么是 API？写给非开发者店主的入门指南

guide api-economy basics-series