JSON 与 YAML：两种最常见的数据格式

完成时间：约 20 分钟。读完后你能看懂 JSON 和 YAML 格式的数据，不会被花括号和缩进吓到。

程序之间传递数据、配置文件、API 响应——到处都是这两种格式。它们表达的是同一种东西，只是写法不同：

	JSON	YAML
外观	花括号 { }、方括号 [ ]、双引号	缩进、冒号、短横线，像写大纲
适合	API 响应、程序间通信	配置文件（Docker Compose、CI/CD）
类比	填表格（严格格式）	写笔记（自由但要对齐）

先学 JSON（更常见），再学 YAML（5 分钟就懂）。

---

JSON 长什么样

{
  "name": "小明",
  "age": 25,
  "isAdmin": true,
  "hobbies": ["读书", "跑步"],
  "address": {
    "city": "上海",
    "street": "南京路"
  }
}

一眼看上去像是有很多引号和花括号的文本。别慌，它的规则非常简单——就是一组一组的”键: 值”配对。

---

6 种数据类型

JSON 里只有 6 种东西，没有更多了：

类型	长什么样	举例	类比
字符串	双引号包裹的文字	"小明"	一段文本
数字	直接写数字，不用引号	25、3.14	数值
布尔值	true 或 false	true	开关，开或关
数组	方括号 [ ]，逗号分隔	["读书", "跑步"]	一个列表
对象	花括号 { }，键值对	{"city": "上海"}	一张表单
null	null	null	空，什么都没有

记住这 6 种就够了。JSON 没有日期类型、没有函数、没有其他花样。

---

语法规则（常见踩坑）

JSON 的语法很严格，差一个字符就报错。以下是新手最常踩的坑：

1. key 必须用双引号

// 正确
{ "name": "小明" }

// 错误 — key 没有引号
{ name: "小明" }

// 错误 — 用了单引号
{ 'name': '小明' }

2. 最后一项后面不能有逗号（trailing comma）

// 正确
{
  "name": "小明",
  "age": 25
}

// 错误 — 25 后面多了一个逗号
{
  "name": "小明",
  "age": 25,
}

这是最常见的错误。JavaScript 允许尾逗号，但 JSON 不允许。

3. 字符串必须用双引号

// 正确
{ "name": "小明" }

// 错误 — 用了单引号
{ "name": '小明' }

4. 不能写注释

// 错误 — JSON 不支持注释
{
  "name": "小明"  // 这是名字
}

JSON 里不能写 // 也不能写 /* */。如果需要说明，只能用一个额外的字段：

{
  "_comment": "这是用户信息",
  "name": "小明"
}

---

你会在哪里遇到 JSON

场景	说明	简化示例
API 响应	后端返回的数据，GET /api/users 返回的就是 JSON	[{"id": 1, "name": "小明"}, {"id": 2, "name": "小红"}]
package.json	前端项目的”身份证”，记录名称、版本、依赖列表	{"name": "my-app", "version": "1.0.0", "dependencies": {"react": "^19.0.0"}}
settings.json	各种工具的配置文件（VS Code、Claude Code 的 Hooks/MCP）	{"editor.fontSize": 14, "editor.tabSize": 2}
mcp.json	MCP 服务器配置，定义 AI 工具能调用哪些服务	{"mcpServers": {"server1": {"command": "node", "args": ["index.js"]}}}
.env 不是 JSON	.env 文件用的是 KEY=VALUE 格式，没有花括号和引号	DATABASE_URL=postgres://localhost/mydb

注意最后一行：.env 文件看起来也是”键=值”，但它不是 JSON，格式完全不同。别把两者搞混。

---

怎么读 JSON

掌握两个符号就能读懂任何 JSON：

• 看到 { } → 这是一个对象（一组键值对，像一张表单）
• 看到 [ ] → 这是一个数组（一组同类东西，像一个列表）

嵌套就是对象里套对象、对象里套数组。顺着缩进一层一层读就行。

