---
title: "4.6 配置文件格式"
description: "理解 JSON 和 YAML 配置格式"
chapter: "第四章"
priority: "🟢"
---

# 4.6 配置文件格式 🟢

> **阅读完本节后，你将会收获：**
>
> - 理解 JSON 和 YAML 的语法和用途
> - 掌握两种格式的读写方法
> - 了解它们在开发中的应用场景
> - 理解结构化数据对 AI 的价值

> JSON 和 YAML 是数字时代的"普通话"——不同系统之间交流的通用语言。

---

## 什么是结构化数据格式

结构化数据格式是用严格规则组织的数据表示方式。它们让计算机能够准确地解析和理解数据。

与自然语言相比，结构化格式：

- 格式统一，没有歧义
- 易于程序解析和生成
- 跨语言、跨平台通用
- AI 能够准确理解

理解结构化数据的价值，可以从编程语言的演进来看。早期的编程语言更接近机器，程序员需要直接处理内存地址和二进制数据。随着高级语言的出现，数据被抽象为变量、对象、数组等概念，程序员可以用更自然的方式描述数据。JSON 和 YAML 代表了这种抽象的最高层——它们不是某种特定语言的语法，而是所有现代语言都能理解的"通用语"。无论你用 Python 的字典、JavaScript 的对象、还是 Go 的结构体，最终都可以无损地转换为 JSON 格式，被其他语言解析。这种通用性是现代软件生态能够互联互通的基础。

::: tip AI 的阅读偏好

相比于散漫的自然语言，结构清晰的格式是 AI 最爱读的"说明书"。当你把需求或配置用 JSON/YAML 写出来，AI 的理解准确度会大幅提升。

:::

---

## JSON 格式

**JSON（JavaScript Object Notation）** 是最常用的数据交换格式。

### 语法规则

```json
{
  "name": "张三",
  "age": 25,
  "email": "zhang@example.com",
  "address": {
    "city": "北京",
    "district": "朝阳"
  },
  "hobbies": ["阅读", "游泳", "编程"]
}
```

**规则说明**：

- 使用大括号 `{}` 表示对象
- 使用方括号 `[]` 表示数组
- 数据以"键: 值"的方式组织
- 键必须用双引号包裹
- 键值对之间用逗号分隔

### 数据类型

| 类型 | 示例 | 说明 |
|------|------|------|
| 字符串 | `"hello"` | 用双引号包裹 |
| 数字 | `123`、`3.14` | 整数或浮点数 |
| 布尔值 | `true`、`false` | 真/假 |
| 数组 | `[1, 2, 3]` | 有序的数据列表 |
| 对象 | `{"key": "value"}` | 键值对集合 |
| null | `null` | 空值 |

### JSON 的优势

| 优势 | 说明 |
|------|------|
| **通用性** | 所有编程语言都支持 |
| **可读性** | 人类可以轻松阅读 |
| **紧凑性** | 格式简洁，不浪费空间 |
| **Web 标准** | HTTP API 的标准格式 |

::: tip JSON 是数字时代的普通话

无论你用 Python 写后端，用 JavaScript 写前端，还是让 AI 来写代码，大家都用 JSON 传递数据。如果不用 JSON，每种语言可能都有自己的"方言"格式，就像古代各地有自己的语言一样，交流起来很困难。

:::

---

## YAML 格式

**YAML（YAML Ain't Markup Language）** 是一种更人性化的配置格式。

### 语法规则

```yaml
# 用户信息
name: 张三
age: 25
email: zhang@example.com

# 地址信息
address:
  city: 北京
  district: 朝阳

# 爱好列表
hobbies:
  - 阅读
  - 游泳
  - 编程
```

**规则说明**：

- 用缩进表示层级关系（空格，不能用 Tab）
- 键值对用冒号分隔
- 数组项用短横线 `-` 表示
- `#` 开头表示注释

### YAML 的优势

| 优势 | 说明 |
|------|------|
| **可读性更强** | 像写清单一样自然 |
| **支持注释** | 可以添加说明文字 |
| **简洁** | 不需要花括号、引号、逗号 |
| **适合配置** | 常用于配置文件 |

::: tip YAML vs JSON

YAML 像"清单"，JSON 像"表格"。写配置文件用 YAML 更轻松，传输数据用 JSON 更标准。

:::

---

## CSV：平面文件格式

在讨论结构化数据时，**CSV（Comma-Separated Values）** 是最简单的格式之一。它用纯文本存储表格数据，每行是一条记录，字段用逗号分隔。

**CSV 示例**：

