4.6 配置文件格式 🟢

阅读完本节后，你将会收获：

理解 JSON 和 YAML 的语法和用途
掌握两种格式的读写方法
了解它们在开发中的应用场景
理解结构化数据对 AI 的价值

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

什么是结构化数据格式

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

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

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

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

💡 提示

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 的标准格式

💡 提示

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 的优势****************

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

💡 提示

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 是更好的选择，因为它们能表达更复杂的数据结构。

两种格式对比“

特性	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。

MossDocuments v2.2.2

4.6 配置文件格式 🟢

什么是结构化数据格式

JSON 格式

语法规则json

数据类型````````````````

JSON 的优势****************

YAML 格式

语法规则yaml

YAML 的优势****************

CSV：平面文件格式

两种格式对比“

实际应用示例

JSON：用户数据json

YAML：应用配置yaml

JSON：API 响应json

YAML：CI/CD 配置yaml

在开发中的使用

package.json（JSON）

tsconfig.json（JSON）

常见问题

Q1: JSON 中的注释怎么办？

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

Q3: 如何选择 JSON 还是 YAML？

Q4: 格式写错了怎么办？

本节核心要点

相关内容