如何使用 ruamel.yaml 安全合并 YAML 数据（保留注释与格式）

本文介绍如何将新 YAML 片段智能合并到现有 YAML 文件中，避免覆盖已有键、丢失注释或破坏缩进——推荐使用 ruamel.yaml 替代过时且不支持注释的 PyYAML。

在实际的配置管理或 CI/CD 流程中，经常需要向已有的 YAML 文件（比如 foo.yaml）动态追加内容，例如新增一个包列表。但这事儿要是直接字符串拼接，或者用 PyYAML 来处理，麻烦可就大了。PyYAML 基于早已废弃的 YAML 1.1 标准，不光没法保留注释，还会重排格式，丢失锚点与标签，更谈不上什么安全的原地合并逻辑了。

正确的做法，是选用专为可编辑性设计的 ruamel.yaml。它完整支持 YAML 1.2，能原生保留注释、缩进、引号风格和行内格式，并且提供了类似字典的操作接口。这一点特别重要。

下面给出一个完整且健壮的合并示例：

import sys
from pathlib import Path
import ruamel.yaml

yaml = ruamel.yaml.YAML()
yaml.indent(sequence=4, offset=2)  # 统一序列缩进风格
yaml.preserve_quotes = True        # 保留原始引号（如 'value' 或 "value"）

# 加载目标文件和待合并数据
foo = yaml.load(Path('foo.yaml'))
extra = yaml.load(Path('extra.yaml'))  # 或用 yaml.load_string("packages:\n  - 4\n  - 5")

# ✅ 安全合并：若 packages 不存在则创建空列表，否则追加
foo.setdefault('packages', []).extend(extra['packages'])

# ⚠️ 可选：迁移原有注释（如 packages 行尾注释或末尾注释）
if 'packages' in foo and hasattr(foo['packages'], 'ca'):
    fpc = foo['packages'].ca  # 获取注释属性
    if fpc.items:  # 若存在末尾注释（如绑定到最后一个元素）
        last_idx = len(foo['packages']) - 1
        if last_idx in fpc.items:
            # 将原末尾注释迁移至新列表末尾
            new_last_idx = len(foo['packages']) - 1
            fpc.items[new_last_idx] = fpc.items.pop(last_idx)

# 写入标准输出（或替换为 yaml.dump(foo, Path('foo.yaml').open('w'))）
yaml.dump(foo, sys.stdout)

执行之后，foo.yaml 中的 packages 列表会被无缝扩展。原有的注释（比如 # doesn't ha ve to exist）会老老实实待在原位置，新增项按规范缩进，不会影响到其他字段，更不会把整个文件结构搞得乱七八糟。

关键注意事项：

• ❌ 不要使用 PyYAML.load() + dict.update()：这会把所有注释都丢掉，重置格式，还有可能错误地覆盖嵌套结构；
• ✅ 始终用 ruamel.yaml.YAML() 实例（不是 ruamel.yaml.safe_load 这类静态函数），这样才能启用注释与格式保留功能；
• ? 如果需要合并多个键（不止 packages），可以封装成一个通用函数，遍历 extra 的顶层键，然后逐个 setdefault(...).extend(...)；
• ? 写入文件时务必用 yaml.dump(data, file_obj)，别用 str() 或 print()，否则辛辛苦苦保留的注释和格式转眼就没了。

通过 ruamel.yaml，你得到的不仅仅是“能用”的 YAML 操作，而是真正符合工程实践的可审计、可协作、可回溯的配置管理能力。这一点，在大型项目中尤其关键。