yaml基本语法，数据类型，对象，数组，复合结构，纯量，引用；文件后缀为.yml或.yaml

`.yml` 是 **YAML（YAML Ain‘t Markup Language）** 文件的标准扩展名之一，它是一种用于数据序列化的人类可读的数据格式，广泛应用于配置文件、数据交换和持久化场景[ref_1]。其核心设计目标是易于人类阅读和编写，同时能被各种编程语言轻松解析。 ### YAML 与 `.yml` 扩展名解析 `.yml` 与 `.yaml` 扩展名在功能上完全等价，都代表YAML格式的文件。两者的区别主要在于使用习惯和跨平台兼容性上的细微差异[ref_1]。 | 特性对比 | `.yml` 扩展名 | `.yaml` 扩展名 | | :--- | :--- | :--- | | **本质** | YAML 文件格式的常用扩展名 | YAML 文件格式的官方推荐扩展名 | | **内容与语法** | 与 `.yaml` 完全相同，无任何区别 | 与 `.yml` 完全相同，无任何区别 | | **历史与习惯** | 源于早期 DOS/Windows 系统对文件扩展名长度（3个字符）的限制，形成了广泛的使用习惯[ref_1]。 | 是官方更推荐的完整拼写，在 Unix/Linux 系统和许多现代工具中更常见。 | | **兼容性** | 绝大多数现代工具和框架（如 Docker, Ansible, Spring Boot）都同时支持两种扩展名，但某些严格遵循官方规范的旧工具可能只识别 `.yaml`[ref_1]。 | 具有最佳的跨平台和工具兼容性。 | **结论**：在项目中，`.yml` 和 `.yaml` 可以互换使用。选择哪一个主要取决于团队约定或所用框架的默认习惯。例如，Spring Boot 社区更常用 `application.yml`，而许多基础设施工具（如 Kubernetes）的官方文档示例多用 `.yaml`[ref_1]。 ### `.yml` 文件的核心语法与结构 `.yml` 文件使用缩进（通常为2个空格）来表示层级关系，使用冒号 `:` 表示键值对，使用短横线 `-` 表示列表项[ref_2]。 **1. 基本键值对与嵌套：** ```yaml # 简单的键值对 name: John Doe age: 30 # 嵌套对象（使用缩进） person: name: Alice address: city: Beijing street: Zhongguancun ``` 上面的YAML对应JSON结构为：`{"name": "John Doe", "age": 30, "person": {"name": "Alice", "address": {"city": "Beijing", "street": "Zhongguancun"}}}`[ref_2]。 **2. 列表（数组）：** ```yaml # 简单列表 fruits: - Apple - Banana - Orange # 对象列表 employees: - name: Zhang San department: R&D - name: Li Si department: Sales ``` **3. 多文档支持：** 一个 `.yml` 文件可以包含多个独立的“文档”，它们之间用 `---` 分隔，以 `...` 结束（可选）[ref_2]。 ```yaml # 文档1：服务器配置 server: port: 8080 --- # 文档2：数据库配置 database: host: localhost name: test_db ... ``` **4. 特殊值表示：** * **空值**：使用 `~` 或 `null` 表示。 * **字符串**：通常不需要引号，但包含特殊字符时需用单引号 `'` 或双引号 `"`。双引号会解析转义字符（如 `\n`），单引号不会。 * **布尔值**：`true`/`false` 或 `yes`/`no`。 * **强制类型转换**：使用 `!!` 进行类型声明，如 `!!int 123`[ref_2]。 ### `.yml` 文件在项目中的典型应用 `.yml` 文件因其清晰的结构，在各类项目中扮演着配置中心的角色。 **1. Spring Boot 应用配置 (`application.yml`)** 这是 `.yml` 最经典的应用场景之一，用于集中管理应用的所有配置[ref_4][ref_6]。 ```yaml # application.yml 示例 spring: datasource: url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC username: root password: mypassword driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 server: port: 8080 servlet: context-path: /api logging: level: com.example: DEBUG ``` 在此例中，YAML的层级结构清晰地组织了数据库、服务器、日志等不同维度的配置。Spring Boot 会自动加载此文件并将属性注入到应用中。与 `application.properties` 相比，YAML格式在配置复杂嵌套结构时更加简洁直观[ref_6]。 **2. Docker Compose 服务编排 (`docker-compose.yml`)** 用于定义和运行多容器 Docker 应用程序[ref_3][ref_5]。 ```yaml # docker-compose.yml 示例 version: '3.8' # 指定Compose文件格式版本[ref_3] services: # 定义服务列表 webapp: build: . # 从当前目录Dockerfile构建镜像 ports: - "8080:80" # 端口映射 depends_on: # 依赖关系 - db environment: # 环境变量 DB_HOST: db db: image: postgres:13 environment: POSTGRES_PASSWORD: secret volumes: # 数据卷挂载 - db_data:/var/lib/postgresql/data volumes: db_data: # 声明命名卷 ``` 此文件通过声明式语法描述了整个应用栈：一个Web应用服务和一个PostgreSQL数据库服务，包括它们的构建方式、依赖关系、网络和存储配置[ref_5]。 **3. CI/CD 流水线配置 (如 GitLab CI `.gitlab-ci.yml`)** ```yaml # .gitlab-ci.yml 示例 stages: - build - test - deploy build_job: stage: build script: - echo "Compiling the code..." - mvn compile test_job: stage: test script: - echo "Running tests..." - mvn test ``` ### 使用 `.yml` 文件的注意事项与常见问题 1. **严格的缩进**：YAML 依赖缩进（空格）定义结构，**不能使用Tab键**。使用空格（通常是2个或4个）并保持一致性至关重要。缩进错误是导致解析失败的最常见原因[ref_4]。 ```yaml # 错误示例：使用了Tab缩进，可能导致解析错误 database: host: localhost # 这里用了Tab # 正确示例：使用空格缩进 database: host: localhost # 这里用了两个空格 ``` 2. **冒号后的空格**：在键值对中，冒号 `:` 后面**必须有一个空格**，否则会被解析为字符串的一部分[ref_4]。 ```yaml # 错误 key:value # 正确 key: value ``` 3. **字符串的特殊字符**：当字符串包含 `:`、`-`、`#`、`[`、`]`、`{`、`}` 等YAML特殊字符时，需要用引号括起来。 ```yaml # 包含冒号的字符串 message: "Error: Something went wrong" # 被误解为列表项的字符串 item: "- This is a single string" ``` 4. **多行字符串**：YAML 提供了多种多行字符串表示法（如 `|` 保留换行，`>` 折叠换行），用于配置长文本（如脚本、证书）[ref_2]。 ```yaml script: | echo "Line 1" echo "Line 2" echo "Line 3" ``` 5. **与 `.properties` 文件的区别与选择**： * **`.properties`**：平面键值对结构，适合简单配置，语法为 `key=value`。 * **`.yml`/`.yaml`**：层次化结构，适合复杂、有嵌套关系的配置。 在Spring Boot中，如果同时存在 `application.properties` 和 `application.yml`，且配置冲突，`.properties` 文件的优先级通常更高[ref_6]。 总之，`.yml` 文件是一种强大且流行的配置和数据定义格式。理解其语法规则（缩进、冒号空格、列表表示）是避免配置错误的关键[ref_4]。在实际项目中，应根据配置的复杂度和团队规范，在 `.yml` 和 `.properties` 之间做出合适选择，并注意 `.yml` 与 `.yaml` 扩展名的实质等价性及潜在的工具兼容性差异[ref_1]。

