Go encoding/json/jsontext Token 数字访问器现在返回 error 怎么改

如果升级到 Go 1.27 后，jsontext.Token.Int() 或 Uint() 的赋值突然报“多个值用于单值接收”，不是 JSON 格式变了，而是数字访问器的返回契约变了。现在应把调用改成 value, err := tok.Int()，并在业务边界判断 err；只要传入的 Token 不是 JSON 数字，访问器仍可能 panic，所以不能只靠忽略错误来兜底。

迁移的核心是把“读取数字”和“确认数字可按目标类型使用”拆开：先检查 Kind，再接收第二个返回值，最后用 errors.Is 区分语法错误与范围错误。

先把返回值改成“数值加错误”

Go 1.27 的 encoding/json/jsontext 用更明确的返回值暴露数字转换风险。Int() 返回 (int64, error)，Uint() 返回 (uint64, error)，浮点访问器也会返回错误。旧代码如果这样写：

// 旧写法：只接收数字，升级后会出现赋值数量不匹配。
count := tok.Int()

应改成下面的最小迁移形式。注释保留了两个关键判断：Token 类型要先确认，转换错误不能被静默丢掉。

package main

import (
    "encoding/json/jsontext"
    "fmt"
)

func readCount(tok jsontext.Token) (int64, error) {
    // 数字访问器对非数字 Token 可能 panic，先检查 Kind。
    if tok.Kind() != jsontext.KindNumber {
        return 0, fmt.Errorf("需要 JSON 数字，实际类型为 %v", tok.Kind())
    }
    // Int 现在同时返回转换结果和转换错误。
    value, err := tok.Int()
    if err != nil {
        return 0, fmt.Errorf("读取数量失败: %w", err)
    }
    return value, nil
}

上面的 Kind 示例提醒一个容易误用的点：不要在业务代码里猜常量字符。正式代码应使用当前版本文档提供的数字 Kind 判断方式，或在读取结构上下文已经保证 Token 为数字时直接调用并处理 error。文章关注的是返回值迁移，不要把字符串、true 或对象分隔符交给 Int。

按 JSON 数字边界处理 error

Int 和 Uint 的错误不是同一种情况。数字不符合目标访问器的整数语法时，错误可用 errors.Is(err, strconv.ErrSyntax) 判断；整数超出 int64 或 uint64 范围时，则对应 strconv.ErrRange。即使有错误，方法仍会返回一个合理值，超范围时会饱和到目标类型边界，小数部分会向零截断。因此，计数、金额或 ID 通常应该在错误时拒绝，而不是直接使用返回值。

package main

import (
    "encoding/json/jsontext"
    "errors"
    "fmt"
    "strconv"
)

func parseID(tok jsontext.Token) (uint64, error) {
    // 调用前必须保证 tok 是 JSON number，否则访问器可能 panic。
    value, err := tok.Uint()
    if err == nil {
        return value, nil
    }
    // 语法错误表示负数、小数或指数形式不符合无符号整数要求。
    if errors.Is(err, strconv.ErrSyntax) {
        return 0, fmt.Errorf("ID 必须是无符号整数: %w", err)
    }
    // 范围错误表示数值无法放进 uint64，不能把饱和值当成真实 ID。
    if errors.Is(err, strconv.ErrRange) {
        return 0, fmt.Errorf("ID 超出 uint64 范围: %w", err)
    }
    return 0, fmt.Errorf("未知的数字转换错误: %w", err)
}

如果业务确实允许小数转整数，要把这个决定写在调用方，而不是依赖访问器的隐式截断；如果要接收指数或普通小数，应选择 Float，再按业务规则做范围和精度检查。Float 越过 float64 可表示范围时同样会返回 ErrRange，不能只检查是否得到 +Inf 或 -Inf。

把 Token 生命周期和迁移一起检查

从 Decoder 读出的原始 Token 由 Decoder 的内部缓冲区支持，下一次调用 Decoder 方法后可能失效。若解析逻辑要把 Token 放进队列、缓存或延迟处理，应在离开当前读取位置前调用 Clone()；由 jsontext.Int、Uint 等构造函数创建的 typed Token 则是自包含的。

迁移可以按这份清单收尾：搜索所有 .Int()、.Uint()、.Float() 和 .Float32() 的调用；补上第二个返回值；在数字边界处理 ErrSyntax 与 ErrRange；确认非数字 Token 不会进入数字访问器；最后检查 Token 是否跨越 Decoder 的下一次读取。这样改动的重点不是“让编译通过”，而是把之前被隐藏的 JSON 数字可用性判断明确交给业务代码。

常见问题

为什么拿到 error 还会有一个数值？ 因为访问器对小数会截断，对超范围整数会返回饱和值；error 用来提醒调用方这个结果不应当按精确目标类型使用。

能不能只写 value, _ := tok.Int()？ 只有在调用方已经明确接受语法、范围和截断风险时才适合。订单金额、资源配额和外部 ID 等字段不应这样忽略错误。