```csv
name,email,age
张三,zhang@example.com,25
李四,li@example.com,30
```

**CSV 的特点**：

- **简单**：任何文本编辑器都能打开
- **兼容性好**：Excel、Google Sheets 都能直接导入
- **体积小**：没有多余的格式标记

**CSV 的局限**：

- 只能表示二维表格（行和列）
- 不支持嵌套结构
- 没有数据类型（所有内容都是字符串）
- 处理复杂关系时力不从心

**CSV vs JSON/YAML**：

| 特性 | CSV | JSON/YAML |
|------|-----|-----------|
| 结构 | 二维表格 | 任意嵌套 |
| 数据类型 | 无 | 字符串、数字、布尔等 |
| 关系表达 | 弱 | 强 |
| 适用场景 | 简单数据导出、表格交换 | 配置文件、API 数据、复杂结构 |

当你需要从电子表格导出数据，或者与使用 Excel 的同事交换简单数据时，CSV 很合适。但对于 Web 应用开发，JSON 和 YAML 是更好的选择，因为它们能表达更复杂的数据结构。

---

## 两种格式对比

<ConfigFormatPlayground />

| 特性 | JSON | YAML |
|------|------|------|
| 语法 | 严格，需要括号引号 | 宽松，靠缩进 |
| 注释 | 不支持 | 支持 `#` |
| 可读性 | 较好 | 更好 |
| 适用场景 | 数据传输、API | 配置文件 |
| 解析速度 | 更快 | 稍慢 |

---

## 实际应用示例

### JSON：用户数据

```json
{
  "id": "user_123",
  "name": "张三",
  "email": "zhang@example.com",
  "avatar": "https://example.com/avatar.jpg",
  "location": {
    "country": "中国",
    "province": "北京",
    "city": "北京"
  },
  "birthday": "1990-01-15",
  "phone": "+86 138 0000 0000"
}
```

### YAML：应用配置

```yaml
# 应用配置
app:
  name: "我的博客"
  version: "1.0.0"
  port: 3000

# 数据库配置
database:
  host: "localhost"
  port: 5432
  name: "blog_db"
  user: "admin"
  password: "${DB_PASSWORD}"  # 引用环境变量

# 功能开关
features:
  enable_comments: true
  enable_analytics: false
```

### JSON：API 响应

```json
{
  "success": true,
  "data": {
    "posts": [
      {
        "id": "1",
        "title": "第一篇文章",
        "author": "张三"
      },
      {
        "id": "2",
        "title": "第二篇文章",
        "author": "李四"
      }
    ],
    "total": 2,
    "page": 1
  }
}
```

### YAML：CI/CD 配置

```yaml
# GitHub Actions 配置
name: 部署
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装依赖
        run: pnpm install
      - name: 构建
        run: pnpm build
      - name: 部署
        run: pnpm deploy
```

---

## 在开发中的使用

### package.json（JSON）

Node.js 项目的配置文件，定义项目依赖和脚本：

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.0.0"
  }
}
```

### tsconfig.json（JSON）

TypeScript 配置文件：

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "jsx": "preserve",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
```

---

## 常见问题

### Q1: JSON 中的注释怎么办？

JSON 标准不支持注释。需要注释可以用 JSONC（JSON with Comments）或改用 YAML。

### Q2: YAML 缩进用空格还是 Tab？

只能用空格，不能用 Tab。通常用 2 个空格作为一级缩进。

### Q3: 如何选择 JSON 还是 YAML？

- 数据传输、API 响应：用 JSON
- 配置文件：优先 YAML
- 需要注释：用 YAML
- Web API：用 JSON

### Q4: 格式写错了怎么办？

大多数编辑器都有语法检查。让 AI 帮忙修复也是好办法，它会指出具体错误并给出正确格式。

---

## 本节核心要点

- ✅ JSON 和 YAML 是结构化数据的标准格式
- ✅ JSON 是 Web API 的通用数据格式
- ✅ YAML 更适合写配置文件
- ✅ 结构化格式让 AI 更准确理解需求
- ✅ JSON 使用括号引号，YAML 使用缩进
- ✅ 选择格式取决于使用场景

理解了配置格式后，接下来学习如何将这些知识应用到实际场景中——集成外部 API。

---

## 相关内容

- 前置：[4.2 PRD与技术文档的关系](./02-prd-and-tech-docs.md)
- 前置：[4.5 前后端分离概念](./05-frontend-backend-separation.md)
- 详见：[4.7 API集成实战](./07-api-integration.md)
- 详见：[4.8 项目说明书结构](./08-readme-structure.md)