YAML（YAML Ain‘t Markup Language）是一种**数据序列化语言**，它被设计成对人类非常友好，易于阅读和编写，常用于配置文件、数据交换等场景。其文件扩展名通常为 `.yaml` 或 `.yml`，两者在内容和语法上完全等价，可以互换使用，只是 `.yml` 更简短，历史上在某些系统（如 Windows 3.1）中更流行 [ref_5]。 ### 一、YAML 的核心特性与优势 YAML 之所以在配置领域广受欢迎，得益于其一系列特性 [ref_3][ref_4]。 | 特性 | 说明与优势 | | :--- | :--- | | **可读性强** | 使用缩进和常见符号（如冒号、短横线）来组织数据，结构一目了然，远胜于 JSON 或 XML 的括号嵌套。 | | **简洁明了** | 不需要大量的括号和引号，语法非常精简。 | | **支持多种数据类型** | 支持字符串、布尔值、整数、浮点数、空值、数组（列表）、对象（映射）等。 | | **跨语言支持** | 几乎所有主流编程语言都有成熟的 YAML 解析库，如 Python 的 `PyYAML`、Java 的 `SnakeYAML`、JavaScript 的 `js-yaml` 等。 | | **广泛应用** | 是 **Docker Compose**、**Kubernetes**、**Ansible**、**Spring Boot**、**GitHub Actions** 等众多现代工具和框架的**首选配置格式**。 | ### 二、YAML 基本语法详解 YAML 使用缩进（通常为 2 个空格）来表示层级关系，**不允许使用制表符（Tab）**。 #### 1. 键值对（对象/映射） 最基本的元素，使用 `key: value` 格式。冒号后面必须有一个空格 [ref_2][ref_3]。 ```yaml # 普通键值对 name: John Doe age: 30 is_student: false ``` #### 2. 数组（列表） 使用短横线加空格 `- ` 表示数组中的一项 [ref_2][ref_3]。 ```yaml # 一个简单的列表 fruits: - Apple - Banana - Orange # 内联写法（行内数组） colors: [Red, Green, Blue] ``` #### 3. 嵌套结构 YAML 支持对象和数组的任意嵌套。 ```yaml # 对象中包含对象和数组 person: name: Alice address: city: Shanghai street: Nanjing Road hobbies: - Reading - Hiking - Coding ``` #### 4. 多行字符串 对于长文本，YAML 提供了多种多行字符串的写法，以保留或折叠换行符 [ref_2]。 * **`|`（保留换行符）**：保留字符串中的所有换行。 * **`>`（折叠换行符）**：将字符串中的换行转换为空格，使长字符串更易读。 * **`|+` / `|-`**：用于控制文档末尾的换行符处理（`+` 保留，`-` 删除）[ref_2]。 ```yaml description: | This is a long description that spans multiple lines. Each line will be preserved. summary: > This is a summary that also spans multiple lines, but newlines will be folded into spaces. ``` #### 5. 特殊值与注释 * **空值**：可以用 `null`、`~` 或直接不写值来表示 [ref_2]。 * **布尔值**：`true` / `false`、`yes` / `no`、`on` / `off` 都可以。 * **注释**：使用 `#` 符号，从 `#` 开始到行尾的内容都会被忽略。 ```yaml middle_name: null # 或 middle_name: ~ enabled: true disabled: no # 这是一行注释 host: localhost # 行内注释 ``` ### 三、在 Spring Boot 中的应用 Spring Boot 支持使用 `application.yml` 替代传统的 `application.properties` 作为配置文件，使得配置更加结构化 [ref_3][ref_4]。 **`application.properties` 写法**: ```properties server.port=8080 spring.datasource.url=jdbc:mysql://localhost:3306/mydb spring.datasource.username=root spring.datasource.password=secret spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver ``` **等效的 `application.yml` 写法**: ```yaml server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/mydb username: root password: secret driver-class-name: com.mysql.cj.jdbc.Driver ``` YAML 的层次结构使得配置项之间的关系一目了然，特别是在配置复杂对象（如列表、Map）时优势明显 [ref_3]。 ```yaml # 配置一个列表属性，例如多个缓存名称 spring: cache: cache-names: - users - products - orders # 配置一个Map属性，例如自定义消息 app: messages: welcome: “Hello, World!“ error: not-found: “Resource not found.“ server: “Internal server error.“ ``` ### 四、在 Docker Compose 中的应用 `docker-compose.yml` 文件是 YAML 格式的经典应用，用于定义和运行多容器 Docker 应用 [ref_6]。其结构清晰地展示了 YAML 的组织能力。 ```yaml # 版本声明（在新版Compose中有时可省略）[ref_6] version: ‘3.8‘ # 定义所有服务（容器）[ref_6] services: # 定义一个名为‘web‘的服务 web: # 服务使用的镜像 [ref_6] image: nginx:alpine # 容器名称 container_name: my_nginx # 端口映射 ports: - “80:80“ # 列表项，表示将主机80端口映射到容器80端口 # 环境变量 environment: NGINX_HOST: example.com NGINX_PORT: 80 # 数据卷挂载 volumes: - ./html:/usr/share/nginx/html # 绑定挂载主机目录 - nginx_logs:/var/log/nginx # 使用命名卷 # 重启策略 restart: unless-stopped # 定义另一个服务，如数据库 db: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: rootpass volumes: - db_data:/var/lib/mysql # 定义在‘services‘中引用的命名数据卷 [ref_6] volumes: nginx_logs: db_data: ``` ### 五、`.yaml` 与 `.yml` 扩展名区别 这是一个常见的困惑点。简单来说，**`.yaml` 和 `.yml` 在功能上没有任何区别**，它们都代表 YAML 格式的文件。区别主要在于历史和习惯 [ref_5]： 1. **官方推荐**：YAML 官方最初建议使用 `.yaml`。 2. **历史原因**：在早期的 Windows 3.1 和 DOS 系统中，文件扩展名被限制为三个字符，因此 `.yml` 被广泛使用。 3. **现状**：现代系统中两者完全通用。在 **Spring Boot** 中常用 `application.yml`，而在 **Kubernetes** 中则普遍使用 `.yaml`。选择哪一个主要取决于项目约定或个人偏好 [ref_5]。 ### 六、注意事项与常见错误 1. **缩进**：**必须使用空格**，不能使用 Tab 键。通常建议使用 2 个空格作为一级缩进 [ref_3]。 2. **冒号后的空格**：在键值对中，冒号 `:` 后面**必须**跟一个空格，否则解析会出错。 3. **字符串引号**：一般情况下字符串不需要引号，但如果字符串中包含特殊字符（如 `:`, `{`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``），则需要用单引号或双引号括起来。单引号会转义特殊字符，双引号则不会。 4. **文档分隔符**：一个 YAML 文件可以包含多个文档，文档之间用三个连字符 `---` 分隔，文档结束可以用三个点 `...` 表示（可选）[ref_2]。 总之，YAML 凭借其极佳的可读性和表达能力，已成为现代软件开发和运维中不可或缺的配置语言。掌握其基本语法和最佳实践，对于使用 Spring Boot、Docker Compose、Kubernetes 等工具至关重要。