YAML 简介：易懂的配置语言

什么是 YAML

YAML 是 "YAML Ain't Markup Language" 的缩写，这是一种用于数据序列化的基于文本的标记语言。

YAML 的用途

YAML (YAML Ain't Markup Language) 是一种人类可读的数据序列化格式，主要用于以下目的：

• 作为配置文件格式：  许多编程语言和框架采用 YAML 作为配置文件的格式。

• 作为应用程序之间的数据交换格式：  YAML 常和 JSON 一起被用作数据交换格式。

• 描述结构化数据：  YAML 可用于描述文档、产品信息、各种元数据等。

• YAML 是一个重要的数据序列化格式，广泛应用于各种场景，如编程语言中的数据结构序列化/反序列化、容器编排工具的清单文件描述、各类配置文件定义等。YAML 是 API 文档的标准格式之一，这是 YAML 的主要应用场景之一。

YAML 的特点

作为一种方便人类阅读和书写的语言，YAML 具有以下显著特点：

• 数据可以以人类易读易写的格式进行书写。

• 比 JSON 更简洁的语法。

• 空白字符（空格和制表符）具有特殊意义，因此缩进很重要。

• 能够包含注释。

• 能够表示数据类型，例如字符串、数字、数组和对象。

由于这些特点，使用 YAML 进行书写非常方便。在接下来的部分，我们将介绍如何编写 YAML 文件，以便不太熟悉的人更好地掌握。

如何编写 YAML

在 YAML 中，数据通常表示为 键值对。多个键值对可以通过缩进来分隔。以下是编写 YAML 的基本步骤。

使用键值对

在 YAML 中，数据主要通过键值对来表示，这样的键值对以冒号 (:) 分隔。

key: value

编写数据层级

当存在数据层级时，使用缩进（通常为两个空格）来继续描述下级对象。

parent:  child: value

编写列表和条目

数组使用短划线（-）来书写。如果有多个条目，每个条目必须以短划线开头。

fruits:  - apple  - orange  - banana

编写对象

对象也使用键值对，但需要使用缩进。

user:  name: Taro  age: 23

编写注释

要在 YAML 中编写注释，使用井号 (#)。注释从井号开始，延续到该行的末尾。

# 这是一个注释
# 你还可以在值旁边写注释key: value  # 注释
# 注释可以跨越多行long_commented_key: |  此值在  注释后继续。
# 嵌套结构（如 JSON）也可以有注释parent:  # 子元素的注释  child_key: child_value
# 在列表中也可以使用注释shopping_list:  - milk  # 2 升  - eggs  # 10 个  - bread

注释规则包括：

• 从 # 到行末的部分被视为注释。

• 注释可以放在值的前面或后面。

• 可以在标量值的上方或下方编写注释。

• 注释可以跨越多行。

通过添加注释，可以提高文件的清晰度和可读性，特别是对于配置文件或文档化内容。

编写多行字符串

要在 YAML 文件中编写多行字符串，使用竖线 (|) 包围内容。

text: |  XXXX  YYYY

遵循这些规则，您可以轻松编写 YAML 文件。与 JSON 相比，主要区别在于缩进和空白字符在 YAML 中是有意义的。因此，如果您熟悉 JSON，在使用 YAML 进行编写时需要特别注意这些差异。

YAML 文件示例

以下是一个完整的 YAML 文件示例，这有助于您更好地理解如何编写 YAML 文件。

# 样本 YAML文件
# 字典（映射）book:  title: Introduction to YAML  author:    # 嵌套的映射    name: Yamada Taro    age: 38  year: 2023  pages: 120  chapters:    # 列表    - Introduction    - Basics    - Advanced Techniques
# 列表fruits:  - apple  - orange  - banana
# 字符串description: |  YAML 是一个人类友好的数据序列化标准。  它通常用于配置文件和 API 中。
# 数值price: 9.99
# 布尔值published: true
# 空值score: ~

这个 YAML 文件表示如下数据结构：

以 book: 开头的块定义了一个字典（映射）。

• book 是键，其值为字典数据。

• title、author、year、pages 和 chapters 是键。

• author 的值是一个嵌套的字典结构。

• chapters 的值是一个列表结构。

以 fruits: 开头的块定义了一个列表。

• fruits 是键，值是列表。

• - apple、- orange 和 - banana 表示列表中的条目。

description: 键显示了一个多行字符串。

price: 定义了一个数值。

published: 定义了一个布尔值。

score: 使用 ~ 表示一个空值。

因此，YAML 允许灵活定义各种数据类型，并容易表示嵌套结构。

导入使用 YAML

Apifox 支持以 YAML 格式导入 OpenAPI 3、Swagger 1、2 和 3 API，因此您可以完全解析 YAML 格式的任何 API，并将 API 的数据完全导入到 Apifox 中进行测试。

首先可以打开项目设置，点击“导入数据”，选择 “OpenAPI/Swagger” 并将 YAML 文件拖到 Apifox 中。即可导入成功。

总结

YAML 是一种人类可读的数据结构化格式，广泛应用于 Web 应用开发中，如配置文件的编写和 API 文档的创建等。尽管其语法相对简单，但在缩进和注释处理上有独特的规则，需要特别注意。适当使用 YAML 可以提高开发效率和文档质量。