Go jsontext Token 为什么数值访问器返回 error（参数形态）

如果你看到 jsontext.Token 的数值方法从“返回一个数”变成了“返回数值和 error”，通常不是 API 多余设计，而是输入的 JSON 数字不一定能无损、合法地落到目标 Go 类型。Go 1.27 的 encoding/json/jsontext 把这层解析边界明确暴露出来：Int、Uint、Float 和 Float32 都可能返回错误。

官方地址：https://pkg.go.dev/encoding/json/jsontext

排查时先看 Token.Kind()，再按目标类型选择访问器，最后处理 error。整数语法不匹配主要是 strconv.ErrSyntax，超出目标数值范围主要是 strconv.ErrRange；即使同时拿到了一个数值，也不能跳过 error。

数值访问器为什么必须返回 error

Token 可以来自解码器，也可以由 jsontext.Int、jsontext.Uint、jsontext.Float 等构造器创建。构造器已经知道目标 Go 类型；而访问器面对的是一个 JSON token，需要再次判断它能否按调用者要求解释。

package main

import (
	"errors"
	"fmt"
	"strconv"

	"encoding/json/jsontext"
)

func readCount(tok jsontext.Token) (int64, error) {
	// 先确认输入是 JSON number，避免把字符串或结构分隔符当成整数。
	if tok.Kind() != jsontext.KindNumber {
		return 0, fmt.Errorf("不是 JSON number: %s", tok.Kind())
	}

	n, err := tok.Int()
	if err != nil {
		// 语法错误和范围错误都要交给调用方决定是否拒绝。
		if errors.Is(err, strconv.ErrSyntax) || errors.Is(err, strconv.ErrRange) {
			return n, err
		}
		return n, err
	}
	return n, nil
}

因此返回值的两个部分要一起看。比如小数按 Int 读取时，文档允许返回向零截断后的数值，但同时报告语法错误；调用方若只使用数值，就可能把格式错误的输入当成合法计数。

先看 Token.Kind，再看参数形态

数值访问器的前提是 token 属于 JSON number。字符串、布尔值、null 以及对象和数组的开始/结束分隔符，都不是普通数值输入。这个判断与“数字内容是否能落入目标类型”是两层问题，不能只依赖一次类型转换。

func classify(tok jsontext.Token) string {
	// Kind 只回答 token 的词法类别，不替代 Int、Uint 或 Float 的范围判断。
	switch tok.Kind() {
	case jsontext.KindNumber:
		return "可以进入数值访问器"
	case jsontext.KindString:
		return "字符串：不要按普通整数读取"
	default:
		return "其它 JSON token：先按业务规则处理"
	}
}

有了 JSON number，下一步才是匹配访问器：

syntax、range 和截断不是一回事

最容易混淆的是“方法给了一个结果”与“输入已经通过解析”这两件事。Int 和 Uint 会针对整数语法和表示范围返回不同错误；在发生错误时，文档仍可能给出一个合理的饱和值或截断值，这个值用于诊断，不等于业务上可以接受。

func acceptInteger(tok jsontext.Token) (int64, error) {
	// 先保留 error；不要因为 n 看起来合理就继续写入数据库或计数器。
	n, err := tok.Int()
	if err != nil {
		if errors.Is(err, strconv.ErrSyntax) {
			return 0, fmt.Errorf("数字格式不符合有符号整数: %w", err)
		}
		if errors.Is(err, strconv.ErrRange) {
			return 0, fmt.Errorf("数字超出 int64 范围: %w", err)
		}
		return 0, err
	}
	return n, nil
}

例如 12.8 不是严格的有符号整数形态；即使得到向零截断的 12，也应该由业务明确决定是否接受。负数交给 Uint、极大的整数交给 Int，同样不能靠“返回了一个数”来掩盖不匹配。

写代码时保留这张边界清单

1. 先用 Kind() 排除非 number token。
2. 目标是整数时，明确是否允许小数截断；不允许就把 ErrSyntax 当作拒绝条件。
3. 目标是无符号数时，单独处理负数和超出 uint64 的输入。
4. 普通 JSON 数字优先使用 Float()；只有协议明确为 32 位精度时才选 Float32()。
5. 使用 errors.Is 判断 strconv.ErrSyntax 与 strconv.ErrRange，不要匹配易变化的错误字符串。

归纳起来，error 是数值访问器对“参数形态”的反馈：它告诉你 JSON token 是否符合目标 Go 类型的语法和范围。保留这个反馈，才能把格式错误、溢出和业务允许的截断区分开。

相关问题

为什么 Int 返回了数字还要检查 error？

因为返回值可能是截断值或范围边界值。它可以帮助诊断输入，但只有 error 为 nil 时才表示通过了该访问器的解析条件。

Float32 是否比 Float 更省事？

不是。官方文档建议只有在调用方确认输入按 32 位精度编码时才使用 Float32；一般 JSON 数字应优先按 float64 处理。