encoding/xml Decoder 如何读取未知标签的原始内容

在接入第三方 XML 时，经常会遇到这样的结构：主体字段是固定的，但节点中还夹着业务方自定义的未知标签。此时直接用结构体反序列化，往往只能拿到已声明的字段；如果还要把未知节点交给别的模块处理，就应该让 encoding/xml.Decoder 逐个返回 token。

这里的“原始内容”需要先说清楚：Go 标准库没有直接返回未知标签源文件字节区间的公开方法。Token 和 RawToken 返回的是结构化 token，因此下面的做法是把未知元素的起始标签、子节点和结束标签重新编码成 XML 字节。它能保留结构，不能承诺保留源文件中的空白、属性排列或实体写法。

最稳妥的方案是先用 Token 找到目标 StartElement，再用深度计数收集到对应的 EndElement。只有确实需要保留命名空间前缀写法，或明确接受不做起止标签匹配时，才切换到 RawToken。

先看清 Decoder 返回的是什么

encoding/xml 把 XML 拆成几类 token：StartElement、EndElement、CharData、注释、处理指令和指令节点。Token 每次读取一个 token；输入结束时返回 nil, io.EOF。它还会检查起始标签和结束标签是否正确嵌套，并按 XML 命名空间规则处理元素名称。

因此，不预先知道节点名称并不等于只能拿字符串扫描。你仍然可以用类型断言判断当前 token 是否是 xml.StartElement，再根据 start.Name.Local 做选择。未知标签只是业务结构未知，不是 XML 语法未知。

用 Token 定位未知标签

先写一个只负责定位的函数。它不把未知节点直接解码成结构体，而是返回命中的 StartElement，这样后面既可以收集整个子树，也可以调用 DecodeElement 把某个节点交给另一种结构体处理。

func findElement(dec *xml.Decoder, name string) (xml.StartElement, error) {
    for {
        tok, err := dec.Token()
        if err == io.EOF {
            // 输入结束仍没找到目标节点，返回带上下文的错误。
            return xml.StartElement{}, fmt.Errorf("未找到元素 %q", name)
        }
        if err != nil {
            // Token 会报告 XML 语法或读取错误，不能把它当成普通缺失节点。
            return xml.StartElement{}, err
        }

        start, ok := tok.(xml.StartElement)
        if ok && start.Name.Local == name {
            // 起始标签已经被消费，调用方从它的子节点继续读取。
            return start, nil
        }
    }
}

调用方要记住一个时机：返回 StartElement 后，解码器的位置已经在起始标签之后。收集函数应该先把这个起始标签写入输出，再继续读取它里面的 token，否则重建结果会只剩子节点和文本。

按深度收集一整棵未知子树

收集未知节点的关键不是寻找某个固定的结束标签，而是维护一个深度值：已经拿到起始标签时深度为 1；遇到嵌套的 StartElement 加 1；遇到 EndElement 减 1；回到 0 就说明目标元素完整结束。这个方法天然支持未知层级和未知子节点。

func collectElement(dec *xml.Decoder, start xml.StartElement) ([]byte, error) {
    var buf bytes.Buffer
    enc := xml.NewEncoder(&buf)

    if err := enc.EncodeToken(start); err != nil {
        return nil, fmt.Errorf("写入起始标签失败: %w", err)
    }

    depth := 1
    for depth > 0 {
        tok, err := dec.Token()
        if err == io.EOF {
            // XML 在子树结束前结束，说明输入不完整。
            return nil, errors.New("未知元素缺少结束标签")
        }
        if err != nil {
            return nil, fmt.Errorf("读取未知元素失败: %w", err)
        }

        switch tok.(type) {
        case xml.StartElement:
            depth++
        case xml.EndElement:
            depth--
        }

        if err := enc.EncodeToken(tok); err != nil {
            return nil, fmt.Errorf("重建 XML token 失败: %w", err)
        }
    }

    if err := enc.Flush(); err != nil {
        // Encoder 也可能在最后一次写出时报告底层 Writer 错误。
        return nil, fmt.Errorf("刷新重建内容失败: %w", err)
    }
    return buf.Bytes(), nil
}

完整的使用方式可以把定位和收集合并起来。示例只关注一个名为 extension 的未知节点，其他 XML 内容仍然由 token 循环正常跳过。