实战：读一个真实的 API 响应

假设你请求 GET /api/courses/1，后端返回：

{
  "id": 1,
  "title": "AI 工具实战营",
  "status": "active",
  "teacher": {
    "id": 10,
    "name": "张老师",
    "email": "zhang@example.com"
  },
  "lessons": [
    {
      "id": 101,
      "title": "第一课：环境搭建",
      "order": 1
    },
    {
      "id": 102,
      "title": "第二课：第一个项目",
      "order": 2
    }
  ]
}

怎么读：

1. 最外层是 { } → 这是一个课程对象
2. "teacher" 的值是 { } → 嵌套了一个老师对象
3. "lessons" 的值是 [ ] → 这是一个课程列表数组
4. 数组里每一项又是 { } → 每个课时也是一个对象

就像剥洋葱一样，一层一层往里看。

---

怎么编辑 JSON

1. 用编辑器自动格式化

在 VS Code / Cursor 里打开 JSON 文件，右键 → Format Document（格式化文档），编辑器会自动对齐缩进、检查语法。

快捷键：

• macOS：Shift + Option + F
• Windows：Shift + Alt + F

2. 在线工具

浏览器搜索 “JSON formatter” 或 “JSON validator”，把 JSON 粘贴进去，可以：

• 格式化（让缩进好看）
• 验证（检查有没有语法错误）
• 高亮显示错误位置

3. 常见编辑错误和解决方法

错误	现象	解决
少了逗号	两个键值对之间没有逗号	每行键值对末尾加 ,（最后一行除外）
多了逗号	最后一项后面多了逗号	删掉最后一个 ,
引号不对	用了单引号或中文引号	全部换成英文双引号 "
中文引号	复制粘贴时带入了 " "	替换为英文 "

---

动手练习

手写一个 JSON 描述你自己。要求包含：

• 名字（字符串）
• 年龄（数字）
• 技能列表（数组）
• 地址（嵌套对象，包含城市和街道）

参考格式：

{
  "name": "你的名字",
  "age": 20,
  "skills": ["技能1", "技能2", "技能3"],
  "address": {
    "city": "你的城市",
    "street": "你的街道"
  }
}

写完后用编辑器的 Format Document 格式化一下——如果没有报错，说明你的 JSON 语法是对的。

---

小结

要点	内容
JSON 是什么	程序之间传递数据的文本格式，所有语言通用
核心语法	{ } 是对象，[ ] 是数组，键值对用 : 分隔，项之间用 , 分隔
6 种类型	字符串、数字、布尔值、数组、对象、null
常见踩坑	key 必须双引号、没有尾逗号、没有注释
在哪遇到	API 响应、package.json、settings.json、mcp.json

JSON 没有什么难的。它就是一堆花括号、方括号、引号和逗号组成的文本。看到 { } 就知道是对象，看到 [ ] 就知道是数组——仅此而已。

---

Part 2：YAML — 更适合人类阅读的格式

YAML 是什么

YAML（YAML Ain’t Markup Language）和 JSON 表达的是完全相同的数据，只是写法不同。

如果说 JSON 像”填表格”——严格、精确、每个引号都不能少；那 YAML 就像”写大纲”——靠缩进来表示层级，看起来更清爽。

同一份数据的两种写法

JSON 版本：

{
  "name": "小明",
  "age": 25,
  "isAdmin": true,
  "hobbies": ["读书", "跑步"],
  "address": {
    "city": "上海",
    "street": "南京路"
  }
}

YAML 版本：

name: 小明
age: 25
isAdmin: true
hobbies:
  - 读书
  - 跑步
address:
  city: 上海
  street: 南京路

对比一下：

• 没有花括号 { }
• 没有方括号 [ ]（列表用 - 开头）
• key 不需要引号
• 用缩进（2 个空格）表示嵌套层级

YAML 的 5 条规则

1. 键值对 — 用冒号分隔

