encoding/json/v2 用 StringifyNumbers 兼容旧数字字段

旧客户端如果把订单号、金额分值或时间戳约定成 JSON 字符串，Go 1.27 的 encoding/json/v2 可以用 StringifyNumbers(true) 保持这种线格式：原本会编码为 JSON number 的数值，改为编码成包含等价数字的 JSON string。它也能在解码时按相同规则从字符串数字解析回 Go 数值。

真正需要先决定的是作用范围。调用级 StringifyNumbers(true) 会递归影响这次编解码中的数值；结构体字段上的 ,string 只作用于该字段对应的顶层值，不会继续深入字段内部的对象或数组。旧协议只要求少数字段为字符串时，字段标签通常更稳；整个旧端点都使用字符串数字时，再考虑调用级选项。

官方资料：https://pkg.go.dev/encoding/json/v2

Go 1.27 发布说明：https://go.dev/blog/go1.27

先用兼容矩阵决定编码和解码边界

我遇到这类迁移时，第一反应通常不是改代码，而是把线上线格式列成矩阵。因为“旧客户端需要字符串数字”可能只指响应编码，也可能意味着请求体同样只会发送字符串。StringifyNumbers 同时可用于 Marshal 和 Unmarshal，但启用解码选项后，目标数值要从 JSON 字符串读取；它不是“数字和字符串都宽松接受”的双格式开关。

矩阵的基线数据应来自契约测试、网关日志或客户端版本分布，不能把“接口返回 200”当成兼容成功。尤其是 JavaScript 客户端，大于 2^53-1 的整数可能超出二进制浮点数安全整数范围；把标识符编码为字符串可以保持十进制文本精度，但这并不意味着所有业务数值都应该字符串化。

全局字符串化适合完整的旧协议端点

如果一个旧版响应明确规定所有数字都必须是字符串，可以把选项放在一次 Marshal 调用上。这个选项会递归作用，所以嵌套切片里的价格也会被字符串化。

package main

import (
    jsonv2 "encoding/json/v2"
    "fmt"
)

type Item struct {
    SKU   string `json:"sku"`
    Price int64  `json:"price"`
}

type Order struct {
    OrderID int64  `json:"order_id"`
    Count   int    `json:"count"`
    Items   []Item `json:"items"`
}

func main() {
    order := Order{
        OrderID: 9007199254740993,
        Count:   2,
        Items:   []Item{{SKU: "A-01", Price: 19900}},
    }

    // 调用级选项会递归处理本次编码中的数字字段。
    data, err := jsonv2.Marshal(order, jsonv2.StringifyNumbers(true))
    if err != nil {
        // 编码失败必须中止，不能向客户端返回半截 JSON。
        panic(err)
    }

    // 示例只展示线格式；生产服务应写入响应体而不是打印。
    fmt.Println(string(data))
}

对应的线格式中，order_id、count 和嵌套的 price 都是 JSON 字符串：

{"order_id":"9007199254740993","count":"2","items":[{"sku":"A-01","price":"19900"}]}

这就是调用级配置的代价：改动很集中，但影响面也大。只要旧客户端对某个普通计数字段仍期待 JSON number，全局字符串化就会制造新的兼容问题。不要因为一个大整数标识符需要字符串，就顺手改变整个响应树。

字段级 string 标签更适合小范围兼容

旧协议只要求订单号是字符串，而数量和价格仍保持标准 JSON number 时，应把规则写进 DTO 字段。json:"order_id,string" 会把 StringifyNumbers 语义应用到该字段的顶层值，不递归影响其他字段。

package main

import (
    jsonv2 "encoding/json/v2"
    "fmt"
)

type Item struct {
    SKU   string `json:"sku"`
    Price int64  `json:"price"`
}

type LegacyOrder struct {
    // 仅订单号保持旧协议的字符串数字形状。
    OrderID int64  `json:"order_id,string"`
    Count   int    `json:"count"`
    Items   []Item `json:"items"`
}

func main() {
    order := LegacyOrder{
        OrderID: 9007199254740993,
        Count:   2,
        Items:   []Item{{SKU: "A-01", Price: 19900}},
    }

    // 不传全局选项，避免递归改变 Count 和 Price 的线格式。
    data, err := jsonv2.Marshal(order)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(data))
}

这次输出只改变订单号：

{"order_id":"9007199254740993","count":2,"items":[{"sku":"A-01","price":19900}]}

字段标签还有一个工程优势：协议约束靠近字段定义，代码审查时能直接看见。但不要把兼容标签加到核心领域模型的每一层。更稳妥的方式是单独维护 LegacyOrderResponse，由映射函数把领域对象转换为旧协议 DTO，这样未来移除兼容层时不会牵动内部模型。

解码时不要把 StringifyNumbers 当成双格式兼容

在 Unmarshal 中传入 StringifyNumbers(true)，表示数值从 JSON 字符串中的数字文本解析，并且字符串内部不能带额外空白。它适合请求协议已经明确为字符串数字的端点。

package main

import (
    jsonv2 "encoding/json/v2"
    "fmt"
)

type LegacyRequest struct {
    OrderID int64 `json:"order_id"`
    Count   int   `json:"count"`
}

func main() {
    input := []byte(`{"order_id":"9007199254740993","count":"2"}`)
    var req LegacyRequest

    // 解码选项要求数字来自 JSON 字符串，并递归应用到数值字段。
    if err := jsonv2.Unmarshal(input, &req, jsonv2.StringifyNumbers(true)); err != nil {
        panic(err)
    }

    // 成功后得到正常 Go 数值，业务层不必处理字符串转换。
    fmt.Printf("%d %d\n", req.OrderID, req.Count)
}

