Go / 技术文章
Go JSON 编解码为什么会丢精度和字段
Go 的 encoding/json 在处理数字和结构体字段时有明确规则:JSON 数字解到 interface{} 默认进入 float64,结构体字段则受导出规则、类型匹配和 json 标签影响。掌握这些边界后,可以定位大整数精度变化、字段缺失以及编码结果不符合预期的问题,并选择合适的目标类型。
大整数为什么会丢精度
调用 json.Unmarshal 把 JSON 解到 interface{} 或 map[string]interface{} 时,JSON 数字默认使用 float64 保存。IEEE 754 双精度浮点数不能精确表示所有超过 的整数,因此类似订单号、时间戳或外部系统 ID 的大整数可能在解码后发生变化。
例如:
package main
import (
"encoding/json"
"fmt"
)
func main() {
data := []byte(`{"id":9007199254740993}`)
var v map[string]interface{}
if err := json.Unmarshal(data, &v); err != nil {
panic(err)
}
fmt.Printf("%T %v\n", v["id"], v["id"])
}预期结果会显示 float64,数值可能无法保持原始整数的精确值。
需要保留整数语义时,优先让字段拥有明确的整数类型;若必须使用通用 JSON 容器,则可以通过 Decoder.UseNumber() 保留数字文本:
package main
import (
"encoding/json"
"fmt"
"strings"
)
func main() {
data := `{"id":9007199254740993}`
dec := json.NewDecoder(strings.NewReader(data))
dec.UseNumber()
var v map[string]interface{}
if err := dec.Decode(&v); err != nil {
panic(err)
}
n := v["id"].(json.Number)
id, err := n.Int64()
if err != nil {
panic(err)
}
fmt.Printf("%T %d\n", n, id)
}预期结果:
json.Number 9007199254740993UseNumber 只解决通用容器中的数字表示问题,不会自动替你决定这个数字最终应该是 int64、uint64 还是其他类型。
字段为什么解码不进去
JSON 字段能否写入 Go 结构体,首先取决于目标字段是否可被 encoding/json 设置。普通小写字段是未导出的,因此不会被默认解码;大写字段可以参与解码。字段名还会受到 json 标签影响。
package main
import (
"encoding/json"
"fmt"
)
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
password string `json:"password"`
}
func main() {
data := []byte(`{"id":7,"name":"alice","password":"secret"}`)
var u User
if err := json.Unmarshal(data, &u); err != nil {
panic(err)
}
fmt.Printf("%+v\n", u)
}预期结果:ID 和 Name 能得到 JSON 中的值,而未导出的 password 保持零值。即使 JSON 中存在同名键,也不能通过默认反射机制写入未导出字段。
实际排查时,应先检查结构体字段首字母、json 标签以及目标字段类型,再判断是否真的存在“JSON 丢字段”。
字段为什么编码后又消失
编码到 JSON 时,字段同样受导出规则和标签控制。未导出字段不会输出,json:"-" 会明确禁止输出,而 omitempty 会让满足空值条件的字段被省略。
type Response struct {
ID int64 `json:"id"`
Name string `json:"name,omitempty"`
Internal string `json:"-"`
}
v := Response{
ID: 42,
Internal: "trace-only",
}预期结果:
{"id":42}这里 Name 因为空字符串而被 omitempty 省略,Internal 则因 json:"-" 永远不会出现在结果中。需要区分“字段没有编码”与“字段被标签规则主动省略”。
标签不匹配时会发生什么
结构体字段没有标签时,encoding/json 会根据字段名进行匹配,并且匹配规则并不要求 JSON 键与 Go 字段大小写完全一致。但在公共 API、消息协议和配置文件中,显式写标签更稳定,因为它明确了外部字段名。
type Request struct {
UserID int64 `json:"user_id"`
CreatedAt string `json:"created_at"`
}对于这样的定义,JSON 应使用 user_id 和 created_at。若代码写成 json:"userid",它描述的是另一个外部字段名。修改结构体字段名而不检查标签,也可能导致序列化结果与接口契约不一致。
还需要注意 json:"-"、omitempty 以及标签中额外的选项。不要只盯着 JSON 样例,还要直接查看编译后的结构体定义。
如何避免宽松解码掩盖问题
默认 json.Unmarshal 遇到目标结构体中不存在的 JSON 字段时通常会忽略它。这适合兼容接口演进,但对严格配置解析或协议校验可能过于宽松。此时可以使用 Decoder.DisallowUnknownFields()。
package main
import (
"encoding/json"
"fmt"
"strings"
)
type Config struct {
Host string `json:"host"`
Port int `json:"port"`
}
func main() {
data := `{"host":"127.0.0.1","port":8080,"porrt":9000}`
dec := json.NewDecoder(strings.NewReader(data))
dec.DisallowUnknownFields()
var cfg Config
if err := dec.Decode(&cfg); err != nil {
fmt.Println(err)
return
}
fmt.Printf("%+v\n", cfg)
}预期结果会报告未知字段 porrt,从而及时发现拼写错误,而不是静默忽略它。
API 和消息场景怎么选类型
对 API 请求、消息事件和配置结构,优先使用明确的结构体,而不是先解析成 map[string]interface{} 再自行断言。金额、计数器、ID 等具有整数语义的数据,使用合适的整数类型或字符串表示;需要保留任意 JSON 数字原文时,再考虑 json.Number。
当一个字段可能缺失,并且“缺失”和“零值”具有不同业务含义时,可以使用指针字段区分两种状态:
type PatchRequest struct {
Enabled *bool `json:"enabled"`
Limit *int64 `json:"limit"`
}预期结果:当 JSON 中没有 enabled 时,Enabled == nil;当 JSON 明确传入 false 时,Enabled 非空且指向 false。这样可以避免把“没有传”误判成“传了零值”。
处理 JSON 异常时,可以按“目标类型 → 字段导出状态 → json 标签 → 数字类型 → 是否允许未知字段”的顺序排查。先确认数据落到什么 Go 类型,再看字段映射规则,通常比直接反复修改 JSON 样例更快定位问题。