Go encoding/xml 怎样让 XML 解码保留未知元素

如果 XML 来自多个供应商，结构体通常只认识自己关心的字段。Go 的 encoding/xml.Unmarshal 会把能匹配的元素写入导出字段，无法映射到目标值的良构元素则直接丢弃。想保留未知元素，做法不是给结构体加一个神奇的通配字段，而是让父对象实现 UnmarshalXML，在读取 token 时把未知节点交给一个可重新编码的容器。

官方文档：https://pkg.go.dev/encoding/xml@go1.27.3

下面的实现保留未知元素的名称、属性和嵌套 token，适合协议扩展、配置透传和“读取后再写回”的场景。它保留的是 XML 结构语义，不承诺保留原文件的空格、前缀和字节布局。

默认 Unmarshal 为什么会丢掉未知元素

encoding/xml 的结构体映射是“XML 名称匹配字段或标签”。例如目标类型只声明了 name 和 version，输入里的 vendor:trace 没有对应字段，解码仍然可以成功，但这个节点不会出现在结果里。

package main

import (
    "encoding/xml"
    "fmt"
)

type BasicDocument struct {
    XMLName xml.Name `xml:"document"`
    Name    string   `xml:"name"`
    Version string   `xml:"version"`
}

func main() {
    input := []byte(`demoalpha2`)
    var doc BasicDocument
    if err := xml.Unmarshal(input, &doc); err != nil {
        // 输入不是合法 XML 时，先返回解析错误，不把缺失字段当成未知节点。
        panic(err)
    }
    fmt.Printf("name=%s version=%s\n", doc.Name, doc.Version)
    // 输出只包含已声明字段；vendor:trace 不会自动进入 BasicDocument。
}

这里的“未知”不是语法错误，而是“合法 XML 与目标结构不匹配”。因此只靠检查 Unmarshal 的错误返回值，无法判断扩展节点是否被丢弃。innerxml 也不是通配符：它只收集已经匹配到的那个元素内部内容，不能把同级未知元素自动装进切片。

先定义能保存 XML 结构的未知节点

未知节点至少需要三类信息：元素名、属性、子内容。xml.Name 保存本地名和命名空间，属性复制到独立切片，嵌套内容用 []xml.Token 保存。每次从 Decoder 取出 token 后立即调用 xml.CopyToken，避免继续读取时底层数据被复用。

type UnknownElement struct {
    XMLName xml.Name
    Attr    []xml.Attr
    Tokens  []xml.Token
}

func (u *UnknownElement) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
    // 先复制根元素的身份和属性，后面只保存它的内部 token。
    *u = UnknownElement{
        XMLName: start.Name,
        Attr:    append([]xml.Attr(nil), start.Attr...),
    }

    depth := 1
    for depth > 0 {
        tok, err := d.Token()
        if err != nil {
            // 子树不完整时把原始解析错误交给上层处理。
            return err
        }
        switch tok.(type) {
        case xml.StartElement:
            depth++
        case xml.EndElement:
            depth--
            if depth == 0 {
                // 当前节点的结束标签由 MarshalXML 重新补上。
                break
            }
        }
        if depth > 0 {
            // Token 的底层数据可能随下一次读取变化，必须保存副本。
            u.Tokens = append(u.Tokens, xml.CopyToken(tok))
        }
    }
    return nil
}

这个方法由 DecodeElement 触发时，传入的 start 已经是未知元素的开始标签。循环从深度 1 开始，遇到嵌套开始标签就加一，遇到结束标签就减一；外层结束标签不放入 Tokens，因为它会在重新编码时由 StartElement.End 生成。

在父对象中分流已知字段和未知节点

父类型的自定义解码器负责决定哪些名字走普通字段，哪些名字进入 UnknownElement。示例中 name 与 version 仍使用 DecodeElement，其它元素统一收集到 Extra。

type Document struct {
    XMLName xml.Name
    Name    string
    Version string
    Extra   []UnknownElement
}

func (d *Document) UnmarshalXML(dec *xml.Decoder, start xml.StartElement) error {
    d.XMLName = start.Name
    for {
        tok, err := dec.Token()
        if err != nil {
            // XML 提前结束或结构损坏时，不返回一个半成品文档。
            return err
        }
        switch t := tok.(type) {
        case xml.StartElement:
            switch t.Name.Local {
            case "name":
                if err := dec.DecodeElement(&d.Name, &t); err != nil {
                    return err
                }
            case "version":
                if err := dec.DecodeElement(&d.Version, &t); err != nil {
                    return err
                }
            default:
                var extra UnknownElement
                if err := dec.DecodeElement(&extra, &t); err != nil {
                    return err
                }
                d.Extra = append(d.Extra, extra)
            }
        case xml.EndElement:
            if t.Name == start.Name {
                // 父元素闭合，未知元素已经全部收集完毕。
                return nil
            }
        }
    }
}

注意这里比较了完整的 xml.Name，而不是只比较 Local。如果协议允许不同命名空间里出现同名元素，可以在分流条件中同时判断 t.Name.Space；否则可能把不同供应商的扩展混在一起。

重新编码时保留名称、属性和嵌套内容

只实现解码还不够。若文档会被修改后再次写出，UnknownElement 还应实现 MarshalXML。先创建带名称和属性的 StartElement，再逐个写回内部 token，最后写入结束标签。

func (u UnknownElement) MarshalXML(e *xml.Encoder, _ xml.StartElement) error {
    start := xml.StartElement{
        Name: u.XMLName,
        Attr: append([]xml.Attr(nil), u.Attr...),
    }
    if err := e.EncodeToken(start); err != nil {
        // 开始标签写入失败时立即返回，避免产生半个扩展节点。
        return err
    }
    for _, tok := range u.Tokens {
        if err := e.EncodeToken(tok); err != nil {
            // 任一嵌套 token 失败都不能继续补结束标签。
            return err
        }
    }
    // End 会根据开始标签生成匹配的结束元素。
    return e.EncodeToken(start.End())
}

调用层可以直接对 Document 使用 xml.NewEncoder，未知节点会作为扩展对象参与输出。重新编码后，命名空间前缀、缩进空格或属性排列可能与输入不同，这是 XML 语义等价的正常结果；如果业务要求逐字节保留原文，就不应只依赖 token，而应另外保存原始字节片段。

什么时候应该换一种保留策略

最后的判断标准很简单：只要未知节点需要参与后续业务，先把它变成有边界的对象；如果只是向前兼容而无需写回，接受默认丢弃通常更简单。不要为了“以后可能用到”把整个 XML 文档无差别存进内存。

相关问题

为什么检查 Unmarshal 的 error 不能发现未知字段？

因为未知元素属于“合法但没有目标字段”的情况，不是语法错误。Unmarshal 仍可能返回 nil，调用方要主动设计收集逻辑。

innerxml 能不能直接收集所有未知元素？

不能。它绑定到当前匹配的元素，只保存该元素内部的原始 XML；同级未知元素仍需要父对象自定义解码。

为什么示例一定要调用 xml.CopyToken？

因为 token 可能引用解码器后续会复用的底层数据。要把 token 放进结构体并延迟到编码阶段使用，就应在读取时复制。