若迁移窗口要求同时接受 2 和 "2"，单纯打开或关闭这个选项都不能表达完整契约。此时应选择更明确的方案：保留旧端点并新增标准数字端点、按版本头路由到不同 DTO，或者为少数字段实现经过测试的自定义类型。不要给所有请求做“先失败再换选项重试”，那会让错误定位、性能成本和安全边界都变得模糊。

用大整数与嵌套结构写契约测试

兼容测试至少覆盖三个维度：超过 JavaScript 安全整数范围的 int64、嵌套集合中的数字、以及编码和解码方向。下面的表驱动测试不依赖人工查看输出，而是把旧协议需要的字节形状固定下来。

package contract_test

import (
    jsonv2 "encoding/json/v2"
    "testing"
)

type Item struct {
    Price int64 `json:"price"`
}

type Order struct {
    OrderID int64  `json:"order_id"`
    Items   []Item `json:"items"`
}

func TestLegacyNumberShape(t *testing.T) {
    input := Order{
        OrderID: 9007199254740993,
        Items:   []Item{{Price: 19900}},
    }

    // 全局选项应递归字符串化顶层和嵌套数字。
    got, err := jsonv2.Marshal(input, jsonv2.StringifyNumbers(true))
    if err != nil {
        t.Fatalf("marshal legacy payload: %v", err)
    }

    want := `{"order_id":"9007199254740993","items":[{"price":"19900"}]}`
    if string(got) != want {
        // 直接比较协议字节，避免只验证回读后的 Go 值。
        t.Fatalf("wire shape mismatch\nwant: %s\n got: %s", want, got)
    }

    var decoded Order
    // 使用同一选项验证字符串数字能无损回到 int64。
    if err := jsonv2.Unmarshal(got, &decoded, jsonv2.StringifyNumbers(true)); err != nil {
        t.Fatalf("unmarshal legacy payload: %v", err)
    }
    if decoded.OrderID != input.OrderID {
        t.Fatalf("order id lost precision: want %d, got %d", input.OrderID, decoded.OrderID)
    }
}

如果响应成员顺序不是协议的一部分，不要把整段 JSON 字符串比较当作唯一测试；可同时解析为 jsontext.Value 或对关键字段做结构断言。这里直接比较字节，是为了强调数字是否带引号这一条明确线格式要求。

灰度阶段看错误率，不猜兼容是否成功

这篇文章不提供虚构的压测数字。你需要从自己的客户端矩阵建立基线，并至少记录下面三类可归因指标：

• 解码错误率：按端点、客户端版本和字段名统计语义解码错误，观察字符串数字与裸数字不匹配。
• 响应线格式：在测试或采样日志中记录目标字段是 JSON number 还是 JSON string，不记录敏感业务值。
• 契约测试通过率：旧客户端、新客户端、边界大整数和嵌套对象各自必须全部通过后再扩大流量。

灰度假设可以写成一句可验证的话：“旧客户端失败来自订单号为 JSON number；仅把订单号改为字符串后，旧客户端解析失败归零，同时新客户端契约测试保持通过。”若数据不支持这句话，就撤回改动，而不是继续扩大 StringifyNumbers 的作用范围。

迁移时把开关收在协议边界

一个容易维护的结构是：领域模型保持自然 Go 数值；旧响应 DTO 用 ,string 标出少数字段；确实全量字符串化的旧端点在编码器封装中传入 StringifyNumbers(true)；新端点使用 json/v2 默认数字语义。编码和解码分别配置，不共享一个含糊的“legacyJSON”布尔值。

package wire

import jsonv2 "encoding/json/v2"

// MarshalLegacy 只服务已经冻结的旧端点协议。
func MarshalLegacy(v any) ([]byte, error) {
    return jsonv2.Marshal(v, jsonv2.StringifyNumbers(true))
}

// MarshalCurrent 保持 json/v2 默认数字线格式，供新客户端使用。
func MarshalCurrent(v any) ([]byte, error) {
    return jsonv2.Marshal(v)
}

退出兼容层时也要有指标门槛：旧客户端流量降到可接受范围、相关契约测试从发布门禁中移除、旧 DTO 没有新调用方后，再删除字符串化入口。这样 StringifyNumbers 是一个有边界、可观察、能下线的协议工具，而不是永久散落在业务代码里的全局习惯。

常见问题

StringifyNumbers 会递归处理嵌套对象里的数字吗？

作为 Marshal 或 Unmarshal 的调用级选项时会递归应用。通过结构体字段的 ,string 标签启用时，只作用于该字段的顶层 JSON 值，不递归处理字段内部的对象或数组。

为什么字符串化大整数能避免 JavaScript 精度丢失？

因为数字以十进制文本放进 JSON 字符串，JavaScript 不会先把它转换为可能超出安全整数范围的 Number。客户端仍应把标识符保留为字符串，或显式转换为 BigInt。

开启 StringifyNumbers 后能同时接受数字和字符串数字吗？

不能把它理解为双格式宽松开关。解码时启用该选项意味着从 JSON 字符串解析数字。需要双格式过渡时，应使用独立版本 DTO、端点路由或经过测试的自定义字段类型。

字段标签和调用级选项应该选哪个？

少数字段兼容旧协议时优先字段标签；整个端点的数字都必须字符串化时使用调用级选项。选择依据是已经确认的协议矩阵，而不是代码量多少。

迁移到 encoding/json/v2 必须立即改掉 encoding/json v1 吗？

不必。Go 1.27 继续维护现有 encoding/json 的兼容性。可以先为明确受益的端点建立 json/v2 DTO 和契约测试，再按风险逐步迁移。