本文介绍如何使用 PyYAML 自定义字符串表示器，确保 JSON 内容作为多行字面量（|-）而非内联字符串被序列化，从而在 Kubernetes 配置（如 ConfigMap）的 YAML round-trip 场景中保持格式兼容性与可读性。
本文介绍如何使用 pyyaml 自定义字符串表示器，确保 json 内容作为多行字面量（`|-`）而非内联字符串被序列化，从而在 kubernetes 配置（如 configmap）的 yaml round-trip 场景中保持格式兼容性与可读性。
在处理 Kubernetes 资源（如 ConfigMap）时，常需用 Python 加载 YAML、修改嵌套的 JSON 数据（例如 data["sample.json"] 中的内容），再将其安全地写回 YAML。但默认情况下，PyYAML 会将含换行符的字符串转为带引号的折叠形式（如 "[\n {\n \"name\": ...}"），破坏原始 |- 字面量块结构，导致 kubectl apply 解析异常或 Git 差异混乱。
解决关键在于覆盖 PyYAML 对 str 类型的默认表示逻辑，使其对含换行符的字符串自动采用 | 风格（保留换行与缩进），对单行字符串仍用普通格式。以下为完整实现：
import yaml
def str_presenter(dumper, data):
"""自定义字符串表示器：含换行符时使用 |- 块字面量，否则用普通字符串"""
if '\n' in data:
return dumper.represent_scalar('tag:yaml.org,2002:str', data, style='|')
return dumper.represent_scalar('tag:yaml.org,2002:str', data)
# 注册全局表示器（影响后续所有 yaml.dump 调用）
yaml.add_representer(str, str_presenter)
# 示例：加载并修改 ConfigMap
configmap_yaml = """apiVersion: v1
kind: ConfigMap
metadata:
name: sample-map
data:
sample.json: |-
[
{
"name": "foo",
"description": "bar"
}
]"""
# 安全加载（推荐使用 SafeLoader）
data = yaml.load(configmap_yaml, Loader=yaml.SafeLoader)
# 修改 JSON 内容（例如追加一项）
import json
json_data = json.loads(data['data']['sample.json'])
json_data.append({"name": "baz", "description": "qux"})
data['data']['sample.json'] = json.dumps(json_data, indent=2)
# 转储 —— 此时 sample.json 将保持 |- 格式
print(yaml.dump(data, default_flow_style=False, sort_keys=False))
✅ 输出效果（保留 |- 与原始缩进）：
apiVersion: v1
kind: ConfigMap
metadata:
name: sample-map
data:
sample.json: |-
[
{
"name": "foo",
"description": "bar"
},
{
"name": "baz",
"description": "qux"
}
]
⚠️ 注意事项：
- sort_keys=False 是必需的，否则字段顺序（如 apiVersion/kind）可能被打乱，虽不影响 Kubernetes 解析，但降低可读性与 diff 友好度；
- default_flow_style=False 确保嵌套结构始终以块格式输出，避免意外的内联表示；
- 若需严格保持原始键序（如 metadata 在 data 之前），建议使用 yaml.CLoader + collections.OrderedDict（Python
- 此方案不改变 YAML 解析行为，仅影响序列化（dump）阶段，对 load() 无副作用。
通过该方法，即可在 Python 中可靠实现 Kubernetes YAML 的“无损 round-trip”修改，兼顾语义正确性与运维友好性。
