Go encoding/xml Encoder.Indent 怎样让 XML 输出保持层级格式

我在把 Go 结构体写成配置文件时，最常遇到的不是 XML 编码失败，而是输出挤在一行，人工排查节点层级很费劲。要让流式编码器输出可读的 XML，核心写法只有两步：创建 xml.Encoder 后调用 Indent(prefix, indent)，再调用 Encode。其中 prefix 是每个元素所在行的固定前缀，indent 会按嵌套深度重复。

官方参考：https://pkg.go.dev/encoding/xml#Encoder.Indent

最稳妥的默认值是 enc.Indent("", " ")：不增加行首前缀，每深入一层多两个空格。它只改变输出排版，不替你补 XML 声明，也不替你修复错误的结构。

先把三个对象和两个参数分清

xml.NewEncoder(w) 把 XML 写到给定的 io.Writer，常见目标是文件、HTTP 响应或 bytes.Buffer。Indent 记录排版规则，Encode 再按这个规则写出值。官方文档对它的定义是：每个元素从新行开始，行首先放 prefix，再根据嵌套深度重复 indent。

prefix 和 indent 不是一回事。前者适合给整份 XML 加统一的行首标记，后者才是层级缩进单位；大多数配置文件场景把 prefix 设为空字符串即可。如果把两者都写成空字符串，编码仍然有效，只是不会得到漂亮的层级排版。

用 Encoder.Indent 输出一份可读 XML

下面的例子把一个服务配置写入内存缓冲区。结构体标签负责决定元素名称和嵌套关系，Indent 只负责在编码阶段安排换行和空格。这样排版和数据结构各司其职，后续改变缩进宽度时不需要改 XML 标签。

package main

import (
    "bytes"
    "encoding/xml"
    "fmt"
)

type Service struct {
    XMLName xml.Name `xml:"service"`
    Name    string   `xml:"name"`
    Port    int      `xml:"port"`
}

func main() {
    var out bytes.Buffer
    enc := xml.NewEncoder(&out)
    // prefix 为空，只用两个空格表示一层嵌套。
    enc.Indent("", "  ")

    value := Service{Name: "orders", Port: 8080}
    // Encode 会把值写入 out，并返回编码过程中的错误。
    if err := enc.Encode(value); err != nil {
        fmt.Printf("编码 XML 失败: %v\n", err)
        return
    }
    fmt.Print(out.String())
}

这段代码的关键不是把空格拼进字符串，而是让编码器知道“当前元素处于哪一层”。输出会类似下面这样：

orders8080

这里的输出示例只是排版结果示意。实际项目中仍然要根据调用方要求决定是否需要 XML 声明；Encoder 不会因为设置了缩进就自动添加 。

按文件或接口场景选择缩进宽度

如果目标是提交到版本库的配置文件，两个空格或四个空格都可以，重要的是整个项目保持一致。若需要兼容已有文件，可以先观察旧文件的缩进单位，再传给 Indent。例如用制表符也合法，但不同查看器对制表符宽度的显示可能不同。

排版参数不会改变元素名称、属性和值。如果接收方对空白敏感，尤其是把元素文本当作混合内容处理时，不能只看“更整齐”就直接上线；需要确认接收方是否把新增换行当作数据的一部分。

使用 EncodeToken 时记得 Flush

直接调用 Encode 时，官方文档说明它会在返回前刷新编码器。如果改用 EncodeToken 一枚枚写入开始标签、文本和结束标签，就要在完整的 token 序列结束后显式调用 Flush。否则，仍留在编码器缓冲区里的内容可能还没有写到目标 Writer。

package main

import (
    "bytes"
    "encoding/xml"
    "fmt"
)

func main() {
    var out bytes.Buffer
    enc := xml.NewEncoder(&out)
    // 让手工 token 也采用统一的层级排版。
    enc.Indent("", "  ")

    tokens := []xml.Token{
        xml.StartElement{Name: xml.Name{Local: "service"}},
        xml.StartElement{Name: xml.Name{Local: "status"}},
        xml.CharData("ready"),
        xml.EndElement{Name: xml.Name{Local: "status"}},
        xml.EndElement{Name: xml.Name{Local: "service"}},
    }
    for _, token := range tokens {
        // 每个 token 都可能返回结构不匹配等编码错误。
        if err := enc.EncodeToken(token); err != nil {
            fmt.Printf("写入 XML token 失败: %v\n", err)
            return
        }
    }
    // EncodeToken 不负责最后一次 Flush，这里显式提交缓冲内容。
    if err := enc.Flush(); err != nil {
        fmt.Printf("刷新 XML 编码器失败: %v\n", err)
        return
    }
    fmt.Print(out.String())
}

手工 token 还要额外保证开始标签和结束标签正确匹配。若 token 序列可能在多个分支中提前返回，可以把错误处理和 Flush 放在统一的出口，避免只写出半棵 XML 树。

和 MarshalIndent 怎么选

如果一次性把值编码成 []byte，xml.MarshalIndent 更直接；如果数据要持续写入文件、响应或其他 Writer，xml.NewEncoder 加 Indent 更合适。两者都能得到缩进后的 XML，但使用边界不同。

回滚路径也很简单：如果接收方不接受新增空白，先去掉 Indent 或切回 Marshal，确认数据契约后再决定是否用更窄的排版方式。不要为了让日志好看，牺牲协议对混合文本的语义要求。

上线前按这六项快速复查

1. 确认 Writer 没有被提前关闭，目标是文件、响应还是内存缓冲区要明确。
2. 确认 prefix 只是固定行首文本，真正的层级单位是 indent。
3. 确认 Encode 的错误被处理；不要因为只输出配置就忽略编码失败。
4. 使用 EncodeToken 时确认标签成对，并在最后调用 Flush。
5. 确认 XML 声明是否由协议要求，不能把缩进配置当成声明开关。
6. 对混合文本或空白敏感的接收方做契约确认，必要时回退到无缩进输出。

我自己的取舍是：配置文件默认使用 Indent("", " ")，流式接口保留错误处理和明确的写入边界；只有在接收方把空白当作内容时，才放弃漂亮排版。这样既能让排障更快，也不会把展示层的方便误当成数据层的规则。

相关问题

Encoder.Indent 会自动添加 XML 声明吗？

不会。它只控制元素换行和缩进，XML 声明需要由调用方按协议写入。

为什么 EncodeToken 后看不到完整输出？

EncodeToken 不负责最后一次刷新，完整 token 序列结束后应调用 enc.Flush()，同时检查标签配对和返回错误。

Indent 和 MarshalIndent 的区别是什么？

MarshalIndent 直接返回一段缩进后的字节切片；Encoder.Indent 是流式编码器的排版设置，适合配合 Writer 或手工 token 使用。