05交换格式

API  数据交换格式是应用程序之间传输数据时遵循的结构化规范，其核心作用是确保发送方和接收方能够一致理解数据的含义和结构。

不同格式因设计目标不同，在可读性、简洁性、功能性、性能等方面各有侧重。以下是常见的 API 数据交换格式，包括 JSON、XML、YAML 及其他重要格式的详细说明：

## 一、JSON

**定义**

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，起源于 JavaScript 的对象语法，但目前已成为跨语言通用格式（几乎所有编程语言都支持 JSON 解析 / 生成）。

**语法结构：**

核心是 “键值对”（key: value），键为字符串（必须用双引号包裹），值可以是字符串、数字、布尔值（true/false）、null、对象（{}，嵌套键值对）或数组（[]，有序值集合）。

示例：
```json
{
  "name": "API教程",
  "type": "技术文档",
  "tags": ["REST", "GraphQL"],
  "isPublished": true,
  "metadata": {
    "version": 1.0,
    "updateTime": "2025-08-07"
  }
}
```

**核心特点**：

- 轻量简洁：相比 XML，无冗余标签，数据体积更小，传输效率高。
- 易读性强：人类可直接理解，结构清晰（通过大括号、中括号区分对象和数组）。
- 跨语言兼容：几乎所有编程语言都内置 JSON 解析库（如 Python 的json模块、Java 的Jackson）。
- 支持基础数据类型：字符串、数字、布尔、null、对象、数组（不支持注释，这是与 YAML 的主要区别）。

**优缺点**：

- 优点：传输效率高、解析速度快、生态成熟（Web API 的 “事实标准”）。
- 缺点：不支持注释（复杂结构难以维护）、不支持复杂数据类型（如日期需转为字符串）、数组中元素类型无强制约束（可能导致解析歧义）。

**典型应用场景**：

- 绝大多数 Web API（RESTful API 的首选格式）。
- 前后端数据交互（浏览器原生支持JSON.parse()和JSON.stringify()）。
- 轻量级配置文件（如package.json）。

## 二、XML

**定义：**

XML（eXtensible Markup Language） 是一种可扩展的标记语言，通过自定义标签描述数据结构，强调 “数据的含义” 而非展示（区别于 HTML），曾是早期 API 的主流交换格式。

**语法结构：**

以标签（<tag>）包裹数据，标签必须成对出现（<tag></tag>），且严格嵌套（不能交叉）。

支持 “属性”（标签内的键值对）和 “文本内容”。

可通过 DTD（文档类型定义）或 XSD（XML Schema）定义数据结构规则（用于验证数据合法性）。

```xml
<document>
  <name>API教程</name>
  <type>技术文档</type>
  <tags>
    <tag>REST</tag>
    <tag>GraphQL</tag>
  </tags>
  <isPublished>true</isPublished>
  <metadata version="1.0">
    <updateTime>2025-08-07</updateTime>
  </metadata>
</document>
```

**核心特点**：

- 可扩展性：标签可完全自定义（如<name>、<metadata>），能精准描述业务语义。
- 严格结构化：通过标签嵌套和验证规则（XSD）确保数据格式严谨，适合复杂层级结构。
- 支持命名空间（Namespace）：避免多来源数据的标签冲突（如<ns1:tag>和<ns2:tag>）。
- 自描述性：标签本身携带数据含义（如<updateTime>明确表示 “更新时间”）。

**优缺点**：

- 优点：结构严谨、支持复杂验证、适合多系统间的规范数据交换（尤其企业级场景）。
- 缺点：冗余度高（标签重复导致数据体积大）、解析复杂（需处理标签嵌套和验证）、可读性较差（相比 JSON 和 YAML）。

**典型应用场景**：

- 早期 SOAP API 的默认格式（SOAP 协议基于 XML）。
- 企业级系统集成（如银行、电信的跨系统数据交换，依赖 XSD 验证）。
- 配置文件（如 Spring 框架的applicationContext.xml）、文档格式（如 RSS、SVG）。

## 三、YAML

**定义：**

