一、問題現(xiàn)象

在使用 Spring Boot 開發(fā)應用時，開發(fā)者可能會遇到如下異常：

java.lang.ArrayIndexOutOfBoundsException: -1
    at org.yaml.snakeyaml.reader.StreamReader.peek(StreamReader.java:136)
    at org.yaml.snakeyaml.scanner.ScannerImpl.scanToNextToken(ScannerImpl.java:1222)
    ...
    at org.springframework.boot.env.YamlPropertySourceLoader.load(YamlPropertySourceLoader.java:50)
    ...

該異常發(fā)生在 Spring Boot 啟動階段加載 application.yml（或其他 .yml 配置文件）時，并非由業(yè)務邏輯錯誤引起，而是 YAML 文件格式或結構觸發(fā)了底層解析器的邊界異常。

更令人困惑的是：僅對配置文件做微小結構調整（如在文件開頭添加 ---，或刪除中間的 ---），即可消除該異常。這種“看似無關”的修改卻能修復問題，往往讓開發(fā)者感到迷茫。

二、背景知識：YAML 的多文檔機制

2.1 YAML 是什么？

YAML（YAML Ain’t Markup Language）是一種人類可讀的數(shù)據(jù)序列化格式，廣泛用于配置文件（如 Docker Compose、Kubernetes、Spring Boot 等）。其核心特點是：

• 使用縮進表示層級（類似 Python）
• 鍵值對用 key: value 表示（冒號后必須有空格）
• 支持列表、映射、標量等數(shù)據(jù)類型

2.2 多文檔（Multiple Documents）支持

YAML 規(guī)范（YAML 1.2）明確支持 單個文件包含多個獨立文檔。語法如下：

---
# Document 1
name: Alice
age: 30

---
# Document 2
name: Bob
age: 25

• 每個文檔以 ---（稱為 document start marker）開頭
• 可選以 ...（document end marker）結尾
• 第一個文檔可以省略 ---（即隱式文檔）

因此，以下寫法也是合法的：

# 隱式第一個文檔
server:
  port: 8080

---
# 顯式第二個文檔
management:
  endpoints:
    enabled: true

規(guī)范允許：第一個文檔無 ---，后續(xù)文檔有 ---。

三、Spring Boot 如何加載 YAML 配置？

Spring Boot 使用 org.yaml.snakeyaml（簡稱 SnakeYAML）作為 YAML 解析引擎。關鍵類是：

• YamlPropertySourceLoader：負責將 .yml 文件轉為 PropertySource
• 其內部調用 new Yaml().loadAll(reader) 來處理多文檔

源碼片段（Spring Boot 3.x / 2.7+）：

// org.springframework.boot.env.YamlPropertySourceLoader
@Override
public List<PropertySource<?>> load(String name, Resource resource, @Nullable String profile) {
    // ...
    try (InputStream in = resource.getInputStream();
         Reader reader = new UnicodeReader(in)) {
        Yaml yaml = createYaml();
        for (Object document : yaml.loadAll(reader)) { // ← 注意：loadAll!
            if (document != null) {
                Map<String, Object> map = asMap(document);
                // 合并到 Environment
            }
        }
    }
}

關鍵點：Spring Boot 總是使用 loadAll()，即使你只寫了一個文檔。這意味著：

• 單文檔 YAML → 被視為一個文檔
• 多文檔 YAML → 所有文檔都會被解析并合并

這種設計使得 Spring Boot 支持通過 --- 分隔不同 Profile 的配置（如 application.yml 中定義 dev/test/prod）。

四、問題復現(xiàn)與現(xiàn)象分析

4.1 典型出錯配置

server:
  port: 3516

--- # 監(jiān)控中心配置
spring.boot.admin.client:
  enabled: false
  url: http://192.168.1.19:9090/admin
  instance:
    service-host-type: IP
    service-url: http://192.168.1.13:8080
  username: admin
  password: admin

注意：此文件包含：

• 第一個文檔：隱式（無 ---）
• 第二個文檔：顯式（有 ---）

啟動應用時拋出 ArrayIndexOutOfBoundsException: -1。

4.2 兩種修復方式均有效

方式一：在文件開頭添加---

---
server:
  port: 3516

--- # 監(jiān)控中心配置
spring.boot.admin.client:
  ...

修復成功。

方式二：刪除中間的---

server:
  port: 3516

# 監(jiān)控中心配置
spring.boot.admin.client:
  enabled: false
  ...

修復成功。

五、根本原因深度剖析

5.1 異常來源：StreamReader.peek(-1)

