Go jsontext.Encoder.WriteToken 增量生成 JSON 的实现方式

需要按字段、数组和嵌套对象逐段生成 JSON 时，jsontext.Encoder.WriteToken 比一次性拼接字符串更容易守住语法边界。它每次写入一个 JSON token，并根据当前上下文判断下一个 token 是否合理；对象字段名必须是字符串，数组结束符也不能出现在对象状态里。只要按 JSON 语法顺序调用，bytes.Buffer 就能接住最终文本；调用顺序错误则应优先处理返回的 error，而不是继续写后续内容。

确认 token、对象边界和字段顺序

jsontext 处理的是 JSON 的语法层。对象和数组的分隔符不需要手动写逗号或冒号，编码器会根据 token 上下文补出这些结构；但字段名和值的角色必须正确。可以先把几个关键实体对照起来：

下面的示例只构造一个对象，字段 tags 的值是字符串数组。代码中的中文注释解释了关键顺序；这段示例不依赖本地运行结果，读者可以把它放进自己的 Go 项目验证。

package main

import (
    "bytes"
    "fmt"

    "encoding/json/jsontext"
)

func main() {
    var buf bytes.Buffer
    enc := jsontext.NewEncoder(&buf)

    // 对象必须从 BeginObject 开始，字段名和值成对出现。
    tokens := []jsontext.Token{
        jsontext.BeginObject,
        jsontext.String("name"),
        jsontext.String("gopher"),
        jsontext.String("tags"),
        jsontext.BeginArray,
        jsontext.String("go"),
        jsontext.String("json"),
        jsontext.EndArray,
        jsontext.EndObject,
    }
    for _, tok := range tokens {
        // 任何 token 违反当前 JSON 语法都必须立即返回错误。
        if err := enc.WriteToken(tok); err != nil {
            panic(err)
        }
    }
    fmt.Println(buf.String())
}

用 Encoder.WriteToken 增量构造对象与数组

上例的关键不是 token 数量，而是每个 token 在对象或数组里的角色。写入 String("name") 后，编码器期待一个值；写入 BeginArray 后，后面可以放多个字符串、数字或嵌套对象，直到 EndArray 把数组闭合。WriteToken 会替我们处理 JSON 文本中的标点和必要换行，因此不应再用字符串拼接插入逗号。

如果对象里增加数字字段，可以直接使用 jsontext.Int；如果值来自已经编码好的片段，也可以把它作为 jsontext.Value 交给 WriteValue。两者都要服从当前上下文：对象字段名仍然必须先写入字符串 token。

// 写入一个数值字段；字段名和值仍然是两个相邻 token。
if err := enc.WriteToken(jsontext.String("count")); err != nil {
    return err
}
if err := enc.WriteToken(jsontext.Int(3)); err != nil {
    return err
}

// WriteValue 适合已经确定为合法 JSON 的局部值，不能绕过外层语法状态。
if err := enc.WriteValue(jsontext.Value(`{"enabled":true}`)); err != nil {
    return err
}

处理语法错误并保持状态可恢复

调用顺序错时，WriteToken 会返回错误。例如刚开始写对象就传入 jsontext.Int(1)，编码器期待的是字段名字符串；在数组已经结束后再写 EndArray，也会破坏当前语法。官方文档将这类问题归为 SyntacticError，其中的偏移量可帮助定位输出中的错误位置。

func writeInvalidToken(enc *jsontext.Encoder) error {
    if err := enc.WriteToken(jsontext.BeginObject); err != nil {
        return err
    }

    // 对象打开后必须先写字段名，不能直接写整数值。
    if err := enc.WriteToken(jsontext.Int(1)); err != nil {
        return fmt.Errorf("写入对象字段值失败: %w", err)
    }
    return nil
}

实践上建议每次调用都检查错误，并在错误处停止当前对象的生成。不要吞掉错误后继续写，因为后续 token 依赖编码器当前状态，继续追加只会让最终定位更困难。需要保留错误信息时，用 errors.As 识别具体语法错误，再记录字段上下文。

WriteToken 与 WriteValue 的选择清单

可以用下面的判断缩小 API 选择范围：

因此，WriteToken 的核心价值是让“动态结构”仍然有可检查的 JSON 语法边界。它并不负责业务字段命名、校验规则或对象模型映射；这些职责应留在调用方或 encoding/json/v2 的语义层。

相关问题

WriteToken 会不会要求手动写逗号和冒号？

不需要。编码器根据字段名、值和数组边界推导这些分隔符，但调用者必须提供正确的 token 顺序。

WriteToken 出错后还能继续写吗？

不建议继续。先保存错误并停止当前生成；如果能修正调用顺序，应从明确的编码器状态重新开始。

什么时候直接使用 WriteValue？

当你已经拥有一段需要作为完整 JSON 值写入的原始内容，并且它能放在当前字段或数组位置时，WriteValue 更合适。