YAML（YAML Ain't Markup Language） 是一种以 “可读性” 为核心设计目标的数据序列化格式，强调 “数据即代码”，避免冗余标记，适合配置和数据交换。其名称是递归缩写（“YAML 不是标记语言”），突出非标记语言的特性。

**语法结构：**

用**缩进**（空格，不支持制表符）表示层级关系（类似 Python）。

键值对用冒号加空格表示（key: value），数组用短横线加空格表示（- item）。

支持注释（# 这是注释），这是相比 JSON 的重要优势。

```yaml
name: "API教程"
type: 技术文档  # 字符串可省略引号（无特殊字符时）
tags:
  - REST
  - GraphQL
isPublished: true
metadata:
  version: 1.0
  updateTime: 2025-08-07  # 支持日期类型（解析时可自动识别）

```

**核心特点**：

- 极致可读性：缩进替代标签 / 括号，结构接近自然语言，人类易理解和编辑。
- 支持注释：可直接在数据中添加说明，适合复杂配置或文档化数据。
- 类型灵活：自动识别数据类型（如1.0为数字、2025-08-07为日期），无需显式声明。
- 兼容性：可表示 JSON 的所有结构（YAML 1.2 与 JSON 兼容，JSON 是 YAML 的子集）。

**优缺点**：

- 优点：可读性极强、支持注释、适合人工编辑的场景。
- 缺点：缩进敏感（错误缩进会导致解析失败）、解析速度略慢于 JSON（因需处理缩进和类型推断）、在高频 API 交互中使用较少（生态不如 JSON 成熟）。

**典型应用场景**：

- 配置文件（如 Docker 的docker-compose.yml、Kubernetes 资源清单、CI/CD 配置.github/workflows）。
- 需人工维护的结构化数据（如 API 文档示例、测试数据）。
- 部分 API（尤其是内部系统，优先考虑可读性时）。

## 四、其他格式

除上述三种外，还有一些针对特定场景优化的格式：

**Protocol Buffers（Protobuf）**

- 定义：Google 开发的二进制数据交换格式，需通过.proto文件预定义数据结构（类似 XSD），然后生成对应语言的解析代码。
- 特点：二进制格式（体积比 JSON 小 50%-80%）、解析速度极快（比 JSON 快 10 倍以上）、强类型（数据结构严格约束）、跨语言支持（支持 C++、Java、Python 等）。
- 缺点：不可读（二进制）、需预定义结构（灵活性低）、不适合人类直接编辑。
- 应用：高性能 API（如微服务间通信、实时数据传输）、内部系统交互（优先考虑效率）。

**CSV（Comma-Separated Values）**

- 定义：纯文本格式，用逗号（或制表符）分隔字段，每行表示一条记录，适合表格类数据。
- 特点：极简（无结构标记）、体积小、适合批量数据导出 / 导入（如 Excel、数据库）。
- 缺点：不支持嵌套结构（仅平面数据）、无类型区分（所有数据均为字符串）、易受特殊字符（如逗号）干扰。
- 应用：数据报表导出（如 API 返回用户列表、订单记录）、简单数据迁移。

**MessagePack**

- 定义：二进制 JSON 替代格式，保留 JSON 的结构（键值对、数组），但用二进制编码减少体积。
- 特点：兼容 JSON 语法、体积更小（比 JSON 节省 30%+ 空间）、解析速度快、支持更多数据类型（如二进制、时间戳）。
- 缺点：不可读（二进制）、生态不如 JSON 成熟。
- 应用：移动端 API（节省流量）、高性能 Web 服务。

## 五、小结

不同数据交换格式的选择需基于场景需求：

- **优先可读性和通用性**：选 JSON（Web API）或 YAML（配置 / 文档）。
- **需严格结构验证和复杂层级**：选 XML（企业级系统）。
- **追求极致性能和效率**：选 Protobuf 或 MessagePack（内部微服务）。
- **简单表格数据**：选 CSV（导出 / 导入）。

在 API 设计中，JSON 因平衡了可读性、效率和生态成熟度，仍是目前最主流的选择