【Spring Boot—— .yml（YAML）】Spring Boot中.yml文件的基础语法、高级特性、实践技巧

文章目录

- [一、YAML 基础概述](#一、YAML 基础概述)
- - [1. YAML 定义与特点](#1. YAML 定义与特点)
  - [2. Spring Boot 对 YAML 的支持](#2. Spring Boot 对 YAML 的支持)
- [二、YAML 核心语法规则](#二、YAML 核心语法规则)
- - [1. 基本语法规范](#1. 基本语法规范)
  - [2. 数据类型](#2. 数据类型)
  - [3. 特殊语法](#3. 特殊语法)
  - [一、YAML 基本语法规范](#一、YAML 基本语法规范)
  - - [1. 键值对（Key-Value）](#1. 键值对（Key-Value）)
    - [2. 层级缩进（表示嵌套关系）](#2. 层级缩进（表示嵌套关系）)
    - [3. 注释](#3. 注释)
  - [二、YAML 数据类型](#二、YAML 数据类型)
  - - [1. 标量（Scalar）：单个值](#1. 标量（Scalar）：单个值)
    - [2. 序列（Sequence）：列表/数组](#2. 序列（Sequence）：列表/数组)
    - [3. 映射（Mapping）：嵌套对象](#3. 映射（Mapping）：嵌套对象)
  - [三、YAML 特殊语法](#三、YAML 特殊语法)
  - - [1. 多行字符串](#1. 多行字符串)
    - [2. 引用与合并（复用配置）](#2. 引用与合并（复用配置）)
  - [四、Spring Boot 特有的 YAML 语法](#四、Spring Boot 特有的 YAML 语法)
  - - [1. 占位符与默认值](#1. 占位符与默认值)
    - [2. 随机值配置](#2. 随机值配置)
    - [3. 多环境 Profile 配置](#3. 多环境 Profile 配置)
  - 注意事项
- [三、Spring Boot 中 YAML 配置优先级](#三、Spring Boot 中 YAML 配置优先级)
- - [1. 配置文件位置优先级（从高到低）](#1. 配置文件位置优先级（从高到低）)
  - [2. 多环境配置优先级](#2. 多环境配置优先级)
  - [3. 全量配置源优先级（从高到低）](#3. 全量配置源优先级（从高到低）)
- [四、YAML vs Properties：对比与选择](#四、YAML vs Properties：对比与选择)
- [五、Spring Boot 中 YAML 常用配置示例](#五、Spring Boot 中 YAML 常用配置示例)
- - [1. 服务器与 Web 配置](#1. 服务器与 Web 配置)
  - [2. 数据源与持久层配置](#2. 数据源与持久层配置)
  - [3. 日志配置](#3. 日志配置)
  - [4. 自定义配置](#4. 自定义配置)
- [六、YAML 高级特性与进阶用法](#六、YAML 高级特性与进阶用法)
- - [1. 多环境 Profile 配置](#1. 多环境 Profile 配置)
  - [2. 占位符与变量引用](#2. 占位符与变量引用)
  - [3. 类型安全的配置属性（`@ConfigurationProperties`）](#3. 类型安全的配置属性（@ConfigurationProperties）)
  - [4. YAML 扩展与集成](#4. YAML 扩展与集成)
- 七、常见问题与注意事项
- - [1. 语法陷阱](#1. 语法陷阱)
  - [2. 配置优先级混淆](#2. 配置优先级混淆)
  - [3. 编码与乱码](#3. 编码与乱码)
- [八、YAML 配置最佳实践](#八、YAML 配置最佳实践)

Spring Boot 中 .yml 文件的完整知识体系，涵盖基础语法、高级特性、实践技巧等维度，可作为系统学习或日常开发的参考手册。

一、YAML 基础概述

1. YAML 定义与特点

定义：YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化格式 ，以层级缩进表示数据结构，适合作为配置文件。
核心特点 ：
- 大小写敏感
- 以缩进表示层级关系（禁止使用 Tab，只能用空格）
- 支持复杂数据结构（列表、嵌套对象）
- 语法简洁，可读性强

2. Spring Boot 对 YAML 的支持

Spring Boot 默认集成 YAML 解析（依赖 SnakeYAML 库），无需额外配置。
支持 application.yml 替代传统的 application.properties，且两者可共存（YAML 优先级更高）。

二、YAML 核心语法规则

1. 基本语法规范

键值对 ：key: value（冒号后必须加空格；大小写敏感）
层级缩进 ：用空格表示嵌套关系（必须使用空格，禁用Tab，通常 2 或 4 个空格）；缩进数量代表层级（相同缩进的键属于同一层级）。
注释：# 注释内容（仅支持单行注释）

2. 数据类型

类型	示例	说明
标量	`name: ZhangSan`	字符串、数字、布尔值等
序列	`fruits: [apple, banana]` 或 `fruits:` `- apple` `- banana`	列表/数组
映射	`user:` `name: LiSi` `age: 25`	嵌套对象（键值对集合）

3. 特殊语法

多行字符串 ：
- |：保留换行符（如日志内容）
- >：折叠换行符（如长描述）
引用与合并 ：
- & 定义锚点，* 引用锚点，<<: 合并锚点（用于复用配置）
yaml 复制代码
```
default: &default
  timeout: 30
service:
  <<: *default  # 复用 default 的配置
  port: 8080
```

一、YAML 基本语法规范

YAML 的核心设计是「以人类可读为优先 」，通过缩进和简单符号表达数据结构，无需复杂的标签或括号。

1. 键值对（Key-Value）

YAML 最基础的结构是键值对，格式为 key: value，需注意：

冒号后必须加空格 ：name: ZhangSan（正确），name:ZhangSan（错误）。
大小写敏感 ：Name 和 name 是两个不同的键。

示例（Spring Boot 基础配置）：

yaml 复制代码

server:
  port: 8080  # 键：server.port，值：8080
  servlet:
    context-path: /myapp  # 嵌套键：server.servlet.context-path

2. 层级缩进（表示嵌套关系）

YAML 用空格缩进表示数据的层级关系，需注意：

禁止使用 Tab：必须用空格（通常 2 或 4 个空格，保持一致即可）。
缩进数量代表层级：相同缩进的键属于同一层级。

错误示例（Tab 代替空格）：

yaml 复制代码

server:
	port: 8080  # ❌ 用了 Tab，会导致解析失败

正确示例（嵌套对象）：

yaml 复制代码

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: 123456

3. 注释

YAML 仅支持单行注释 ，用 # 开头，注释内容会被解析器忽略。

yaml 复制代码

# 这是服务器配置
server:
  port: 8080  # 端口号（行内注释）

二、YAML 数据类型

YAML 支持丰富的数据类型，可直接映射到 Java 的基本类型、集合或对象。

1. 标量（Scalar）：单个值

标量是最基础的数据类型，包括字符串、数字、布尔值、Null 等。

类型	示例	说明
字符串	`name: ZhangSan` 或 `name: "Zhang San"`	通常无需引号，含特殊字符（如 `:`、`#`）时需加引号
数字	`age: 25`、`price: 3.14`	支持整数、浮点数
布尔值	`enabled: true`、`flag: false`	直接写 `true`/`false`
Null	`value: null` 或 `value: ~`	表示空值

字符串特殊场景：

含特殊字符时用双引号：path: "C:\\Users\\Admin"（转义字符生效）。
单引号会保留原始内容：desc: 'Hello # World'（# 不会被当作注释）。

2. 序列（Sequence）：列表/数组

序列用于表示一组有序的值，有两种写法：

短横线写法 （推荐，可读性强）：
yaml 复制代码
```
fruits:
  - apple
  - banana
  - orange
```
方括号写法 （紧凑写法）：
yaml 复制代码
```
fruits: [apple, banana, orange]
```

Spring Boot 场景示例（配置拦截路径）：

yaml 复制代码

spring:
  mvc:
    interceptors:
      - path: /api/**
        exclude: /api/login
      - path: /admin/**

3. 映射（Mapping）：嵌套对象

映射用于表示键值对的集合（即 Java 中的 Map 或自定义对象），通过缩进实现嵌套。

示例（自定义配置对象）：

yaml 复制代码

app:
  name: MySpringBootApp
  author:
    name: ZhangSan
    email: zhangsan@example.com
  version: 1.0.0

对应 Java 绑定（@ConfigurationProperties）：

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private Author author; // 嵌套对象
    private String version;
    // getters and setters
}

三、YAML 特殊语法

1. 多行字符串

YAML 提供两种方式处理多行文本，避免在一行写长字符串：

|（保留换行符） ：保留文本中的换行和缩进，适合日志、代码片段。

yaml 复制代码

log:
  content: |
    2024-01-01 10:00:00 INFO  Application started
    2024-01-01 10:00:01 DEBUG  Database connected

>（折叠换行符） ：将换行符替换为空格，适合长描述文本。

yaml 复制代码

desc: >
  这是一个很长的描述文本，
  会被折叠成一行显示，
  但保留空格分隔。

2. 引用与合并（复用配置）

YAML 支持通过**锚点（&）和引用（*）复用配置，结合 合并键（<<:）**可实现配置继承。

示例（复用公共配置）：

yaml 复制代码

# 定义公共配置锚点
default: &default
  timeout: 30
  retry: 3

# 开发环境：复用 default 配置，覆盖 port
dev:
  <<: *default  # 合并 default 的所有键值
  port: 8080

# 生产环境：复用 default 配置，覆盖 port 和 timeout
prod:
  <<: *default
  port: 80
  timeout: 60  # 覆盖 default 的 timeout

四、Spring Boot 特有的 YAML 语法

1. 占位符与默认值

YAML 中可使用 ${key:default} 引用其他配置项，冒号后为默认值（当 key 不存在时使用）。

示例：

yaml 复制代码

app:
  name: MyApp
  full-name: ${app.name:DefaultApp} - v1.0  # 引用 app.name
  temp-path: ${java.io.tmpdir:/tmp}  # 引用系统属性，默认 /tmp

2. 随机值配置

Spring Boot 提供 random.* 前缀生成随机值，常用于测试或临时配置：

yaml 复制代码

app:
  secret: ${random.uuid}  # 随机 UUID
  port: ${random.int(8000,9000)}  # 8000-9000 之间的随机整数
  number: ${random.long}  # 随机长整数

3. 多环境 Profile 配置

YAML 支持通过 spring.profiles 区分不同环境（开发、测试、生产），有两种方式：

单文件多文档块 （用 --- 分隔）：

yaml 复制代码

# 默认配置
spring:
  application:
    name: MyApp

---
# 开发环境配置
spring:
  profiles: dev
server:
  port: 8080

---
# 生产环境配置
spring:
  profiles: prod
server:
  port: 80

多文件方式 ：单独创建 application-dev.yml、application-prod.yml，在 application.yml 中激活：
yaml 复制代码
```
spring:
  profiles:
    active: dev  # 激活开发环境
```

注意事项

缩进错误：必须用空格，禁止 Tab，否则解析失败。
冒号后无空格 ：key:value 会被当作一个字符串，而非键值对。
特殊字符未加引号 ：字符串含 :、#、{、} 等字符时，需用引号包裹，如 url: "http://example.com:8080"。
布尔值/数字被当作字符串 ：enabled: "true" 会被解析为字符串，而非布尔值（去掉引号即可）。

三、Spring Boot 中 YAML 配置优先级

1. 配置文件位置优先级（从高到低）

file:./config/（项目根目录下的 config 文件夹）
file:./（项目根目录）
classpath:/config/（类路径下的 config 文件夹）
classpath:/（类路径根目录，如 resources 文件夹）

2. 多环境配置优先级

激活的 Profile 配置（application-{profile}.yml）覆盖默认配置（application.yml）。
激活方式：spring.profiles.active=dev（在 application.yml 或命令行指定）。

3. 全量配置源优先级（从高到低）

命令行参数（--server.port=8081）
外部配置文件（file:./application.yml）
内部配置文件（classpath:/application.yml）
默认属性（SpringApplication.setDefaultProperties()）

四、YAML vs Properties：对比与选择

维度	YAML	Properties
语法	层级缩进，结构清晰	点号分隔（`server.port=8080`）
数据结构	支持列表、嵌套对象	需特殊处理（如 `list[0]=a`）
可读性	适合复杂配置	适合简单配置
优先级	高于 Properties（同位置时）	低于 YAML

五、Spring Boot 中 YAML 常用配置示例

1. 服务器与 Web 配置

yaml 复制代码

server:
  port: 8080
  servlet:
    context-path: /myapp  # 上下文路径

2. 数据源与持久层配置

yaml 复制代码

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/testdb
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update  # 自动更新表结构

3. 日志配置

yaml 复制代码

logging:
  level:
    root: INFO
    com.example: DEBUG  # 指定包日志级别
  file:
    name: logs/myapp.log  # 日志文件路径

4. 自定义配置

yaml 复制代码

app:
  name: MySpringBootApp
  author:
    name: ZhangSan
    email: zhangsan@example.com

六、YAML 高级特性与进阶用法

1. 多环境 Profile 配置

定义环境配置文件：application-dev.yml（开发）、application-prod.yml（生产）。

在 application.yml 中激活：

yaml 复制代码

spring:
  profiles:
    active: dev  # 激活开发环境

2. 占位符与变量引用

引用配置项：${app.name:DefaultApp}（冒号后为默认值）。
随机值：${random.uuid}、${random.int(1,100)}。

3. 类型安全的配置属性（`@ConfigurationProperties`）

将 YAML 配置绑定到 Java 对象，实现类型安全：

java 复制代码

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private Author author;
    // getters and setters
}

4. YAML 扩展与集成

支持 Spring Cloud Config 配置中心。
可通过 PropertySource 加载自定义 YAML 文件（需额外配置解析器）。

七、常见问题与注意事项

1. 语法陷阱

缩进错误：必须用空格，禁止 Tab。
冒号后无空格 ：key:value 错误，应为 key: value。
特殊字符 ：字符串含 :、# 等字符时需用引号包裹（"key: value"）。

2. 配置优先级混淆

同位置时，application.yml 覆盖 application.properties。
激活的 Profile 配置覆盖默认配置。

3. 编码与乱码

YAML 文件需使用 UTF-8 编码，避免中文乱码。

八、YAML 配置最佳实践

结构分层 ：按模块分组配置（如 server、spring、logging）。
多环境管理：用 Profile 隔离开发、测试、生产配置。
类型安全 ：优先使用 @ConfigurationProperties 绑定配置。
注释与文档：关键配置添加注释，说明用途和默认值。
配置复用 ：用 YAML 锚点（&、*）复用公共配置。

【Spring Boot—— .yml（YAML）】Spring Boot中.yml文件的基础语法、高级特性、实践技巧

文章目录

一、YAML 基础概述

1. YAML 定义与特点

2. Spring Boot 对 YAML 的支持

二、YAML 核心语法规则

1. 基本语法规范

2. 数据类型

3. 特殊语法

一、YAML 基本语法规范

1. 键值对（Key-Value）

2. 层级缩进（表示嵌套关系）

3. 注释

二、YAML 数据类型

1. 标量（Scalar）：单个值

2. 序列（Sequence）：列表/数组

3. 映射（Mapping）：嵌套对象

三、YAML 特殊语法

1. 多行字符串

2. 引用与合并（复用配置）

四、Spring Boot 特有的 YAML 语法

1. 占位符与默认值

2. 随机值配置

3. 多环境 Profile 配置

注意事项

三、Spring Boot 中 YAML 配置优先级

1. 配置文件位置优先级（从高到低）

2. 多环境配置优先级

3. 全量配置源优先级（从高到低）

四、YAML vs Properties：对比与选择

五、Spring Boot 中 YAML 常用配置示例

1. 服务器与 Web 配置

2. 数据源与持久层配置

3. 日志配置

4. 自定义配置

六、YAML 高级特性与进阶用法

1. 多环境 Profile 配置

2. 占位符与变量引用

3. 类型安全的配置属性（@ConfigurationProperties）

4. YAML 扩展与集成

七、常见问题与注意事项

1. 语法陷阱

2. 配置优先级混淆

3. 编码与乱码

八、YAML 配置最佳实践

3. 类型安全的配置属性（`@ConfigurationProperties`）