Go x/net/html.Tokenizer 为什么不能保留所有原始标签格式

如果你把一段 HTML 交给 html.NewTokenizer，再用 z.Token() 拼回标签，得到的结果通常只能算“语义上相近”，不能当作原始 HTML 的逐字副本。原因是 Token() 面向结构化处理：实体会被反转义，标签名和属性名会被规范化，原始引号、空白和写法差异也没有被设计成必须保留的字段。

官方地址：https://pkg.go.dev/golang.org/x/net/html#Tokenizer

需要保留原始字节时，在每次 Next() 之后立即复制 Raw()，不要先调用 Token()、Text()、TagName() 或 TagAttr()。需要理解标签含义时再使用结构化 API。

先分清“原始文本”和“结构化 token”

x/net/html 的定位是 HTML5 tokenizer/parser。Tokenizer 按输入生成 token，调用顺序的核心是 Next {Raw} [Token | Text | TagName {TagAttr}]。同一个 token 可以先取 Raw，也可以再读取结构化字段，但这两条路径的目标不同。

为什么 Token 重建不可能保证原始格式

假设输入包含大写标签、混合引号、属性之间的多余空白，以及用实体表示的字符。Tokenizer 的任务是识别 token，而不是记录一份格式化源文件的 AST。文档明确说明，Token 中的 Data 已经是反转义后的数据，标签名和属性键也会采用规范化形式。

因此，下面几类信息不能从 Token 结构可靠地推回原文：

• 标签原来是大写、小写还是混合大小写；
• 字符原来写成实体还是直接写成字符；
• 属性值使用单引号、双引号还是其他可被解析的形式；
• 标签名、属性和属性值之间原本有多少空白。

属性的语义值仍然可以正确读取，但“语义相同”不等于“字节相同”。如果后续代码要做签名、缓存键、补丁定位或审计对照，就不应把 Token.String() 或自己拼出来的标签当成原始输入。

最小实验：同时观察 Raw 和 Token

先用一段故意包含格式差异的输入。这个示例只读取当前 token，不把输出当成线上页面截图；重点是理解两个 API 读取的是两种不同表示。

package main

import (
    "fmt"
    "strings"

    "golang.org/x/net/html"
)

func main() {
    // 保留大小写、单双引号、空白和实体写法的差异。
    source := `
`
    z := html.NewTokenizer(strings.NewReader(source))

    for {
        tt := z.Next()
        if tt == html.ErrorToken {
            // io.EOF 表示 token 已正常读完，其他错误才需要排查。
            fmt.Println("结束：", z.Err())
            return
        }

        raw := append([]byte(nil), z.Raw()...)
        tok := z.Token()
        // Raw 是当前 token 的原字节，Token 是面向语义处理的结构。
        fmt.Printf("raw=%q type=%v data=%q attrs=%v\n", raw, tok.Type, tok.Data, tok.Attr)
    }
}

这个实验中，raw 仍然保留当前 token 的输入写法；tok 则按 Token 的契约提供结构化数据。使用 append([]byte(nil), ...) 是有意的：它创建了独立副本，避免后续 tokenizer 操作复用返回切片。

要保留原始 HTML，Raw 必须先复制

官方文档给出的关键约束是：Raw() 返回当前 token 的未修改文本，但调用下一次 Next()，或调用 Token、Text、TagName、TagAttr，都可能改变这块返回切片的内容。保留原文时，最小可靠模式就是“Next、复制 Raw、再做可选的语义读取”。

package main

import (
    "errors"
    "fmt"
    "io"
    "strings"

    "golang.org/x/net/html"
)

func preserveRaw(source string) ([]byte, error) {
    z := html.NewTokenizer(strings.NewReader(source))
    var kept []byte

    for {
        tt := z.Next()
        if tt == html.ErrorToken {
            // ErrorToken 后读取 Err，EOF 是正常结束信号。
            if err := z.Err(); err != nil && !errors.Is(err, io.EOF) {
                return nil, err
            }
            return kept, nil
        }

        // 必须在任何规范化字段读取前复制当前 token 的原始字节。
        kept = append(kept, z.Raw()...)
    }
}

func main() {
    source := `
`
    kept, err := preserveRaw(source)
    if err != nil {
        panic(err)
    }
    // kept 是复制后的字节，可安全交给下一步处理或写入文件。
    fmt.Println(string(kept))
}

按照文档，token 的 raw bytes 在遇到 ErrorToken 之前会分割输入字节流，不会在相邻 token 之间产生重叠或空洞。因此，逐个复制 Raw() 可以构成一条原始字节保留路径；但如果输入在错误 token 处结束，代码仍应按 Err() 的结果决定是接受部分数据还是返回错误。

Raw 与低级 API 的调用顺序

如果既要做语义判断，又要保留原文，先复制 Raw，再读取低级字段。低级 API 适合减少分配，例如只判断当前标签是不是 a；但它们返回的字节切片可能在下一次 Next() 后变化，所以需要跨轮保存时也要复制。

for {
    tt := z.Next()
    if tt == html.ErrorToken {
        return z.Err()
    }

    // 先复制原始 token，保证后续语义读取不会影响保留结果。
    raw := append([]byte(nil), z.Raw()...)

    if tt == html.StartTagToken {
        // 这里的名称已经是规范化字段，适合做判断，不代表原始拼写。
        name, hasAttr := z.TagName()
        fmt.Printf("raw=%q tag=%q hasAttr=%v\n", raw, name, hasAttr)
    }
}

按需求选择 Tokenizer、Parser 或字节保留

只做文本级替换时，可以保存每个 token 的 Raw，再在明确的字节范围内做替换。需要判断标签、属性或文本内容时，用 Token 或低级 API 更直接。需要完整 DOM、父子关系和结构化修改时，应使用包提供的 parser，而不是把 tokenizer 当作 DOM。

尤其要避免一个常见误区：先用 Token() 做安全或规则判断，再直接信任原输入的字节形态。官方文档提醒，tokenization 或 parsing 可能改变内容；如果信任决策依赖重新序列化后的结果，应使用明确的序列化步骤，例如 Render 或 Token.String()，并把它视为新的表示，而不是原始输入。

最后检查这四个边界

1. 要逐字保留：每次 Next() 后立即复制 Raw()。
2. 要读语义：使用 Token、Text、TagName 或 TagAttr，接受规范化结果。
3. 要跨轮保存低级字段：复制返回的 []byte，不要保存原切片。
4. 要构造 DOM：使用 parser；要原始字节：不要依赖 Token 重建。

一句话总结：Raw() 解决的是当前 token 的字节保留，Token() 解决的是结构化理解。把两者按正确顺序组合，才能同时兼顾原文对照和标签语义处理。

相关问题

• Raw() 能不能在下一次 Next() 后继续使用？不能依赖，应该先复制。
• Token() 为什么把实体变成字符？它返回的是反转义后的结构化数据，不是源代码片段。
• 为什么标签名和属性键变成小写？这是 Tokenizer 面向 HTML 语义处理的规范化行为。
• 需要完整 HTML 结构时该用什么？使用同包的 parser，让它构建 DOM 节点树。