Spring Boot 中 YAML 配置文件詳解

在 Spring Boot 項目中，配置文件是不可或缺的一部分，用于自定義應用行為、覆蓋默認設置。除了傳統的 properties 文件，Spring Boot 對 YAML（YAML Ain’t Markup Language）格式提供了完美支持。YAML 以其簡潔的語法、清晰的層級結構，成為許多開發者的首選配置方式。

一、YAML 是什么？為什么用 YAML？

YAML 是一種數據序列化格式，設計目標是易讀易寫，同時兼顧機器解析效率。與傳統的 properties 文件相比，YAML 具有以下優勢：

• 層級結構清晰：通過縮進表示配置之間的父子關系，避免了 properties 中重復的前綴（如 server.port、server.servlet.context-path）。
• 支持復雜數據類型：原生支持對象、列表、Map 等復雜結構，無需額外語法。
• 語法簡潔：去掉了 properties 中的等號和多余標點，減少冗余代碼。

Spring Boot 會自動加載 resources 目錄下的 application.yml 或 application.yaml 文件，其優先級與 application.properties 一致（可通過配置位置調整優先級）。

二、YAML 基礎語法規則

使用 YAML 時，需遵守以下核心規則，否則可能導致配置加載失敗：

1. 大小寫敏感：name 和 Name 代表不同的配置項。
2. 縮進表示層級：使用空格（不允許使用 Tab）縮進，縮進數量不限，但同級配置必須對齊。
3. 鍵值對格式：鍵與值之間用冒號加空格分隔（如 key: value），冒號后必須有空格。
4. 注釋：以 # 開頭的行為注釋，會被忽略。
5. 字符串無需引號：默認情況下，字符串可以不加引號；若包含特殊字符（如空格、冒號），需用單引號或雙引號包裹。

示例：

# 基本鍵值對
server:port: 8080  # 端口配置servlet:context-path: /demo  # 上下文路徑# 字符串配置（含特殊字符）
app:title: "Spring Boot: YAML 教程"  # 雙引號保留特殊字符description: 'Hello: World'      # 單引號也支持

三、YAML 配置常見數據類型

YAML 支持多種數據類型，從簡單值到復雜結構均可輕松表示，以下是開發中常用的類型及示例：

1. 簡單數據類型

包括字符串、數字、布爾值等，直接以 key: value 形式定義：

# 簡單數據類型示例
user:id: 1001          # 數字name: 張三         # 字符串isVip: true        # 布爾值score: 98.5        # 浮點數joinDate: 2023-10-01  # 日期（字符串形式）

2. 對象類型

用于表示包含多個屬性的實體，支持兩種寫法：

• 縮進式：通過縮進體現屬性層級。
• 行內式：用 {} 包裹，屬性之間用逗號分隔。

示例：

# 對象配置（縮進式）
user1:name: 張三age: 20address: 北京# 對象配置（行內式）
user2: {name: 李四, age: 22, address: 上海}

3. 集合類型

包括列表（List）和集合（Set），支持兩種寫法：

• 短橫線式：每個元素前加 - （短橫線+空格）。
• 行內式：用 [] 包裹，元素之間用逗號分隔。

示例：

# 列表配置（短橫線式）
city1:- 北京- 上海- 廣州# 列表配置（行內式）
city2: [北京, 上海, 廣州]# 集合中的元素是對象
students:- id: 1name: 張三age: 20- id: 2name: 李四age: 22

?? 注意：短橫線與元素值之間必須有空格，否則會解析錯誤 。

四、Spring Boot 中 YAML 的核心應用

1. 覆蓋默認配置

Spring Boot 有許多默認配置（如 Tomcat 端口、日志級別等），可通過 YAML 覆蓋：

# 覆蓋服務器配置
server:port: 8888  # 端口改為 8888（默認 8080）tomcat:max-threads: 200  # Tomcat 最大線程數# 日志配置
logging:level:root: info  # 根日志級別com.example: debug  # 自定義包日志級別

