Go jsontext Token Clone 怎样保留跨次读取的原始 token

在 Go 1.27 的 encoding/json/jsontext 中，Decoder.ReadToken 返回的原始 Token 可能仍然借用 Decoder 的内部缓冲区。如果 token 只在当前读取调用附近使用，可以直接处理；如果要放进切片、结构体、队列，或等下一次读取后再处理，就应该先调用 Token.Clone。Clone 会生成不再依赖后续 Decoder 调用的独立副本。

官方文档地址：https://pkg.go.dev/encoding/json/jsontext#Token.Clone

判断标准很简单：token 是否要跨过下一次 Decoder 调用继续存在？如果要，就在保存前 Clone；如果只在当前读取点立即消费，可以保留原始值。

先看清 jsontext Token 的两种存储形态

Token 表示 JSON 词法 token，可以是字符串、数字、字面量，也可以是对象或数组的边界。官方文档把它分成两种形态：一类是 ReadToken 从 Decoder 内部缓冲区得到的原始 JSON 文本；另一类是 jsontext.String、jsontext.Int 等构造器创建的 typed token。

两者在函数签名上都是 Token，但生命周期不同。原始 token 适合“读到就判断、读到就分派”；typed token 或 Clone 后的 token 才适合交给后续逻辑长期保存。这个差异正是迁移旧代码时最容易漏掉的地方。

哪些后续调用会影响原始 token

原始 token 的有效期不能简单理解成“函数返回后就永远有效”。官方文档明确提醒，后续对同一个 Decoder 的调用可能改变它依赖的内部缓冲区，包括 PeekKind、ReadToken、ReadValue 和 SkipValue。因此，把原始 token 保存起来，再继续读 Decoder，是需要重点检查的组合。

例如，下面的写法把“保存”和“继续读取”分开了。示例中的 Clone 是生命周期边界；注释说明了为什么复制，而不是把它当成每次读取都必须执行的固定模板。

package main

import (
    "fmt"
    "strings"

    "encoding/json/jsontext"
)

func main() {
    dec := jsontext.NewDecoder(strings.NewReader(`["alpha","beta"]`))

    // 读取到的原始 token 可能借用 Decoder 的内部缓冲区。
    first, err := dec.ReadToken()
    if err != nil {
        panic(err)
    }

    // 后面还要继续读取，所以先复制成独立 token 再保存。
    saved := first.Clone()

    // 继续读取会推进 Decoder，原始 first 不应再被当作长期值使用。
    second, err := dec.ReadToken()
    if err != nil {
        panic(err)
    }
    fmt.Println(saved, second)
}

迁移时把 Clone 放在哪里

最稳妥的位置是“从 Decoder 读出 token 后、交给长期生命周期对象前”。如果 token 只用于当前分支判断，可以直接读取 Kind 或调用对应访问器；如果要写入 AST、缓存切片、异步任务参数或错误上下文，就在赋值前 Clone。

不要把 Clone 机械地放在 Decoder 的所有读取点上。它会带来一次独立分配，立即消费的 token 没有必要复制。迁移旧代码时可以沿着数据流问三个问题：这个 token 会不会跨过下一次读取？会不会离开当前函数？接收方是否默认它拥有自己的字节内容？只要有一个答案是“会”或“是”，就应当复制。

回归检查清单

升级到 Go 1.27 或引入 jsontext 流式读取后，可以按下面的清单检查：

• 读取循环里是否把 ReadToken 的结果存入了长期切片或结构体？
• 保存 token 后，是否还会调用同一个 Decoder 的 PeekKind、ReadToken、ReadValue 或 SkipValue？
• 需要跨函数、跨 goroutine 或延后比较时，是否在交接前执行了 Clone？
• 如果只是当前分支立即判断，是否避免了不必要的复制？

这条迁移规则可以压缩成一句话：原始 Token 服务于当前 Decoder 读取上下文，Clone 后的 Token 才适合脱离这个上下文保存。把 Clone 放在所有权转移点，通常比在整个解析器里无差别复制更清晰。

相关问题

Token.Clone 会改变 token 的类型吗？不会。它解决的是原始数据的独立存储问题，不会把字符串 token 变成数字 token，也不会替你完成类型转换。

构造器创建的 Token 也必须 Clone 吗？通常不需要。官方文档说明 typed token 自带数据，不依赖 Decoder 的内部缓冲区；是否复制仍应由实际所有权和性能需求决定。