Go xml.Decoder.Token 怎么流式处理大型 XML

大型 XML 的关键变化，是不要先把整份文件读成 []byte 再调用 xml.Unmarshal，而是把文件作为 io.Reader 交给 xml.NewDecoder，用 Token() 逐个观察开始标签、文本和结束标签。定位到目标记录后，再用 DecodeElement 只解码当前元素，并立即交给回调处理。

流式读取降低的是“整份文档同时驻留内存”的压力。若回调仍把全部记录追加到切片，或者单个元素本身极大，内存仍会继续增长。

• 输入边界：直接读取 os.File、网络响应或其他 io.Reader。
• 记录边界：Token 找到目标 StartElement，DecodeElement 消费到对应结束标签。
• 内存边界：回调处理完当前记录就释放引用，不建立完整对象树。

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

Token 把文档拆成可处理的结构单元

Decoder.Token() 每次返回一个 XML 词法单元，常见类型包括 xml.StartElement、xml.EndElement、xml.CharData、xml.Comment、xml.ProcInst 和 xml.Directive。读到输入末尾时返回 nil, io.EOF；开始和结束标签不匹配时则返回解析错误。

这套接口的设计动机不是让业务代码手工拼出整棵树，而是让调用方在流上决定“哪些元素需要进入业务结构，哪些元素只需跳过”。对于包含几十万条同类记录的 XML，只保留当前记录通常比完整反序列化更合适。

用 StartElement 定位记录，再解码当前元素

假设大型文件由许多 元素组成。循环不需要保存其他 Token，只要遇到目标开始标签，就把该 StartElement 交给 DecodeElement。这个方法会消费当前元素的全部内容以及对应结束标签，因此下一次 Token() 会从该记录之后继续。

package main

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

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

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

    for {
        // 每轮只取一个 Token，不把整份 XML 读入内存。
        tok, err := dec.Token()
        if errors.Is(err, io.EOF) {
            return nil
        }
        if err != nil {
            // InputPos 返回最近 Token 结束位置，便于定位格式错误。
            line, column := dec.InputPos()
            return fmt.Errorf("XML %d:%d 解析失败：%w", line, column, err)
        }

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

        var product Product
        // DecodeElement 只构造当前 product，并消费到对应结束标签。
        if err := dec.DecodeElement(&product, &start); err != nil {
            line, column := dec.InputPos()
            return fmt.Errorf("product %d:%d 解码失败：%w", line, column, err)
        }
        // 回调立即写库、聚合或输出，避免累计全部 Product。
        if err := handle(product); err != nil {
            return fmt.Errorf("处理 product %q 失败：%w", product.ID, err)
        }
    }
}

func main() {
    file, err := os.Open("products.xml")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    count := 0
    err = streamProducts(file, func(product Product) error {
        // 示例只累计数量；实际项目可在这里批量写库或发送消息。
        count++
        fmt.Printf("%s\t%s\t%.2f\n", product.ID, product.Name, product.Price)
        return nil
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("共处理 %d 条记录\n", count)
}

判断标签时通常使用 start.Name.Local。如果文档依赖命名空间，还应同时检查 start.Name.Space；解析器会把已知命名空间前缀转换为规范的命名空间地址，不能只拿原始前缀作业务判断。

从整份反序列化迁移到逐条处理

旧写法常见于小文件：先用 os.ReadFile 得到完整字节，再把所有记录解码到一个切片。它简单，但输入字节、完整对象树和结果切片可能同时存活。迁移后的写法保留 os.File、xml.Decoder 和当前 Product，并把每条记录的生命周期交给 handle。

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

如果某些元素内部包含大量历史数据，而当前任务只需要主记录，可以在读到它的开始标签后调用 Decoder.Skip()。它会消费到最近一次开始标签对应的结束标签，嵌套层级由解析器负责匹配。

for {
    tok, err := dec.Token()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }

    start, ok := tok.(xml.StartElement)
    if !ok || start.Name.Local != "history" {
        continue
    }
    // history 不是当前任务所需字段，整棵子树交给 Skip 消费。
    if err := dec.Skip(); err != nil {
        return fmt.Errorf("跳过 history 失败：%w", err)
    }
}

Skip 必须在已经消费一个开始标签后调用。若业务稍后还要读取该子树的数据，就不能先 Skip 再回头解析，因为流式读取默认不会保留已经消费的内容。

四个容易踩坑的兼容边界

1. Token 的字节切片只在下一次读取前有效

CharData、Comment 等 Token 的底层字节可能引用解析器内部缓冲区，只保证在下一次 Token() 调用前有效。需要跨轮保存时使用 xml.CopyToken(tok)，或调用具体 Token 的 Copy 方法，不要直接把原切片存入长期缓存。

2. Token 和 RawToken 不是同一个契约

Token() 会检查开始、结束标签是否正确嵌套，并处理命名空间；RawToken() 不验证开始和结束元素是否匹配，也不转换命名空间前缀。处理外部输入时通常应优先使用 Token()，不要为了少做检查而换成 RawToken()。

3. 非 UTF-8 XML 要配置 CharsetReader

encoding/xml 默认假设输入是 UTF-8。若 XML 声明了其他字符集，需要设置 Decoder.CharsetReader，把声明的字符集转换为 UTF-8。不要仅把 Strict 设为 false 来掩盖编码错误；宽松模式会改变格式容忍边界，适合明确了解来源的兼容场景。

4. 单个元素也可能很大

流式扫描并不自动限制单个元素的体积。若 DecodeElement 对应结构中包含巨大的文本、innerxml 或无限增长的子切片，当前记录仍可能占用大量内存。此时应把记录继续拆成更细的 Token，或在输入层设置大小限制。

最小验证：确认正确、前进且不重新累积

迁移完成后，不需要先做复杂基准测试，先用下面五项检查确认行为契约：

1. 准备至少两个 product，确认回调按顺序收到两条完整记录。
2. 在记录之间加入无关元素，确认循环不会误解码。
3. 加入嵌套 history，确认 Skip 后下一条记录仍可读取。
4. 故意破坏结束标签，确认错误包含 InputPos 给出的行列位置。
5. 确认回调没有把全部 Product 追加到长期切片；需要批量写入时使用有上限的小批次。

若需要记录字节级进度，可在读取过程中使用 InputOffset()。它表示最近一个 Token 结束位置与下一个 Token 开始位置之间的输入偏移，适合日志和进度记录，但不能把它当成可随意回退解析器的游标。

常见问题

DecodeElement 之后还要手工找 EndElement 吗？

不需要。传入当前 StartElement 后，DecodeElement 会消费其内容和对应结束标签；外层循环继续调用 Token() 即可。

为什么用了 Decoder，内存还是不断上涨？

最常见原因是回调把所有记录追加到了切片，或者结构体字段保存了很大的子树。检查结果容器、缓存和批次上限，而不仅是解析入口。

可以同时解码多种记录吗？

可以。对 StartElement.Name.Local 做分支，每种标签使用各自结构体调用 DecodeElement；无法识别且确定不需要的子树可以 Skip。

这套迁移的核心不是把 Unmarshal 换成更多底层代码，而是把对象生命周期从“整份文档”缩短为“当前记录”。当输入顺序可处理、业务不需要随机访问完整树时，xml.Decoder.Token、DecodeElement 和 Skip 正好组成清晰的流式边界。