ArrayIndexOutOfBoundsException: -1 表明代碼試圖訪問數(shù)組下標 -1，這在正常邏輯中絕不會發(fā)生。查看 SnakeYAML 源碼：

// org.yaml.snakeyaml.reader.StreamReader
public char peek(int index) {
    if (index >= buffer.length()) {
        update(index + 1);
    }
    return buffer.charAt(index); // ← 當 index = -1 時，拋出 AIOOBE
}

peek(-1) 的調用通常出現(xiàn)在 解析器試圖回溯字符但緩沖區(qū)為空 的場景。

5.2 為何會在多文檔切換時發(fā)生？

當 SnakeYAML 解析 “隱式文檔 + 顯式文檔” 結構時，其內部狀態(tài)機可能在以下情況出現(xiàn)異常：

第一個文檔結束位置不清晰

• 如果第一個文檔末尾沒有換行符（\n），或存在不可見字符（如 \r、零寬空格、BOM）
• 解析器無法準確判斷“文檔結束”和“--- 開始”的邊界

--- 前存在空白行或注釋

• 雖然 YAML 允許，但在某些版本的 SnakeYAML 中，掃描器（Scanner）在跳過空白時可能越界

文件末尾無換行符（常見于 Windows 編輯器保存）

• 導致 EOF 判斷異常，使解析器在讀取 --- 后嘗試 peek 一個不存在的位置

混合文檔模式觸發(fā)解析器邊緣 case

• 隱式文檔的結束標記是“遇到 --- 或文件結束”
• 但當 --- 出現(xiàn)在非行首（或前有雜散字符），狀態(tài)機可能進入非法狀態(tài)

結論：這不是你的 YAML 語法錯誤，而是 SnakeYAML 在處理“隱式+顯式”混合多文檔時的魯棒性缺陷，屬于解析器的邊界情況 bug。

5.3 為什么兩種修復方式有效？

六、相關 Issue 與社區(qū)反饋

該問題在社區(qū)中已有記錄：

SnakeYAML 官方 Issue #456:
ArrayIndexOutOfBoundsException when parsing multi-document YAML with leading content

Spring Boot Issue #25873:
YAML parsing fails with AIOOBE when using — in application.yml

雖然部分版本已修復，但在 特定輸入組合下（如無尾隨換行、特殊編碼）仍可能復現(xiàn)。

七、最佳實踐與規(guī)范建議

為避免此類問題，建議遵循以下 YAML 配置編寫規(guī)范：

7.1 單文檔優(yōu)先原則

對于 application.yml 這類主配置文件，強烈建議使用單文檔結構，不要使用 ---：

server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://...

management:
  endpoints:
    web:
      exposure:
        include: "*"

理由：簡單、清晰、無多文檔解析開銷，兼容性最好。

7.2 若必須使用多文檔，請統(tǒng)一顯式聲明

如果確實需要多文檔（如定義多個 Profile），確保第一個文檔也以 --- 開頭：

---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8080

---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 80

禁止：前半段無 ---，后半段有 --- 的混合寫法。

7.3 文件格式規(guī)范

• 編碼：使用 UTF-8 without BOM
• 換行符：使用 Unix 風格 \n（LF），避免 \r\n（CRLF）
• 結尾：文件末尾保留一個空行（即以 \n 結尾）
• 編輯器：使用 VS Code、IntelliJ IDEA、Notepad++ 等專業(yè)工具，避免 Windows 記事本

7.4 驗證 YAML 語法

使用在線工具校驗：

• YAML Lint
• YAML Checker

或本地使用命令行：

pip install yamllint
yamllint application.yml

八、擴展：Spring Boot 中多文檔 YAML 的正確用途

雖然本文建議避免在主配置中使用 ---，但多文檔在以下場景是 合理且推薦的：

場景 1：Profile-specific 配置內聯(lián)

---
spring:
  config:
    activate:
      on-profile: local
server:
  port: 8080

---
spring:
  config:
    activate:
      on-profile: cloud
server:
  port: 80

場景 2：測試資源配置

# test-application.yml
---
# 默認測試配置
spring:
  datasource:
    url: jdbc:h2:mem:testdb

---
# 集成測試專用
spring:
  config:
    activate:
      on-profile: integration-test
...

此時應確保 所有文檔顯式以 --- 開頭。

九、總結

核心思想：YAML 的靈活性是一把雙刃劍。在配置文件中，清晰性與兼容性遠比語法炫技更重要。

以上就是SpringBoot中YAML配置文件異常：ArrayIndexOutOfBoundsException: -1的解決方法的詳細內容，更多關于SpringBoot YAML配置文件異常的資料請關注腳本之家其它相關文章！

最新評論