Spring Boot 中 YAML 配置文件詳解

在 Spring Boot 項(xiàng)目中，配置文件是不可或缺的一部分，用于自定義應(yīng)用行為、覆蓋默認(rèn)設(shè)置。除了傳統(tǒng)的 properties 文件，Spring Boot 對(duì) YAML（YAML Ain’t Markup Language）格式提供了完美支持。YAML 以其簡(jiǎn)潔的語法、清晰的層級(jí)結(jié)構(gòu)，成為許多開發(fā)者的首選配置方式。

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

YAML 是一種數(shù)據(jù)序列化格式，設(shè)計(jì)目標(biāo)是易讀易寫，同時(shí)兼顧機(jī)器解析效率。與傳統(tǒng)的 properties 文件相比，YAML 具有以下優(yōu)勢(shì)：

• 層級(jí)結(jié)構(gòu)清晰：通過縮進(jìn)表示配置之間的父子關(guān)系，避免了 properties 中重復(fù)的前綴（如 server.port、server.servlet.context-path）。
• 支持復(fù)雜數(shù)據(jù)類型：原生支持對(duì)象、列表、Map 等復(fù)雜結(jié)構(gòu)，無需額外語法。
• 語法簡(jiǎn)潔：去掉了 properties 中的等號(hào)和多余標(biāo)點(diǎn)，減少冗余代碼。

Spring Boot 會(huì)自動(dòng)加載 resources 目錄下的 application.yml 或 application.yaml 文件，其優(yōu)先級(jí)與 application.properties 一致（可通過配置位置調(diào)整優(yōu)先級(jí)）。

二、YAML 基礎(chǔ)語法規(guī)則

使用 YAML 時(shí)，需遵守以下核心規(guī)則，否則可能導(dǎo)致配置加載失敗：

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

示例：

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

三、YAML 配置常見數(shù)據(jù)類型

YAML 支持多種數(shù)據(jù)類型，從簡(jiǎn)單值到復(fù)雜結(jié)構(gòu)均可輕松表示，以下是開發(fā)中常用的類型及示例：

1. 簡(jiǎn)單數(shù)據(jù)類型

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

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

2. 對(duì)象類型

用于表示包含多個(gè)屬性的實(shí)體，支持兩種寫法：

• 縮進(jìn)式：通過縮進(jìn)體現(xiàn)屬性層級(jí)。
• 行內(nèi)式：用 {} 包裹，屬性之間用逗號(hào)分隔。

示例：

# 對(duì)象配置（縮進(jìn)式）
user1:
  name: 張三
  age: 20
  address: 北京
# 對(duì)象配置（行內(nèi)式）
user2: {name: 李四, age: 22, address: 上海}

3. 集合類型

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

• 短橫線式：每個(gè)元素前加 - （短橫線+空格）。
• 行內(nèi)式：用 [] 包裹，元素之間用逗號(hào)分隔。

示例：

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

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

四、Spring Boot 中 YAML 的核心應(yīng)用

1. 覆蓋默認(rèn)配置

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

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

2. 自定義配置與讀取

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

方式 1：@Value 注解（適合簡(jiǎn)單配置）

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

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

代碼中讀?。?/p>

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

?? 注意：@Value 僅支持簡(jiǎn)單類型，無法直接映射對(duì)象或復(fù)雜集合 。

方式 2：@ConfigurationProperties（適合對(duì)象/復(fù)雜配置）

當(dāng)配置項(xiàng)較多或?yàn)閷?duì)象結(jié)構(gòu)時(shí)，推薦使用 @ConfigurationProperties 將配置批量映射到實(shí)體類：

1. 定義實(shí)體類并綁定配置前綴：

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

2. YAML 配置：

# 用戶配置（與實(shí)體類對(duì)應(yīng)）
user:
  id: 1001
  name: 張三
  address:
    - 北京
    - 上海

3. 使用時(shí)直接注入實(shí)體類：

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

3. 占位符與動(dòng)態(tài)配置

YAML 支持通過 ${} 引用其他配置項(xiàng)或使用框架提供的工具類生成動(dòng)態(tài)值：

引用其他配置

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

生成隨機(jī)值

Spring Boot 提供 random 工具類，可生成隨機(jī)數(shù)、UUID 等：

# 隨機(jī)值示例
config:
  randomInt: ${random.int}  # 隨機(jī)整數(shù)
  randomIntRange: ${random.int(100, 200)}  # 100-200 之間的隨機(jī)整數(shù)
  randomUUID: ${random.uuid}  # 隨機(jī) UUID
  randomLong: ${random.long}  # 隨機(jī)長(zhǎng)整數(shù)

五、YAML 配置文件的優(yōu)先級(jí)

Spring Boot 會(huì)從多個(gè)位置加載 application.yml，優(yōu)先級(jí)從高到低如下（高優(yōu)先級(jí)配置會(huì)覆蓋低優(yōu)先級(jí)）：

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

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

• 開發(fā)環(huán)境配置放在 resources/config 中，方便修改。
• 生產(chǎn)環(huán)境配置放在項(xiàng)目根目錄的 config 中，避免打包到 Jar 包內(nèi)。

六、常見問題與解決方案

• 配置不生效？
  • 檢查語法：是否漏寫冒號(hào)后的空格、縮進(jìn)是否正確。
  • 檢查路徑：配置文件是否在 resources 目錄或指定的優(yōu)先級(jí)目錄中。
  • 檢查注解：使用 @ConfigurationProperties 時(shí)，確保實(shí)體類有 getter/setter 方法。
• 中文亂碼？
  • 確保 YAML 文件編碼為 UTF-8（IDEA 中可在 File -> Settings -> Editor -> File Encodings 中設(shè)置）。
• 如何區(qū)分多環(huán)境？
  • 創(chuàng)建多環(huán)境配置文件，如 application-dev.yml（開發(fā)）、application-prod.yml（生產(chǎn)），通過 spring.profiles.active=dev 指定激活環(huán)境。

總結(jié)

YAML 以其簡(jiǎn)潔的語法和強(qiáng)大的表達(dá)能力，成為 Spring Boot 配置的優(yōu)選格式。掌握 YAML 的基礎(chǔ)語法、數(shù)據(jù)類型映射及實(shí)戰(zhàn)技巧，能顯著提升配置文件的可讀性和維護(hù)性。在實(shí)際開發(fā)中，建議結(jié)合 @ConfigurationProperties 管理復(fù)雜配置，并合理利用多環(huán)境配置和優(yōu)先級(jí)規(guī)則，讓配置更加靈活高效。

到此這篇關(guān)于Spring Boot 中 YAML 配置文件詳解的文章就介紹到這了,更多相關(guān)Spring Boot  YAML 配置文件內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論