func readExtension(r io.Reader) ([]byte, error) {
    dec := xml.NewDecoder(r)
    start, err := findElement(dec, "extension")
    if err != nil {
        return nil, err
    }
    // start 已经从 Decoder 中读出，collectElement 会继续消费它的子树。
    return collectElement(dec, start)
}

这种结果是结构化重建后的 XML。例如源输入中的未知节点包含嵌套元素、字符数据和注释，编码器会按 token 重新写出它们。它适合传给后续 XML 解析器、保存为独立片段，或记录为待处理的扩展字段。

Token 和 RawToken 有什么区别

RawToken 的名字容易让人误解成“返回原始字节”。它实际仍然返回 Token，区别在于：不验证起始标签和结束标签是否匹配，也不把命名空间前缀翻译成对应的 URL。换句话说，它更接近输入中的名称写法，但依然不是源文件字节切片。

如果业务确实需要保留前缀写法，可以把定位函数和收集函数中的读取调用换成 RawToken。下面的差异只放在读取器选择上，其余深度逻辑相同：

func findRawElement(dec *xml.Decoder, name string) (xml.StartElement, error) {
    for {
        tok, err := dec.RawToken()
        if err == io.EOF {
            // RawToken 同样以 io.EOF 表示输入结束。
            return xml.StartElement{}, fmt.Errorf("未找到原始元素 %q", name)
        }
        if err != nil {
            return xml.StartElement{}, err
        }
        if start, ok := tok.(xml.StartElement); ok && start.Name.Local == name {
            // RawToken 不把命名空间短前缀翻译成 URL。
            return start, nil
        }
    }
}

选择建议可以压缩成三条：

• 只关心 XML 结构是否正确，并希望尽早发现标签错配时，使用 Token。
• 需要观察或重建输入里的命名空间前缀形式时，考虑 RawToken。
• 不需要节点内容，只想跳过未知子树时，直接使用 Decoder.Skip，不要自己维护深度。

三个容易让结果“看起来不对”的细节

第一，Token 里的字节数据不能跨下一次读取长期引用

官方文档说明，返回 token 中的字节切片可能指向解码器内部缓冲区，在下一次调用 Token 前才有效。如果需要把 CharData、注释或指令保存到切片中，应立即调用它们的 Copy 方法，或对整个 token 使用 xml.CopyToken。

tok, err := dec.Token()
if err != nil {
    return err
}
saved := xml.CopyToken(tok) // 复制内部缓冲，后续读取不会覆盖保存的数据。
_ = saved

第二，想要文本不等于想要整个未知节点

如果未知元素只有文本，DecodeElement 可以把它解码到字符串；但它不会把嵌套标签作为原始 XML 返回。如果要完整保留子树，就使用上面的 token 收集；如果只想跳过它，使用 Skip。

var text string
if err := dec.DecodeElement(&text, &start); err != nil {
    // DecodeElement 会消费 start 对应的完整元素，并把文本解码到 text。
    return err
}

第三，重建 XML 不等于逐字节还原

xml.Encoder 会根据 token 重新组织输出。缩进、属性排列、实体写法等源格式细节不应作为结果契约。如果业务要求保存原文件中从某个偏移到另一个偏移之间的字节，应该在更底层读取原始输入并自行记录偏移，而不是把 Token 当作字节切片接口。

如何按场景选择实现

结论

用 Go 读取未知 XML 标签时，核心是把“未知”拆成两个问题：标签名称未知，还是源字节必须一字不变。前者用 Token 找到 StartElement，再按深度把整棵子树编码出来；后者不能靠 Token 或 RawToken 直接解决，因为它们返回的都是结构化 token。

RawToken 适合处理命名空间前缀和不希望由 Decoder 做匹配校验的场景，但它不是更“原始”的通用版本。默认优先使用 Token，需要保存 token 数据时及时复制，只有在需求明确时才切换到 RawToken。

相关问题

encoding/xml 能不能直接返回未知标签的原始字符串？

公开 API 没有直接返回源字节区间的方法。可以用 token 重新编码得到结构等价的 XML；若必须保留所有源格式细节，需要在更底层保存输入字节和偏移。

什么时候用 Decoder.Skip？

当未知节点只需要被忽略、不需要保存内容时使用。它会继续读取到与最近一个起始元素匹配的结束元素，并处理嵌套结构。

RawToken 会不会自动修复错误 XML？

不要这样理解。它只是不验证起止元素是否匹配，不能把它当成修复器。对需要结构完整性的输入，继续使用 Token 并处理返回的错误。