2. 自定義配置與讀取

除了框架默認配置，還可在 YAML 中定義自定義配置，再通過代碼讀取使用。

方式 1：@Value 注解（適合簡單配置）

@Value 可直接映射 YAML 中的簡單值（如字符串、數字），語法為 ${key}：

# 自定義配置
app:name: 我的應用version: 1.0.0authors:- 張三- 李四

代碼中讀取：

@Controller
public class YamlController {@Value("${app.name}")private String appName;  // 映射 "我的應用"@Value("${app.version}")private String appVersion;  // 映射 "1.0.0"@Value("${app.authors[0]}")  // 讀取列表第一個元素private String firstAuthor;  // 映射 "張三"// 業務方法...
}

?? 注意：@Value 僅支持簡單類型，無法直接映射對象或復雜集合 。

方式 2：@ConfigurationProperties（適合對象/復雜配置）

當配置項較多或為對象結構時，推薦使用 @ConfigurationProperties 將配置批量映射到實體類：

1. 定義實體類并綁定配置前綴：

@Component
@ConfigurationProperties(prefix = "user")  // 綁定前綴 "user"
public class UserConfig {private Integer id;private String name;private List<String> address;  // 映射列表// getter + setter（必須存在，否則無法綁定）
}

2. YAML 配置：

# 用戶配置（與實體類對應）
user:id: 1001name: 張三address:- 北京- 上海

3. 使用時直接注入實體類：

@Controller
public class UserController {@Autowiredprivate UserConfig userConfig;  // 自動注入配置@GetMapping("/user")@ResponseBodypublic String getUser() {return "ID: " + userConfig.getId() + ", 姓名: " + userConfig.getName();}
}

3. 占位符與動態配置

YAML 支持通過 ${} 引用其他配置項或使用框架提供的工具類生成動態值：

引用其他配置

server:port: 8080
app:url: http://localhost:${server.port}/demo  # 引用 server.port 的值

生成隨機值

Spring Boot 提供 random 工具類，可生成隨機數、UUID 等：

# 隨機值示例
config:randomInt: ${random.int}  # 隨機整數randomIntRange: ${random.int(100, 200)}  # 100-200 之間的隨機整數randomUUID: ${random.uuid}  # 隨機 UUIDrandomLong: ${random.long}  # 隨機長整數

五、YAML 配置文件的優先級

Spring Boot 會從多個位置加載 application.yml，優先級從高到低如下（高優先級配置會覆蓋低優先級）：

1. 項目根目錄下的 /config 子目錄（./config/application.yml）
2. 項目根目錄（./application.yml）
3. resources 目錄下的 /config 子目錄（classpath:/config/application.yml）
4. resources 目錄（classpath:/application.yml）

可根據需求將配置文件放在不同位置，例如：

• 開發環境配置放在 resources/config 中，方便修改。
• 生產環境配置放在項目根目錄的 config 中，避免打包到 Jar 包內。

六、常見問題與解決方案

1. 配置不生效？

   • 檢查語法：是否漏寫冒號后的空格、縮進是否正確。
   • 檢查路徑：配置文件是否在 resources 目錄或指定的優先級目錄中。
   • 檢查注解：使用 @ConfigurationProperties 時，確保實體類有 getter/setter 方法。

2. 中文亂碼？

   • 確保 YAML 文件編碼為 UTF-8（IDEA 中可在 File -> Settings -> Editor -> File Encodings 中設置）。

3. 如何區分多環境？

   • 創建多環境配置文件，如 application-dev.yml（開發）、application-prod.yml（生產），通過 spring.profiles.active=dev 指定激活環境。

總結

YAML 以其簡潔的語法和強大的表達能力，成為 Spring Boot 配置的優選格式。掌握 YAML 的基礎語法、數據類型映射及實戰技巧，能顯著提升配置文件的可讀性和維護性。在實際開發中，建議結合 @ConfigurationProperties 管理復雜配置，并合理利用多環境配置和優先級規則，讓配置更加靈活高效。