解决 Spring Boot 中 YAML 配置文件的 `ArrayIndexOutOfBoundsException: -1` 异常

一、问题现象

在使用 Spring Boot 开发应用时，开发者可能会遇到如下异常：

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)
    ...

该异常发生在 Spring Boot 启动阶段加载 application.yml（或其他 .yml 配置文件）时，并非由业务逻辑错误引起，而是 YAML 文件格式或结构触发了底层解析器的边界异常。

更令人困惑的是：仅对配置文件做微小结构调整（如在文件开头添加 ---，或删除中间的 ---），即可消除该异常。这种"看似无关"的修改却能修复问题，往往让开发者感到迷茫。

---

二、背景知识：YAML 的多文档机制

2.1 YAML 是什么？

YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化格式，广泛用于配置文件（如 Docker Compose、Kubernetes、Spring Boot 等）。其核心特点是：

• 使用缩进表示层级（类似 Python）
• 键值对用 key: value 表示（冒号后必须有空格）
• 支持列表、映射、标量等数据类型

2.2 多文档（Multiple Documents）支持

YAML 规范（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

✅ 规范允许 ：第一个文档无 ---，后续文档有 ---。

---

三、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）。

---

四、问题复现与现象分析

4.1 典型出错配置

server:
  port: 3516

--- # 监控中心配置
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

--- # 监控中心配置
spring.boot.admin.client:
  ...

✅ 修复成功。

方式二：删除中间的 ---

server:
  port: 3516

# 监控中心配置
spring.boot.admin.client:
  enabled: false
  ...

✅ 修复成功。

---

五、根本原因深度剖析

5.1 异常来源：StreamReader.peek(-1)

ArrayIndexOutOfBoundsException: -1 表明代码试图访问数组下标 -1，这在正常逻辑中绝不会发生。查看 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) 的调用通常出现在 解析器试图回溯字符但缓冲区为空 的场景。

5.2 为何会在多文档切换时发生？

当 SnakeYAML 解析 "隐式文档 + 显式文档" 结构时，其内部状态机可能在以下情况出现异常：

1. 第一个文档结束位置不清晰

   • 如果第一个文档末尾没有换行符（\n），或存在不可见字符（如 \r、零宽空格、BOM）
   • 解析器无法准确判断"文档结束"和"--- 开始"的边界

2. --- 前存在空白行或注释

   • 虽然 YAML 允许，但在某些版本的 SnakeYAML 中，扫描器（Scanner）在跳过空白时可能越界

3. 文件末尾无换行符（常见于 Windows 编辑器保存）

   • 导致 EOF 判断异常，使解析器在读取 --- 后尝试 peek 一个不存在的位置

4. 混合文档模式触发解析器边缘 case

   • 隐式文档的结束标记是"遇到 --- 或文件结束"
   • 但当 --- 出现在非行首（或前有杂散字符），状态机可能进入非法状态

📌 结论 ：这不是你的 YAML 语法错误，而是 SnakeYAML 在处理"隐式+显式"混合多文档时的鲁棒性缺陷，属于解析器的边界情况 bug。

5.3 为什么两种修复方式有效？

修复方式	机制解释
开头加 ---	使所有文档均为显式，解析器能清晰识别每个文档边界，避免状态混淆
删除中间 ---	退化为单文档，绕过多文档解析逻辑，从根本上避开问题

---

六、相关 Issue 与社区反馈

该问题在社区中已有记录：

• 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

虽然部分版本已修复，但在 特定输入组合下（如无尾随换行、特殊编码）仍可能复现。

---

七、最佳实践与规范建议

为避免此类问题，建议遵循以下 YAML 配置编写规范：

✅ 7.1 单文档优先原则

对于 application.yml 这类主配置文件，强烈建议使用单文档结构 ，不要使用 ---：

server:
  port: 8080

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

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

理由：简单、清晰、无多文档解析开销，兼容性最好。

✅ 7.2 若必须使用多文档，请统一显式声明

如果确实需要多文档（如定义多个 Profile），确保第一个文档也以 --- 开头：

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

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

禁止 ：前半段无 ---，后半段有 --- 的混合写法。

✅ 7.3 文件格式规范

• 编码 ：使用 UTF-8 without BOM
• 换行符 ：使用 Unix 风格 \n（LF），避免 \r\n（CRLF）
• 结尾 ：文件末尾保留一个空行（即以 \n 结尾）
• 编辑器：使用 VS Code、IntelliJ IDEA、Notepad++ 等专业工具，避免 Windows 记事本

✅ 7.4 验证 YAML 语法

使用在线工具校验：

• YAML Lint
• YAML Checker

或本地使用命令行：

pip install yamllint
yamllint application.yml

---

八、扩展：Spring Boot 中多文档 YAML 的正确用途

虽然本文建议避免在主配置中使用 ---，但多文档在以下场景是 合理且推荐的：

场景 1：Profile-specific 配置内联

---
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
...

✅ 此时应确保 所有文档显式以 --- 开头。

---

九、总结

问题	根本原因	解决方案
ArrayIndexOutOfBoundsException: -1	SnakeYAML 在解析"隐式文档 + 显式文档"混合结构时状态异常	1. 全部使用单文档 2. 或所有文档显式以 --- 开头
配置文件看似合法却报错	边界字符（换行、BOM、空白）影响解析器状态	规范文件编码、换行、结尾
修改无关内容却修复问题	实际改变了文档结构，绕过了解析器 bug	理解 YAML 多文档机制，避免脆弱写法

核心思想 ：YAML 的灵活性是一把双刃剑。在配置文件中，清晰性与兼容性远比语法炫技更重要。