什么是 YAML？了解 YAML 语法与最佳实践

大家好，欢迎来到IT知识分享网。

什么是 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 可以提高开发效率和文档质量。