Go encoding/xml Token 流式读取大型 XML

读取大型 XML 时，不要先用 io.ReadAll 把文件装进 []byte，再对整份数据调用 xml.Unmarshal。更合适的做法是把文件或网络响应作为 io.Reader 交给 xml.Decoder，用 Token 扫描元素边界，只在遇到目标记录时调用 DecodeElement，处理完一条就释放一条。

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

为什么整份 Unmarshal 不适合大型 XML

整份解码通常同时持有原始字节、完整结构体和其中的切片或字符串。文件越大，内存峰值越容易受到整份文档大小影响。如果业务只需要逐条导入 ，构造完整根对象并没有必要。

xml.NewDecoder 直接从 io.Reader 读取。流式方案把工作集缩小为解析器缓冲、当前 token、当前记录以及业务处理函数自己的缓冲。它不会让内存变成绝对常量：如果单个元素本身非常大，或处理函数把所有记录继续累积到切片里，内存仍会增长。

用 Token 识别目标元素，再逐条 DecodeElement

下面的函数接收任意 io.Reader，因此既能读取文件，也能读取压缩流或 HTTP 响应体。循环只关心 StartElement；遇到 product 后，把这个开始元素交给 DecodeElement，它会消费完整元素并填充一条 Product。

package importxml

import (
    "encoding/xml"
    "errors"
    "fmt"
    "io"
)

type Product struct {
    ID    string `xml:"id,attr"`
    Name  string `xml:"name"`
    Price int64  `xml:"price"`
}

func StreamProducts(r io.Reader, handle func(Product) error) error {
    dec := xml.NewDecoder(r)

    for {
        tok, err := dec.Token()
        if errors.Is(err, io.EOF) {
            // io.EOF 表示所有 XML token 已正常读完。
            return nil
        }
        if err != nil {
            line, column := dec.InputPos()
            return fmt.Errorf("read XML at %d:%d: %w", line, column, err)
        }

        start, ok := tok.(xml.StartElement)
        if !ok || start.Name.Local != "product" {
            continue
        }

        var item Product
        // DecodeElement 从当前开始标签读到与之匹配的结束标签。
        if err := dec.DecodeElement(&item, &start); err != nil {
            line, column := dec.InputPos()
            return fmt.Errorf("decode product at %d:%d: %w", line, column, err)
        }

        // 立即交给调用方，避免在这里累积整个产品切片。
        if err := handle(item); err != nil {
            return fmt.Errorf("handle product %q: %w", item.ID, err)
        }
    }
}

调用方决定如何形成背压。若 handle 同步写数据库，解析器会等这条记录处理完成后再读下一条；若需要并发处理，可以把记录送入有界 channel，但应限制队列容量，避免把 XML 全部变成内存中的待处理对象。

Token 与 DecodeElement 的职责边界

Token 返回输入流中的下一个 XML token，并保证开始和结束元素正确嵌套。自闭合元素会被展开成连续的开始元素与结束元素。到达正常结尾时返回 io.EOF；缺少结束标签等结构错误则返回解析错误。

DecodeElement 适合“外层由自己扫描，目标元素交给标准映射规则”的混合方式。它接收已经读到的 StartElement，所以调用后不要再手动等待同一个元素的结束标签，否则会破坏外层循环的位置。

用 Skip 跳过确定不需要的嵌套子树

如果文件里有一个体积很大的 区域，且业务确认完全不需要其中内容，可以在读到它的开始标签后调用 Skip。该方法会一直消费到与最近开始元素匹配的结束元素，包括其中所有嵌套结构。

func skipArchives(dec *xml.Decoder, tok xml.Token) error {
    start, ok := tok.(xml.StartElement)
    if !ok || start.Name.Local != "archive" {
        return nil
    }

    // Skip 必须紧跟已经消费的开始元素调用，由它处理完整嵌套子树。
    if err := dec.Skip(); err != nil {
        line, column := dec.InputPos()
        return fmt.Errorf("skip archive at %d:%d: %w", line, column, err)
    }
    return nil
}

不要在不确定元素语义时随意 Skip。一旦跳过，内部所有潜在目标记录也会被消费。对于可能包含 product 的父节点，应继续让主循环逐个读取 token。

命名空间不能只看 Local

xml.Name 同时包含 Space 和 Local。Token 会把已知命名空间前缀解析为对应 URL，放在 Name.Space 中。若输入可能同时出现不同命名空间下的同名 product，只判断 Local 会误匹配。

const catalogNS = "https://example.com/catalog"

func isCatalogProduct(start xml.StartElement) bool {
    // 同时限定命名空间和本地名，避免匹配其他 schema 的同名元素。
    return start.Name.Space == catalogNS && start.Name.Local == "product"
}

如果业务输入保证没有命名空间，或所有同名元素语义完全一致，只比较 Local 可以更简洁。这个判断应来自输入格式契约，而不是碰巧能解析某个样例。

别长期保存 Token 内部字节切片

Token 返回的部分 token 数据会引用解析器内部缓冲，只保证在下一次调用 Token 之前有效。如果需要把 xml.CharData、注释或指令保存到循环外，应使用 xml.CopyToken 或具体 token 的 Copy 方法。

func copyCharData(tok xml.Token) ([]byte, bool) {
    data, ok := tok.(xml.CharData)
    if !ok {
        return nil, false
    }

    // Copy 创建独立字节切片，下一次 Token 调用不会覆盖它。
    copied := data.Copy()
    return []byte(copied), true
}

使用 DecodeElement 填入普通字符串或数值字段时，由解码器完成值映射，不需要为这些字段额外调用 CopyToken。这个限制主要影响直接保存原始 token 数据的代码。

错误定位和大文件边界

InputOffset 表示最近返回 token 末尾与下一个 token 开始之间的字节位置；InputPos 提供当前行和从 1 开始的列。它们适合写入错误信息或导入日志，但不能把“已读取字节数”直接当成“已成功导入记录数”。

采用建议

• 文件较小、需要完整对象树：直接 Decode 或 Unmarshal 更清楚。
• 文件很大、目标元素重复：使用 Token + DecodeElement 逐条处理。
• 只需统计或提取少量文本：可以完全基于 token 处理，但保存字节数据时记得复制。
• 存在明确无关的大型子树：在对应开始元素后使用 Skip。
• 业务处理可能慢：让同步处理形成背压，或使用容量可控的工作队列。

相关问题

Token 和 RawToken 有什么区别？

Token 会校验开始与结束元素是否匹配，并处理命名空间；RawToken 不做这两项工作。普通业务解析优先使用 Token。

流式读取一定不会占用大量内存吗？

不一定。解析器不保存整份文档，但单个巨大元素、业务侧缓存、无界 channel 或批量数据库缓冲仍可能推高内存。

可以在读取一半时停止吗？

可以。找到所需记录后直接返回即可；如果底层 Reader 需要关闭，例如文件或 HTTP 响应体，应由创建 Reader 的调用方负责关闭。

DecodeElement 会读到哪里？

它从传入的开始元素继续读取，并消费与之匹配的结束元素。返回后，外层循环可以从下一个 token 继续。