4.2 JSON 与 YAML

🎯 小白理解：JSON 和 YAML 是什么？

想象你要把一份"菜谱"发给朋友：

• 用纯文本：很难表达结构（哪些是材料？哪些是步骤？）
• 用 JSON/YAML：结构清晰，人和电脑都能看懂

它们就是"数据的通用语言"——让不同程序之间能交换信息！

Python 字典 ←→ JSON 文件 ←→ JavaScript 对象
                 ↑
           通用的数据格式

JSON 处理

🎯 小白理解：JSON 长什么样？

{
  "name": "小明",
  "age": 25,
  "hobbies": ["编程", "游戏"]
}

JSON 的规则：

规则	说明
用 {} 表示对象	像 Python 的字典
用 [] 表示数组	像 Python 的列表
键必须用双引号	"name" ✅，'name' ❌
不能有注释	JSON 不支持 // 或 # 注释

关键函数：

• json.dumps(数据) → 把 Python 对象变成 JSON 字符串（dump string）
• json.loads(字符串) → 把 JSON 字符串变成 Python 对象（load string）
• indent=2 → 缩进 2 格，让输出更美观
• ensure_ascii=False → 中文不会变成 \uXXXX

import json
from pathlib import Path

# Agent 配置
config = {
    "name": "ResearchBot",
    "model": "gpt-4",
    "tools": ["search", "calculator"],
    "temperature": 0.7
}

# 保存为 JSON
config_file = Path("agent_config.json")
config_file.write_text(json.dumps(config, indent=2, ensure_ascii=False))

# 读取 JSON
loaded_config = json.loads(config_file.read_text())
print(f"模型: {loaded_config['model']}")

YAML 处理

🎯 小白理解：YAML 和 JSON 有什么区别？

同样的数据：

# YAML 版本（简洁、可以写注释）
name: 小明
age: 25
hobbies:
  - 编程
  - 游戏

// JSON 版本（更严格，不能有注释）
{
  "name": "小明",
  "age": 25,
  "hobbies": ["编程", "游戏"]
}

对比：

特性	JSON	YAML
可读性	一般	非常好
支持注释	❌ 不支持	✅ 支持 #
引号要求	必须用双引号	大多数情况不需要
常见用途	API 数据交换	配置文件

什么时候用哪个？

• JSON：程序之间传数据（API、数据库）
• YAML：给人看的配置文件（Docker、GitHub Actions、Agent 配置）

安全提醒：用 yaml.safe_load() 而不是 yaml.load()！后者可能执行恶意代码。

import yaml
from pathlib import Path

# 保存为 YAML
config_yaml = Path("agent_config.yaml")
with config_yaml.open("w", encoding="utf-8") as f:
    yaml.dump(config, f, allow_unicode=True)

# 读取 YAML
with config_yaml.open("r", encoding="utf-8") as f:
    loaded = yaml.safe_load(f)
    print(loaded)

---

下一节：4.3 实战：配置管理系统