Go-Jsonnet解析YAML时遇到文档分隔符的注意事项

在Go-Jsonnet项目中，使用std.parseYaml函数解析YAML内容时，开发者需要注意一个特殊行为：当YAML值中包含三个连续的连字符(---)时，解析结果会从对象(Object)意外转变为数组(Array)。这个现象源于YAML规范中的文档分隔符处理机制。

问题现象

通过对比测试可以清晰观察到这个行为差异：

1. 正常情况（值中不含---）

std.parseYaml('key: "value"')
// 输出: {"key": "value"}

2. 异常情况（值包含---前缀）

std.parseYaml('key: "---value"')
/* 输出变为数组格式:
[{
  "key": "---value"
}]
*/

3. 边界情况（两个连字符不受影响）

std.parseYaml('key: "--value"')
// 正常输出: {"key": "--value"}

技术背景

这种现象的根本原因在于YAML规范中将三个连字符(---)定义为正式的文档分隔符。当解析器检测到这个模式时：

1. 会认为当前文档结束
2. 自动开启新文档
3. 最终将多个文档包装为数组输出

Go-Jsonnet在v0.20.0及之前版本严格遵循这个规范，导致即使---出现在字符串值中也会触发文档分割。

解决方案

该问题已在v0.21.0版本中得到修复。新版本的解析器能够正确区分：

• 真正的文档分隔符（位于行首的---）
• 字符串内容中的连字符组合

建议开发者通过以下方式应对：

1. 升级到v0.21.0或更高版本
2. 临时方案：对含---的值进行Base64编码处理
3. 在必须使用旧版本时，避免在YAML值中使用三个连续连字符

最佳实践

处理可能包含特殊字符的YAML时，建议：

// 防御性编码方案
local encodedValue = std.base64Encode("---secureValue");
std.parseYaml('key: "%s"' % encodedValue)

理解这个特性有助于开发者在处理证书、密钥等可能包含连字符组合的敏感数据时避免意外行为，确保配置文件的正确解析。