Go / 技术文章

Go JSON 编解码为什么会丢精度和字段

Go 的 encoding/json 在处理数字和结构体字段时有明确规则:JSON 数字解到 interface{} 默认进入 float64,结构体字段则受导出规则、类型匹配和 json 标签影响。掌握这些边界后,可以定位大整数精度变化、字段缺失以及编码结果不符合预期的问题,并选择合适的目标类型。

大整数为什么会丢精度

调用 json.Unmarshal 把 JSON 解到 interface{} 或 map[string]interface{} 时,JSON 数字默认使用 float64 保存。IEEE 754 双精度浮点数不能精确表示所有超过 2532^{53} 的整数,因此类似订单号、时间戳或外部系统 ID 的大整数可能在解码后发生变化。

例如:

go
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() 保留数字文本:

go
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)
}

预期结果:

text
json.Number 9007199254740993

UseNumber 只解决通用容器中的数字表示问题,不会自动替你决定这个数字最终应该是 int64、uint64 还是其他类型。

字段为什么解码不进去

JSON 字段能否写入 Go 结构体,首先取决于目标字段是否可被 encoding/json 设置。普通小写字段是未导出的,因此不会被默认解码;大写字段可以参与解码。字段名还会受到 json 标签影响。

go
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 会让满足空值条件的字段被省略。

go
type Response struct {
    ID       int64  `json:"id"`
    Name     string `json:"name,omitempty"`
    Internal string `json:"-"`
}

v := Response{
    ID:       42,
    Internal: "trace-only",
}

预期结果:

json
{"id":42}

这里 Name 因为空字符串而被 omitempty 省略,Internal 则因 json:"-" 永远不会出现在结果中。需要区分“字段没有编码”与“字段被标签规则主动省略”。

标签不匹配时会发生什么

结构体字段没有标签时,encoding/json 会根据字段名进行匹配,并且匹配规则并不要求 JSON 键与 Go 字段大小写完全一致。但在公共 API、消息协议和配置文件中,显式写标签更稳定,因为它明确了外部字段名。

go
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()。

go
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。

当一个字段可能缺失,并且“缺失”和“零值”具有不同业务含义时,可以使用指针字段区分两种状态:

go
type PatchRequest struct {
    Enabled *bool  `json:"enabled"`
    Limit   *int64 `json:"limit"`
}

预期结果:当 JSON 中没有 enabled 时,Enabled == nil;当 JSON 明确传入 false 时,Enabled 非空且指向 false。这样可以避免把“没有传”误判成“传了零值”。

处理 JSON 异常时,可以按“目标类型 → 字段导出状态 → json 标签 → 数字类型 → 是否允许未知字段”的顺序排查。先确认数据落到什么 Go 类型,再看字段映射规则,通常比直接反复修改 JSON 样例更快定位问题。

目录与阅读设置

记录一个想法

Go JSON 编解码为什么会丢精度和字段

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通