使用Chi与Golang实现REST接口动态返回文件时的YAML格式异常

我有一个REST接口，接收YAML文件并转换为结构体后存储到MongoDB中。原YAML内容如下：

_id: someID
name: someName
multiline: |>
    blah blah many lines
    blah blah many lines
    blah blah many lines
    blah blah many lines
prop: 1

另有一个接口负责逆向流程，根据ID返回文件，实现代码如下：

func (h SomeHandler) DownloadAsFile(w http.ResponseWriter, r *http.Request) {
    someID := chi.URLParam(r, "someId")

    obj, err := h.usecase.GetObj(r.Context(), someID)
    // ... 错误处理逻辑 .... 

    bys, err := yaml.Marshal(obj)
    // ... 错误处理逻辑 .... 

    w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%s.yml", ruleName))
    w.Header().Set("Content-Type", "application/octet-stream; charset=utf8")
    w.Header().Add("Content-Type", "charset=utf8")
    w.WriteHeader(http.StatusOK)
    render.Data(w, r, bys)
}

该接口在Chrome和Postman中均可正常下载文件，但下载后的YAML出现格式变化：

_id: someID
name: someName
multiline: |4
    blah blah many lines
    blah blah many lines
    blah blah many lines
    blah blah many lines
prop: 1

其中多行标记的|>变为|4，虽经在线验证仍为有效YAML，但担心存在其他未发现的符号变化，特此询问原因。

1. |> 转 |4 的核心原因 #

YAML里的|>是折叠块标量，会把块内的换行符折叠成空格（末尾换行除外）；|4是字面量块标量，其中4表示内容的缩进级别为4个空格。

出现这个变化的本质是：你使用的Go YAML库（大概率是gopkg.in/yaml.v2或v3）在解析YAML到结构体时，不会保留原始的块标量样式信息——结构体的multiline字段只是一个普通字符串，仅存储了内容里的换行和缩进。当重新序列化时，库会检测到字符串包含换行和固定缩进，自动选择字面量样式输出，并标注对应的缩进级别4。

2. 其他可能的格式差异 #

Go YAML库的序列化逻辑符合YAML规范，不会破坏语义，但可能存在以下格式层面的变化：

• 字符串引号：如果字符串包含特殊字符（如冒号、空格开头），库会自动添加引号，而原始YAML可能无引号
• 映射键顺序：YAML 1.2不强制映射键的顺序，若未做特殊配置，序列化后的键顺序可能和原始不一致（yaml.v3可通过MapSlice或相关标签保留顺序）
• 空值表示：原始YAML的空值可能被序列化为null，或根据结构体字段零值逻辑处理

3. 如何保留原始YAML样式（可选） #

如果需要严格保留原始的块标量样式（比如|>），不能用普通字符串字段存储，需使用YAML库提供的自定义类型保留节点信息。以gopkg.in/yaml.v3为例，用yaml.Node类型存储字段，即可完整保留原始格式：

type YourStruct struct {
    ID        string      `yaml:"_id"`
    Name      string      `yaml:"name"`
    Multiline yaml.Node   `yaml:"multiline"`
    Prop      int         `yaml:"prop"`
}

内容的提问来源于stack exchange，提问作者Matias Barrios