name: 小明
port: 8080

冒号后面必须有一个空格。name:小明 是错的，name: 小明 才对。

2. 嵌套 — 用缩进（2 个空格）

database:
  host: localhost
  port: 5432
  name: mydb

缩进必须用空格，不能用 Tab。这是 YAML 最常踩的坑。

3. 列表 — 用短横线 -

fruits:
  - 苹果
  - 香蕉
  - 橙子

4. 字符串通常不用引号

# 这三种都行
name: 小明
name: "小明"
name: '小明'

# 但包含特殊字符时需要引号
message: "注意: 这里有冒号"

5. 注释用 #

# 这是注释，YAML 支持注释（JSON 不支持！）
name: 小明  # 行内注释也可以

你会在哪里遇到 YAML

文件	用途	示例
docker-compose.yml	定义 Docker 服务	数据库配置、端口映射
Taskfile.yaml	本课程的任务运行器	定义 task server、task web 等命令
.github/workflows/*.yml	GitHub Actions CI/CD	自动测试、自动部署
Kubernetes 配置	容器编排（进阶）	生产环境部署

实战：读懂 docker-compose.yml

本课程项目里的 docker-compose.yml 就是 YAML 格式：

services:                          # 定义所有服务
  postgres:                        # 服务名叫 postgres
    image: postgres:16             # 使用 PostgreSQL 16 镜像
    ports:                         # 端口映射
      - "5432:5432"                # 本机 5432 → 容器 5432
    environment:                   # 环境变量
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: ai_tool_camp
    volumes:                       # 数据持久化
      - pgdata:/var/lib/postgresql/data

volumes:                           # 声明数据卷
  pgdata:

读法：

1. 最外层 services: → 下面定义了哪些服务
2. postgres: 缩进 2 格 → 这是 services 的子项
3. image:、ports:、environment: 再缩进 2 格 → 这是 postgres 的配置
4. - "5432:5432" 用 - → 这是一个列表项

实战：读懂 Taskfile.yaml

version: '3'

tasks:
  server:                          # task server 命令
    dir: server                    # 在 server 目录下执行
    cmds:                          # 要运行的命令列表
      - go run main.go

  web:                             # task web 命令
    dir: web
    cmds:
      - npm run dev

  seed:                            # task seed 命令
    dir: server
    cmds:
      - go run cmd/seed/main.go

现在你知道为什么 task server 能启动后端了——它实际上是去 server/ 目录执行 go run main.go。

JSON vs YAML 速查对比

特性	JSON	YAML
花括号/方括号	必须	不用，靠缩进
key 引号	必须双引号	通常不用
字符串引号	必须双引号	通常不用
注释	不支持	# 注释
尾逗号	不允许	没有逗号的概念
缩进	无所谓（格式化好看而已）	严格要求（2 空格，不能用 Tab）
主要用途	API 响应、程序间通信	配置文件
常见文件	.json	.yml / .yaml

一句话总结：API 和代码里用 JSON，配置文件用 YAML。两者能互相转换，表达的是同一种数据。

YAML 常见踩坑

错误	现象	解决
用了 Tab 缩进	解析报错	编辑器设置：Tab → 2 spaces
缩进不对齐	层级关系混乱	用编辑器的缩进辅助线对齐
冒号后没空格	key:value 不识别	改成 key: value
特殊字符没引号	包含 :、#、{ 的字符串报错	用双引号包起来
yes/no 被当成布尔值	字符串 “yes” 变成了 true	用引号："yes"

---

总结

要点	内容
JSON	{ } 对象、[ ] 数组、双引号、逗号分隔。API 和程序间通信的标准格式
YAML	缩进表示层级、- 表示列表、# 写注释。配置文件的首选格式
共同点	表达同样的数据结构（对象、数组、字符串、数字、布尔值、null）
记忆法	看到 .json → 花括号世界；看到 .yml → 缩进世界

---

下一步：回到主线课程，继续学习。