jsontext.Value 保存原始 JSON 片段的处理方式

要保存一段“暂时不解析、以后还要继续编码”的 JSON，Go 1.27 可以直接使用 encoding/json/jsontext.Value。它表示一个完整 JSON 值，可以是字符串、数字、对象或数组；但它本质上仍是命名的 []byte。因此，是否复制、是否校验、是否保持原字节排版，是三个必须分别处理的问题。官方 API 说明见 https://pkg.go.dev/encoding/json/jsontext，Go 1.27 的标准库变化见 https://go.dev/doc/go1.27。

现象：保存后的 JSON 为什么会“自己变化”

问题通常发生在复用读取缓冲区、对象池或临时字节切片时。下面的 keepWrong 看似把 JSON 放进了 Value，实际上只创建了一个新的切片头；调用方随后改写 src，已保存的值也会看到相同的底层字节。

package main

import "encoding/json/jsontext"

func keepWrong(src []byte) jsontext.Value {
    // 类型转换不会复制底层数组，返回值仍与 src 共享存储。
    return jsontext.Value(src)
}

func keepOwned(src []byte) jsontext.Value {
    // Clone 创建独立副本，之后复用 src 不会改写已保存内容。
    return jsontext.Value(src).Clone()
}

这个现象和 JSON 是否有效无关。即使输入完全合法，只要两个切片共享底层数组，所有权就没有分开。反过来，克隆一段无效字节也不会使它变成合法 JSON，所以“复制”和“校验”不能合并成一个概念。

调查：Clone 与 IsValid 各自解决什么

保存来自网络、插件或消息队列的原始片段时，可以先把输入视为 Value，调用 IsValid 检查它是否为一个完整 JSON 值，再用 Clone 固化字节。默认校验会拒绝无效 UTF-8 和重复对象名，适合把不可信数据挡在存储边界外。

package rawjson

import (
    "errors"

    "encoding/json/jsontext"
)

func SaveFragment(src []byte) (jsontext.Value, error) {
    // Value 只是对输入字节的轻量视图，此处尚未复制。
    value := jsontext.Value(src)
    // IsValid 检查语法，避免把损坏片段留到编码阶段才发现。
    if !value.IsValid() {
        return nil, errors.New("原始 JSON 片段无效")
    }
    // 校验通过后再复制，明确由返回值持有自己的字节。
    return value.Clone(), nil
}

Value.UnmarshalJSON 会保存输入副本，但官方文档明确说明它不执行验证；Value.MarshalJSON 也会直接返回原始值而不验证。它们适合由上层 JSON 编解码器管理的路径，不应被误解为独立的“校验并保存”函数。

修复：把原始片段放进业务结构

当消息外壳有稳定字段、载荷结构由下游决定时，可以直接把 jsontext.Value 作为结构体字段。这样不必先转成 map[string]any，也不会把 JSON 数字提前变成某个不合适的 Go 数值类型。

package main

import (
    "fmt"

    "encoding/json/jsontext"
    jsonv2 "encoding/json/v2"
)

type Envelope struct {
    // ID 是当前服务理解的稳定字段。
    ID string `json:"id"`
    // Payload 保存一个完整但暂不解释的 JSON 值。
    Payload jsontext.Value `json:"payload"`
}

func forward(input []byte) ([]byte, error) {
    var env Envelope
    // v2 解码器负责读取外壳，并把 payload 交给 Value。
    if err := jsonv2.Unmarshal(input, &env); err != nil {
        return nil, fmt.Errorf("解析消息外壳失败: %w", err)
    }
    // 业务只改稳定字段，不必先理解 Payload 的内部结构。
    env.ID = "forwarded-" + env.ID
    // 再次编码时，Payload 仍作为一个 JSON 值写回对象。
    return jsonv2.Marshal(env)
}

这里“原始”表示保留 JSON 值的字节表示供后续处理，不代表外层重新编码后整条消息会逐字节相同。外层成员顺序、空白和转义形式可能由编码器重新组织。若签名或审计协议要求字节级一致，应把签名对象定义为独立的原始字节，不要把重新编码后的整个外壳当作同一份报文。

验证：用 WriteValue 写入 JSON 流

如果目标不是结构体，而是流式输出一个 JSON 值，使用 jsontext.Encoder.WriteValue 更直接。与 Value.MarshalJSON 不同，WriteValue 会解析输入以检查语法，并按照编码器选项重新格式化；遇到无效值时返回 SyntacticError，编码器状态保持不变。

package main

import (
    "bytes"
    "fmt"

    "encoding/json/jsontext"
)

func encodeOne(value jsontext.Value) ([]byte, error) {
    var dst bytes.Buffer
    // Encoder 管理输出流，WriteValue 会验证传入值的 JSON 语法。
    enc := jsontext.NewEncoder(&dst)
    if err := enc.WriteValue(value); err != nil {
        return nil, fmt.Errorf("写入原始 JSON 失败: %w", err)
    }
    // 返回的是编码器输出，不应假设与输入空白完全一致。
    return dst.Bytes(), nil
}

这条路径适合拼装 NDJSON、协议帧或自定义输出管道。不要用字符串拼接把 Value 塞进对象文本；字符串拼接无法正确处理逗号、上下文和错误状态，也会把验证责任变得模糊。

再次编码前，先决定是否改变字节表示

Value 提供多种原地变换。Compact 删除不必要空白，Indent 调整缩进，Format 在验证后按选项格式化，Canonicalize 则生成适合稳定比较的规范形式。因为这些方法会修改接收者，若还要保留最初片段，应先复制。

package main

import "encoding/json/jsontext"

func compactForStorage(original jsontext.Value) (jsontext.Value, error) {
    // 先克隆，避免压缩操作覆盖仍需用于审计的原始字节。
    compacted := original.Clone()
    // Compact 只改变副本，成功后可用于节省存储空间。
    if err := compacted.Compact(); err != nil {
        return nil, err
    }
    return compacted, nil
}

Canonicalize 不是“无损美化”。它会统一对象成员、字符串和数字表示；对于超出 IEEE 754 精确范围的数字，还要评估精度策略。缓存键、签名材料和审计存档应先明确需要的是语义稳定还是字节保真，再决定是否规范化。

方法对照表

常见问题

nil 的 jsontext.Value 会编码成什么？

MarshalJSON 会把 nil Value 编码为 JSON 的 null。如果业务必须区分“缺少字段”和“字段值为 null”，还要结合结构体字段、指针或省略规则设计协议。

为什么不直接保存 string？

字符串可以保存字节，但不会表达“这里必须是一个完整 JSON 值”的意图，也不能直接使用 IsValid、Compact 和 WriteValue 等 API。需要字节级归档时仍可保存 []byte，但进入 JSON 处理边界后，Value 的类型语义更清楚。

保存后还能按需解析吗？

可以。先用 Kind 判断值的大类，再交给 encoding/json/v2 解码为具体结构。不要为了未来可能使用，就在入口处立即把所有片段转成通用 map。

处理 jsontext.Value 时，最稳妥的顺序是：先确认输入是否可信，再决定是否校验，随后取得所需的字节所有权，最后选择结构体编码、流式写入或格式变换。只要把“复制、验证、格式化”三个责任分开，原始 JSON 片段就不会在缓冲区复用、错误延迟或重编码过程中变成难以追踪的问题。