Go 语言开发里JSON 序列化和反序列化可以说是一天到晚都在碰的东西。不管是写 API 接口、对接第三方服务还是把数据丢进 Redis 或者消息队列只要数据要出进程几乎都会经手一遍encoding/json。很多刚开始用 Go 的同事会觉得这不就是json.Marshal和json.Unmarshal两个函数来回调吗能有什么好讲的但在实际项目里跑一段时间就会发现坑全藏在看似基础的地方数字精度丢了、时间格式不对、字段莫名消失、大 JSON 把内存撑爆……这些问题排查起来都不轻松。这篇文章我想把 Go JSON 处理这件事从基础用法到高阶技巧完整梳理一遍重点放在那些容易踩坑、官方文档又没有细说的细节上。无论你是刚接触 Go 的新人还是已经在生产环境里写过一阵子接口的开发者这篇文章应该都能帮你在下次遇到 JSON 问题时少走点弯路。1. 基础用法先把序列化和反序列化跑通1.1 序列化Marshal 把结构体变成 JSONjson.Marshal是使用频率最高的函数把 Go 的结构体、切片、map 转成 JSON 字节流。用法上没有任何门槛package main import ( encoding/json fmt ) type User struct { Name string Age int Email string } func main() { u : User{ Name: 张三, Age: 28, Email: zhangsanexample.com, } data, err : json.Marshal(u) if err ! nil { panic(err) } fmt.Println(string(data)) // 输出: {Name:张三,Age:28,Email:zhangsanexample.com} }序列化的结果非常直观字段名默认直接用 Go 结构体里的字段名。不过有一个容易忽略的点Marshal只能处理 Go 已导出的字段也就是大写字母开头的字段。如果结构体里有一个password string这种小写字段它会被静默忽略不会报错也不会出现在 JSON 里。这一点在早期排查问题的时候特别容易懵。比如你明明定义了一个字段序列化出来却总是没有第一反应通常是去查代码结果翻半天才发现是小写字段被忽略了。所以在设计结构体时如果你希望某个字段参与 JSON 序列化一定要确保它是导出字段。另一个需要留意的点是序列化 map、slice 这类类型时如果内部包含interface{}值实际输出类型取决于具体值。比如map[string]interface{}{count: 1}输出的是数字1而map[string]interface{}{count: float64(1)}也会输出数字1但如果你塞进去一个[]byte默认会转成 base64 字符串而不是输出一个数组。这条规则在序列化时作用不大但在反序列化和重新序列化时会造成不小的麻烦后面会展开讲。1.2 反序列化Unmarshal 把 JSON 还原成结构体反序列化的标准姿势也简单func main() { jsonStr : {Name:张三,Age:28,Email:zhangsanexample.com} var u User err : json.Unmarshal([]byte(jsonStr), u) if err ! nil { panic(err) } fmt.Printf(%v\n, u) }注意这里必须传u也就是结构体指针。因为Unmarshal需要修改调用方传入的变量如果直接传结构体值那只是拷贝一份解析结果写不回去。这个和 Go 语言里sort、json.Decoder.Decode这类需要修改接收者的函数是一回事。字段匹配的规则也有讲究。Unmarshal匹配 JSON 里的 key 和结构体字段时优先使用字段的 tag 名称没有 tag 就尝试大小写不敏感的字段名匹配。所以 JSON 里给的是name结构体字段是Name也能正确匹配。这就是为什么从很多接口拿到的数据 key 是小写结构体字段是大写也能解析成功的原因。但反序列化也有一套严格的类型校验规则。JSON 里的字符串不能直接塞给 int 字段JSON 里的数字不能期望它自动转成字符串否则会报cannot unmarshal string into Go value of type int这种错误。和 PHP、JavaScript 那种隐式类型转换完全不同Go 在类型上较真得很。这也是很多从动态语言转过来的同事最不习惯的地方。不过这种较真在多数场景下是好事它倒逼你在数据边界上想清楚。比如某个字段在接口文档里说好了是数字但实际返回了一个空字符串如果直接解析就会报错。你必须在结构体里设计成string类型或者自定义解析逻辑来处理这种脏数据。这种问题在对接第三方 API 时极其常见后面自定义解析的部分会专门讲。2. 结构体标签搞定字段映射、空值和类型转换2.1 tag 里最常用的三个参数结构化开发中大多数情况下我们不希望 JSON 的 key 和 Go 字段名完全一致。比如前端习惯小驼峰后端字段习惯大写开头或者接口需要忽略某个字段。这时候就要用结构体 tag。type User struct { Name string json:name Age int json:age Email string json:email,omitempty Token string json:- }tag 里最常用的三个参数json:name指定 JSON 里的 key 名。json:name,omitempty字段值为零值时序列化时忽略这个字段。json:-直接忽略该字段不管是序列化还是反序列化都不参与。omitempty的语义要重点解释一下。它判断的是“零值”不是“空值”。比如Age int的零值是0就算业务上年龄为 0 是有意义的加了omitempty后序列化依然会丢弃这个字段。false、空字符串、nil 指针、长度为 0 的 slice 和 map 同理。这里有一个常见的需求陷阱我想在字段为 nil 时忽略但为 0 时要保留。omitempty帮不了你你得自定义类型或者用指针类型因为指针为 nil 时才被忽略指向 0 的内存地址不算 nil。所以实际开发中如果某个数字字段可能取 0 但语义上又需要保留最稳妥的方案是把这个字段定义成*int或者*float64。2.2 嵌套结构体与匿名嵌入的坑嵌套结构体在 JSON 处理里很常见比如订单里有用户信息type Order struct { OrderID string json:order_id User User json:user }这种嵌套的序列化和反序列化都是递归的只要内层结构体能正确处理外层就没有额外负担。这里真正容易踩坑的是匿名嵌入字段。type Base struct { ID int json:id } type Product struct { Base Name string json:name }默认情况下匿名嵌入了Base序列化时Product会直接把Base的字段“提升”到外层输出{id:1,name:...}而不是{Base:{id:1},name:...}。这其实是 Go 的字段提升机制在起作用用起来确实方便像继承一样的组合效果。但嵌套多了会有隐患当两个匿名结构体里有同名字段时序列化不会报错而是默认取最外层或者按提升规则取一个。这就导致数据可能被静默丢弃。所以我的个人习惯是如果匿名嵌入的字段是给 JSON 用的明确定义一层json:base或者干脆把公共字段单独拆出来不要依赖匿名字段的合并行为可读性和可维护性都更好。3. 类型与边界数字精度、时间和动态字段怎么处理3.1 大整数精度问题这是我见过生产环境里出现频率最高的坑之一。Go 的encoding/json在把 JSON 数字解析到interface{}时默认会使用float64类型。而float64对于超过 2^53-1 的数字会丢失精度比如雪花算法生成的 int64 ID在 map 里转一圈回来发现末尾几位变成了 0。看个例子func main() { data : []byte({id: 12345678901234567890}) var m map[string]interface{} json.Unmarshal(data, m) fmt.Printf(%v\n, m[id]) // 输出: 1.2345678901234568e19 }这个id已经彻底失真了。解决方案主要有两种第一种是使用json.Decoder配合UseNumber()方法把数字解析成json.Number类型而不是float64func main() { data : []byte({id: 12345678901234567890}) dec : json.NewDecoder(bytes.NewReader(data)) dec.UseNumber() var m map[string]interface{} dec.Decode(m) fmt.Printf(%v\n, m[id]) // 输出: 12345678901234567890 }第二种是直接把结构体里的字段定义为int64、uint64或json.Number这样解析时就能保持完整精度。但如果接口的 JSON 结构不确定只能用map[string]interface{}或者interface{}接收时UseNumber()几乎是必选项。我还见过另一种变体前端传一个订单号或者手机号过来后端如果用int64接收没问题但如果在结构体里定义了float64或者用interface{}接收再序列化原本的字符串很可能被解析成数字再次序列化时引号都没了数字的精度也没了。这种问题极其隐蔽因为它不会报错只会在数据流的下游突然冒出错误的结果。排查时要特别留意数字的“流转路径”设计字段类型时尽量显式、具体。3.2 时间字段的格式控制Go 里时间字段默认序列化成RFC3339格式比如2025-04-01T15:04:0508:00。这个格式的好处是标准、有国际化支持坏处是很多国内业务和后端系统习惯用2006-01-02 15:04:05这种形式前端拿到时间后如果直接用 JS 的Date解析容易出问题。如果你希望时间输出成习惯的格式就需要自定义类型或者实现MarshalJSON/UnmarshalJSON方法。最简单的做法是在结构体里用string字段接收然后在业务层转换。但如果项目里有大量地方都要处理时间我更推荐定义一个自定义时间类型type Time time.Time func (t Time) MarshalJSON() ([]byte, error) { return []byte(fmt.Sprintf(%s, time.Time(t).Format(2006-01-02 15:04:05))), nil } func (t *Time) UnmarshalJSON(data []byte) error { s : strings.Trim(string(data), ) v, err : time.Parse(2006-01-02 15:04:05, s) if err ! nil { return err } *t Time(v) return nil }这样在结构体里把字段声明成Time类型就能自动控制序列化格式。注意UnmarshalJSON接收到的 data 是 JSON 里的原始字节流字符串自带引号所以要先Trim掉引号再解析。这一点在写自定义解析时很容易漏。3.3 动态字段json.RawMessage 的妙用对接第三方 API 或者接收前端动态表单时JSON 结构经常不完全确定。有些字段可能不存在有些字段的类型在不同场景下会变化。这时候如果强行定义一个 struct每次解析都要报错或者丢字段。json.RawMessage可以解决一类很实际的问题延迟解析。它本质上是一个[]byte别名在反序列化时不会真正展开内容而是把原始 JSON 片段原样保存下来。等到你需要用的时候再按具体的结构去解析。type Response struct { Code int json:code Data json.RawMessage json:data } func handle(data []byte) error { var resp Response if err : json.Unmarshal(data, resp); err ! nil { return err } // 不确定 data 的内部结构先判断再解析 var obj map[string]interface{} if err : json.Unmarshal(resp.Data, obj); err ! nil { return err } // 或者是解析成确定的结构体 var user User if err : json.Unmarshal(resp.Data, user); err ! nil { return err } }这种做法在接收 Webhook 回调、处理事件消息时特别好用。比如一个消息体里既有业务数据也有元数据元数据处理不了也不影响业务数据的解析。即便其中一个字段的格式变了也不会导致整个Unmarshal失败你完全可以在后续按需处理。需要注意的一点是json.RawMessage在序列化时会把原始字节流原样输出不会额外转义。这既是优点也是隐患如果你往RawMessage里塞的东西本身不是合法 JSON序列化的结果也会是不合法 JSON。所以在往RawMessage里写内容时务必确认它是有效的 JSON 片段。4. 自定义解析当标准库不够用的时候4.1 实现 MarshalJSON / UnmarshalJSON 的完整流程有些特殊场景标准库的默认行为无法满足需求最典型的包括字段需要加密或脱敏序列化时输出掩码反序列化时还原。接口返回的字段格式比较怪比如数字被写成了字符串。需要兼容前端传过来的多种格式。这些情况下自定义MarshalJSON/UnmarshalJSON是最灵活的解决方案。以脱敏为例type Phone string func (p Phone) MarshalJSON() ([]byte, error) { s : string(p) if len(s) 11 { s s[:3] **** s[7:] } return []byte(fmt.Sprintf(%q, s)), nil }写入 JSON 时手机号就变成了138****1234而存储时还是完整的字符串。反序列化时因为字段类型是自定义的Phone底层是string默认解析行为不受影响所以也不需要额外实现UnmarshalJSON。如果你要实现UnmarshalJSON有一点特别重要方法接收的是原始 JSON 字节流你需要先用一个 alias 类型做一次标准解析避免递归调用死循环。比如func (p *Phone) UnmarshalJSON(data []byte) error { var s string if err : json.Unmarshal(data, s); err ! nil { return err } *p Phone(s) return nil }如果你在UnmarshalJSON里直接对p调json.Unmarshal(data, p)会因为类型匹配再次进入当前方法形成无限递归直到栈溢出。正确做法是定义一个新的 alias 类型让它的类型和方法区分开type PhoneAlias Phone func (p *Phone) UnmarshalJSON(data []byte) error { var pa PhoneAlias if err : json.Unmarshal(data, pa); err ! nil { return err } *p Phone(pa) return nil }这算是自定义反序列化初学者的第一道鬼门关很多新手在这里卡很久其实就是没搞明白“方法调用”和“类型方法集”的关系。4.2 自定义解析的典型应用场景除了脱敏我接触得比较多的自定义解析场景还有两种。第一种是兼容接口的脏数据。比如有个老接口正常情况返回count: 5但某天量特别大的时候偶发返回count: 。如果你把字段定义为int解析直接报错定义为string正常的数字又会被当成字符串处理。自定义类型就能两全type FlexibleInt int func (f *FlexibleInt) UnmarshalJSON(data []byte) error { s : strings.Trim(string(data), ) if s || s null { *f 0 return nil } v, err : strconv.Atoi(s) if err ! nil { return err } *f FlexibleInt(v) return nil }第二种是重新定义字段类型。比如前端传一个坐标字符串39.9042,116.4074你希望直接映射成结构体里的Latitude和Longitude两个字段。直接在结构体里搞不定得在自定义类型的UnmarshalJSON里用strings.Split把字符串拆开再赋值给两个字段。虽然这类做法适用范围窄但在写数据清洗、ETL 类服务时能省掉一大部分手动处理逻辑。5. 性能优化与流式处理5.1 Encoder/Decoder 处理大 JSON大多数例子都在用json.Marshal/json.Unmarshal这两个函数对数据是整体进出内存的。数据量小还好如果 JSON 有几十 MB 甚至上百 MB一次json.Unmarshal会分配大量临时结构体内存占用瞬间飙高GC 压力也跟着上来了。流式处理的思路是使用json.Decoder和json.Encoder。Decoder可以从io.Reader按 Token 或者按值分块读取Encoder可以向io.Writer流式写入两者配合可以做到边读边处理不必把整个数据帧一次性载入内存。举个例子处理一个大文件里几千行 JSONfunc processLargeFile(r io.Reader) error { dec : json.NewDecoder(r) for dec.More() { var item Order if err : dec.Decode(item); err ! nil { return err } // 处理每一条订单 processOrder(item) } return nil }注意这里的dec.More()是配合“JSON 数组流”使用的。如果你的数据是一个[]Order数组用Decode循环逐条解析能有效避免一次性解析整个数组。但如果你不知道数据具体是对象还是数组可以先用一次Decode到一个json.RawMessage再决定后续怎么解析。Encoder的输出默认会带一个换行符这在某些写文件或传输场景下是友好的但如果你拼接多个 JSON 再整体返回给前端可能要多做一次 trim。这个细节在对接测试时容易忽略。5.2 减少内存分配与复用对象Go 的 JSON 序列化和反序列化性能问题核心基本都集中在反射和内存分配上。标准库每次Marshal会检查字段的 nested 层级在运行时反射字段 tag同时也免不了产生临时对象。如果你的服务对 QPS 敏感或者请求体很大标准库在高并发下确实会成为瓶颈。有几个优化方向可以尝试第一个方向是避免反复Marshal同一个结构。比如从数据库查出来的对象短时间内多次需要输出 JSON可以先序列化一次然后复制字节切片。在 Go 里拷贝一个切片的成本远远低于重新反射解析一次。第二个方向是使用sync.Pool复用缓冲区。在循环场景里频繁Marshal每次都创建一个[]byteGC 压力不小。可以自己维护一个缓冲池var bufPool sync.Pool{ New: func() any { return bytes.NewBuffer(nil) }, } func marshalWithPool(v any) ([]byte, error) { buf : bufPool.Get().(*bytes.Buffer) defer bufPool.Put(buf) buf.Reset() if err : json.NewEncoder(buf).Encode(v); err ! nil { return nil, err } return bytes.TrimSuffix(buf.Bytes(), []byte(\n)), nil }这样在高频序列化场景下能明显减少内存分配次数。需要注意缓冲池里的对象被取用后要Reset否则上一次的数据会污染本次输出。第三个方向如果你的性能要求极其苛刻可以考虑使用第三方生成代码的库比如easyjson。它的原理是编译期根据结构体生成专门的序列化代码完全绕过反射速度能比标准库快好几倍。缺点是项目需要额外步骤生成代码结构体改动后要重新生成。个人观点是项目初期不必上这个等确实压测到瓶颈、确认标准库的 JSON 处理确实拖慢了整体性能再针对性地做这个优化更实际。6. 常见错误与排查速查表6.1 高频错误信息解读实际开发中遇到过的 JSON 报错信息就那几种这里整理成一份速查表方便排查时对照错误信息触发场景解决思路unexpected end of JSON input解析了一个空的 JSON 字符串比如或 EOF先判断输入是否为空或者用valid校验cannot unmarshal string into Go value of type intJSON 里是字符串结构体字段是数字类型改字段类型为string或自定义UnmarshalJSONcannot unmarshal object into Go value of type stringJSON 里是对象结构体字段是字符串检查接口的返回结构是否和预期一致invalid character x looking for beginning of value字节流前面有 BOM 或者多余字符先bytes.TrimSpace或处理 BOMjson: unsupported type: map[interface{}]interface{}对一个包含interface{}键的 map 做序列化避免使用map[interface{}]interface{}改成map[string]interface{}这里特别展开说一下unexpected end of JSON input。很多人一看到这个错误就以为 JSON 格式不对但实际上它经常出现在“空字符串”或“纯空白”输入的场景。比如从数据库读出一个空字符串直接传给json.Unmarshal就会报这个错。排查思路是确认数据源不为空或者解析前加一层len(data) 0的判断。6.2 排查思路和经验方法JSON 相关的问题排查难度最高的往往不是报错本身而是数据内容在隐式转换后“没有报错但结果不对”。举例来说我在对接一个内部系统时接口返回的字段orderId在文档里是数字但某些极端情况下会返回超大整数。结构体里定义成int64其实没问题但有个同事为了省事直接用map[string]interface{}接收然后把这个 map 序列化后塞给下流系统。结果就是订单号从小数变成了科学计数法下流系统怎么比对都对不上。这类问题不报错需要你顺着数据流做字段级排查。经验方法有三条第一条尽量少用map[string]interface{}接收数据。在明确知道结构的情况下用具体的 struct。不确定的字段用json.RawMessage兜底这样既能保证可解析性也能在出问题时定位到具体字段。第二条反序列化后做一次数据校验。不要假设解析成功就等于数据正确。关键字段是否为空、数字范围是否符合预期、时间格式是否正常在入口处统一校验一遍省去下游排查的大量精力。第三条给接口层的数据结构写单元测试。尤其是时间格式、数字精度、特殊字符转义这三类用例一旦测过后续重构或者数据结构变动时能快速发现问题。7. 最后的实操心得做个总结的话Go 的 JSON 处理虽然入门门槛低但想要用得稳、用得高效还是有不少值得打磨的细节。我自己的体会是设计和数据结构时尽量把类型定准确不要图省事全用interface{}否则问题会沿着调用链越传越远。结构体 tag 定清晰别混用大小写和不同命名风格团队协作时能少掉很多 battle。遇到不确定的字段字段结构优先用json.RawMessage兜底别着急定死结构。在实际项目里我见过太多因为 JSON 精度丢失导致的对账问题、因为时间格式不一致导致的前后端扯皮、因为omitempty误用导致的字段丢失。这些问题大多数都可以靠类型设计和显式解析来避免。如果你刚开始接触 Go建议从最简单的结构体映射开始慢慢把 tag 规则、类型边界、自定义解析这些点一个个吃透。只要每一个环节都清楚明白Go 的 JSON 处理能从“能跑”变成“稳得很”。 
长河君 · 2026/9/15 1:58:24 · 阅读 1.2k Go语言JSON序列化与反序列化避坑指南：从基础到性能优化
Go 语言开发里JSON 序列化和反序列化可以说是一天到晚都在碰的东西。不管是写 API 接口、对接第三方服务还是把数据丢进 Redis 或者消息队列只要数据要出进程几乎都会经手一遍encoding/json。很多刚开始用 Go 的同事会觉得这不就是json.Marshal和json.Unmarshal两个函数来回调吗能有什么好讲的但在实际项目里跑一段时间就会发现坑全藏在看似基础的地方数字精度丢了、时间格式不对、字段莫名消失、大 JSON 把内存撑爆……这些问题排查起来都不轻松。这篇文章我想把 Go JSON 处理这件事从基础用法到高阶技巧完整梳理一遍重点放在那些容易踩坑、官方文档又没有细说的细节上。无论你是刚接触 Go 的新人还是已经在生产环境里写过一阵子接口的开发者这篇文章应该都能帮你在下次遇到 JSON 问题时少走点弯路。1. 基础用法先把序列化和反序列化跑通1.1 序列化Marshal 把结构体变成 JSONjson.Marshal是使用频率最高的函数把 Go 的结构体、切片、map 转成 JSON 字节流。用法上没有任何门槛package main import ( encoding/json fmt ) type User struct { Name string Age int Email string } func main() { u : User{ Name: 张三, Age: 28, Email: zhangsanexample.com, } data, err : json.Marshal(u) if err ! nil { panic(err) } fmt.Println(string(data)) // 输出: {Name:张三,Age:28,Email:zhangsanexample.com} }序列化的结果非常直观字段名默认直接用 Go 结构体里的字段名。不过有一个容易忽略的点Marshal只能处理 Go 已导出的字段也就是大写字母开头的字段。如果结构体里有一个password string这种小写字段它会被静默忽略不会报错也不会出现在 JSON 里。这一点在早期排查问题的时候特别容易懵。比如你明明定义了一个字段序列化出来却总是没有第一反应通常是去查代码结果翻半天才发现是小写字段被忽略了。所以在设计结构体时如果你希望某个字段参与 JSON 序列化一定要确保它是导出字段。另一个需要留意的点是序列化 map、slice 这类类型时如果内部包含interface{}值实际输出类型取决于具体值。比如map[string]interface{}{count: 1}输出的是数字1而map[string]interface{}{count: float64(1)}也会输出数字1但如果你塞进去一个[]byte默认会转成 base64 字符串而不是输出一个数组。这条规则在序列化时作用不大但在反序列化和重新序列化时会造成不小的麻烦后面会展开讲。1.2 反序列化Unmarshal 把 JSON 还原成结构体反序列化的标准姿势也简单func main() { jsonStr : {Name:张三,Age:28,Email:zhangsanexample.com} var u User err : json.Unmarshal([]byte(jsonStr), u) if err ! nil { panic(err) } fmt.Printf(%v\n, u) }注意这里必须传u也就是结构体指针。因为Unmarshal需要修改调用方传入的变量如果直接传结构体值那只是拷贝一份解析结果写不回去。这个和 Go 语言里sort、json.Decoder.Decode这类需要修改接收者的函数是一回事。字段匹配的规则也有讲究。Unmarshal匹配 JSON 里的 key 和结构体字段时优先使用字段的 tag 名称没有 tag 就尝试大小写不敏感的字段名匹配。所以 JSON 里给的是name结构体字段是Name也能正确匹配。这就是为什么从很多接口拿到的数据 key 是小写结构体字段是大写也能解析成功的原因。但反序列化也有一套严格的类型校验规则。JSON 里的字符串不能直接塞给 int 字段JSON 里的数字不能期望它自动转成字符串否则会报cannot unmarshal string into Go value of type int这种错误。和 PHP、JavaScript 那种隐式类型转换完全不同Go 在类型上较真得很。这也是很多从动态语言转过来的同事最不习惯的地方。不过这种较真在多数场景下是好事它倒逼你在数据边界上想清楚。比如某个字段在接口文档里说好了是数字但实际返回了一个空字符串如果直接解析就会报错。你必须在结构体里设计成string类型或者自定义解析逻辑来处理这种脏数据。这种问题在对接第三方 API 时极其常见后面自定义解析的部分会专门讲。2. 结构体标签搞定字段映射、空值和类型转换2.1 tag 里最常用的三个参数结构化开发中大多数情况下我们不希望 JSON 的 key 和 Go 字段名完全一致。比如前端习惯小驼峰后端字段习惯大写开头或者接口需要忽略某个字段。这时候就要用结构体 tag。type User struct { Name string json:name Age int json:age Email string json:email,omitempty Token string json:- }tag 里最常用的三个参数json:name指定 JSON 里的 key 名。json:name,omitempty字段值为零值时序列化时忽略这个字段。json:-直接忽略该字段不管是序列化还是反序列化都不参与。omitempty的语义要重点解释一下。它判断的是“零值”不是“空值”。比如Age int的零值是0就算业务上年龄为 0 是有意义的加了omitempty后序列化依然会丢弃这个字段。false、空字符串、nil 指针、长度为 0 的 slice 和 map 同理。这里有一个常见的需求陷阱我想在字段为 nil 时忽略但为 0 时要保留。omitempty帮不了你你得自定义类型或者用指针类型因为指针为 nil 时才被忽略指向 0 的内存地址不算 nil。所以实际开发中如果某个数字字段可能取 0 但语义上又需要保留最稳妥的方案是把这个字段定义成*int或者*float64。2.2 嵌套结构体与匿名嵌入的坑嵌套结构体在 JSON 处理里很常见比如订单里有用户信息type Order struct { OrderID string json:order_id User User json:user }这种嵌套的序列化和反序列化都是递归的只要内层结构体能正确处理外层就没有额外负担。这里真正容易踩坑的是匿名嵌入字段。type Base struct { ID int json:id } type Product struct { Base Name string json:name }默认情况下匿名嵌入了Base序列化时Product会直接把Base的字段“提升”到外层输出{id:1,name:...}而不是{Base:{id:1},name:...}。这其实是 Go 的字段提升机制在起作用用起来确实方便像继承一样的组合效果。但嵌套多了会有隐患当两个匿名结构体里有同名字段时序列化不会报错而是默认取最外层或者按提升规则取一个。这就导致数据可能被静默丢弃。所以我的个人习惯是如果匿名嵌入的字段是给 JSON 用的明确定义一层json:base或者干脆把公共字段单独拆出来不要依赖匿名字段的合并行为可读性和可维护性都更好。3. 类型与边界数字精度、时间和动态字段怎么处理3.1 大整数精度问题这是我见过生产环境里出现频率最高的坑之一。Go 的encoding/json在把 JSON 数字解析到interface{}时默认会使用float64类型。而float64对于超过 2^53-1 的数字会丢失精度比如雪花算法生成的 int64 ID在 map 里转一圈回来发现末尾几位变成了 0。看个例子func main() { data : []byte({id: 12345678901234567890}) var m map[string]interface{} json.Unmarshal(data, m) fmt.Printf(%v\n, m[id]) // 输出: 1.2345678901234568e19 }这个id已经彻底失真了。解决方案主要有两种第一种是使用json.Decoder配合UseNumber()方法把数字解析成json.Number类型而不是float64func main() { data : []byte({id: 12345678901234567890}) dec : json.NewDecoder(bytes.NewReader(data)) dec.UseNumber() var m map[string]interface{} dec.Decode(m) fmt.Printf(%v\n, m[id]) // 输出: 12345678901234567890 }第二种是直接把结构体里的字段定义为int64、uint64或json.Number这样解析时就能保持完整精度。但如果接口的 JSON 结构不确定只能用map[string]interface{}或者interface{}接收时UseNumber()几乎是必选项。我还见过另一种变体前端传一个订单号或者手机号过来后端如果用int64接收没问题但如果在结构体里定义了float64或者用interface{}接收再序列化原本的字符串很可能被解析成数字再次序列化时引号都没了数字的精度也没了。这种问题极其隐蔽因为它不会报错只会在数据流的下游突然冒出错误的结果。排查时要特别留意数字的“流转路径”设计字段类型时尽量显式、具体。3.2 时间字段的格式控制Go 里时间字段默认序列化成RFC3339格式比如2025-04-01T15:04:0508:00。这个格式的好处是标准、有国际化支持坏处是很多国内业务和后端系统习惯用2006-01-02 15:04:05这种形式前端拿到时间后如果直接用 JS 的Date解析容易出问题。如果你希望时间输出成习惯的格式就需要自定义类型或者实现MarshalJSON/UnmarshalJSON方法。最简单的做法是在结构体里用string字段接收然后在业务层转换。但如果项目里有大量地方都要处理时间我更推荐定义一个自定义时间类型type Time time.Time func (t Time) MarshalJSON() ([]byte, error) { return []byte(fmt.Sprintf(%s, time.Time(t).Format(2006-01-02 15:04:05))), nil } func (t *Time) UnmarshalJSON(data []byte) error { s : strings.Trim(string(data), ) v, err : time.Parse(2006-01-02 15:04:05, s) if err ! nil { return err } *t Time(v) return nil }这样在结构体里把字段声明成Time类型就能自动控制序列化格式。注意UnmarshalJSON接收到的 data 是 JSON 里的原始字节流字符串自带引号所以要先Trim掉引号再解析。这一点在写自定义解析时很容易漏。3.3 动态字段json.RawMessage 的妙用对接第三方 API 或者接收前端动态表单时JSON 结构经常不完全确定。有些字段可能不存在有些字段的类型在不同场景下会变化。这时候如果强行定义一个 struct每次解析都要报错或者丢字段。json.RawMessage可以解决一类很实际的问题延迟解析。它本质上是一个[]byte别名在反序列化时不会真正展开内容而是把原始 JSON 片段原样保存下来。等到你需要用的时候再按具体的结构去解析。type Response struct { Code int json:code Data json.RawMessage json:data } func handle(data []byte) error { var resp Response if err : json.Unmarshal(data, resp); err ! nil { return err } // 不确定 data 的内部结构先判断再解析 var obj map[string]interface{} if err : json.Unmarshal(resp.Data, obj); err ! nil { return err } // 或者是解析成确定的结构体 var user User if err : json.Unmarshal(resp.Data, user); err ! nil { return err } }这种做法在接收 Webhook 回调、处理事件消息时特别好用。比如一个消息体里既有业务数据也有元数据元数据处理不了也不影响业务数据的解析。即便其中一个字段的格式变了也不会导致整个Unmarshal失败你完全可以在后续按需处理。需要注意的一点是json.RawMessage在序列化时会把原始字节流原样输出不会额外转义。这既是优点也是隐患如果你往RawMessage里塞的东西本身不是合法 JSON序列化的结果也会是不合法 JSON。所以在往RawMessage里写内容时务必确认它是有效的 JSON 片段。4. 自定义解析当标准库不够用的时候4.1 实现 MarshalJSON / UnmarshalJSON 的完整流程有些特殊场景标准库的默认行为无法满足需求最典型的包括字段需要加密或脱敏序列化时输出掩码反序列化时还原。接口返回的字段格式比较怪比如数字被写成了字符串。需要兼容前端传过来的多种格式。这些情况下自定义MarshalJSON/UnmarshalJSON是最灵活的解决方案。以脱敏为例type Phone string func (p Phone) MarshalJSON() ([]byte, error) { s : string(p) if len(s) 11 { s s[:3] **** s[7:] } return []byte(fmt.Sprintf(%q, s)), nil }写入 JSON 时手机号就变成了138****1234而存储时还是完整的字符串。反序列化时因为字段类型是自定义的Phone底层是string默认解析行为不受影响所以也不需要额外实现UnmarshalJSON。如果你要实现UnmarshalJSON有一点特别重要方法接收的是原始 JSON 字节流你需要先用一个 alias 类型做一次标准解析避免递归调用死循环。比如func (p *Phone) UnmarshalJSON(data []byte) error { var s string if err : json.Unmarshal(data, s); err ! nil { return err } *p Phone(s) return nil }如果你在UnmarshalJSON里直接对p调json.Unmarshal(data, p)会因为类型匹配再次进入当前方法形成无限递归直到栈溢出。正确做法是定义一个新的 alias 类型让它的类型和方法区分开type PhoneAlias Phone func (p *Phone) UnmarshalJSON(data []byte) error { var pa PhoneAlias if err : json.Unmarshal(data, pa); err ! nil { return err } *p Phone(pa) return nil }这算是自定义反序列化初学者的第一道鬼门关很多新手在这里卡很久其实就是没搞明白“方法调用”和“类型方法集”的关系。4.2 自定义解析的典型应用场景除了脱敏我接触得比较多的自定义解析场景还有两种。第一种是兼容接口的脏数据。比如有个老接口正常情况返回count: 5但某天量特别大的时候偶发返回count: 。如果你把字段定义为int解析直接报错定义为string正常的数字又会被当成字符串处理。自定义类型就能两全type FlexibleInt int func (f *FlexibleInt) UnmarshalJSON(data []byte) error { s : strings.Trim(string(data), ) if s || s null { *f 0 return nil } v, err : strconv.Atoi(s) if err ! nil { return err } *f FlexibleInt(v) return nil }第二种是重新定义字段类型。比如前端传一个坐标字符串39.9042,116.4074你希望直接映射成结构体里的Latitude和Longitude两个字段。直接在结构体里搞不定得在自定义类型的UnmarshalJSON里用strings.Split把字符串拆开再赋值给两个字段。虽然这类做法适用范围窄但在写数据清洗、ETL 类服务时能省掉一大部分手动处理逻辑。5. 性能优化与流式处理5.1 Encoder/Decoder 处理大 JSON大多数例子都在用json.Marshal/json.Unmarshal这两个函数对数据是整体进出内存的。数据量小还好如果 JSON 有几十 MB 甚至上百 MB一次json.Unmarshal会分配大量临时结构体内存占用瞬间飙高GC 压力也跟着上来了。流式处理的思路是使用json.Decoder和json.Encoder。Decoder可以从io.Reader按 Token 或者按值分块读取Encoder可以向io.Writer流式写入两者配合可以做到边读边处理不必把整个数据帧一次性载入内存。举个例子处理一个大文件里几千行 JSONfunc processLargeFile(r io.Reader) error { dec : json.NewDecoder(r) for dec.More() { var item Order if err : dec.Decode(item); err ! nil { return err } // 处理每一条订单 processOrder(item) } return nil }注意这里的dec.More()是配合“JSON 数组流”使用的。如果你的数据是一个[]Order数组用Decode循环逐条解析能有效避免一次性解析整个数组。但如果你不知道数据具体是对象还是数组可以先用一次Decode到一个json.RawMessage再决定后续怎么解析。Encoder的输出默认会带一个换行符这在某些写文件或传输场景下是友好的但如果你拼接多个 JSON 再整体返回给前端可能要多做一次 trim。这个细节在对接测试时容易忽略。5.2 减少内存分配与复用对象Go 的 JSON 序列化和反序列化性能问题核心基本都集中在反射和内存分配上。标准库每次Marshal会检查字段的 nested 层级在运行时反射字段 tag同时也免不了产生临时对象。如果你的服务对 QPS 敏感或者请求体很大标准库在高并发下确实会成为瓶颈。有几个优化方向可以尝试第一个方向是避免反复Marshal同一个结构。比如从数据库查出来的对象短时间内多次需要输出 JSON可以先序列化一次然后复制字节切片。在 Go 里拷贝一个切片的成本远远低于重新反射解析一次。第二个方向是使用sync.Pool复用缓冲区。在循环场景里频繁Marshal每次都创建一个[]byteGC 压力不小。可以自己维护一个缓冲池var bufPool sync.Pool{ New: func() any { return bytes.NewBuffer(nil) }, } func marshalWithPool(v any) ([]byte, error) { buf : bufPool.Get().(*bytes.Buffer) defer bufPool.Put(buf) buf.Reset() if err : json.NewEncoder(buf).Encode(v); err ! nil { return nil, err } return bytes.TrimSuffix(buf.Bytes(), []byte(\n)), nil }这样在高频序列化场景下能明显减少内存分配次数。需要注意缓冲池里的对象被取用后要Reset否则上一次的数据会污染本次输出。第三个方向如果你的性能要求极其苛刻可以考虑使用第三方生成代码的库比如easyjson。它的原理是编译期根据结构体生成专门的序列化代码完全绕过反射速度能比标准库快好几倍。缺点是项目需要额外步骤生成代码结构体改动后要重新生成。个人观点是项目初期不必上这个等确实压测到瓶颈、确认标准库的 JSON 处理确实拖慢了整体性能再针对性地做这个优化更实际。6. 常见错误与排查速查表6.1 高频错误信息解读实际开发中遇到过的 JSON 报错信息就那几种这里整理成一份速查表方便排查时对照错误信息触发场景解决思路unexpected end of JSON input解析了一个空的 JSON 字符串比如或 EOF先判断输入是否为空或者用valid校验cannot unmarshal string into Go value of type intJSON 里是字符串结构体字段是数字类型改字段类型为string或自定义UnmarshalJSONcannot unmarshal object into Go value of type stringJSON 里是对象结构体字段是字符串检查接口的返回结构是否和预期一致invalid character x looking for beginning of value字节流前面有 BOM 或者多余字符先bytes.TrimSpace或处理 BOMjson: unsupported type: map[interface{}]interface{}对一个包含interface{}键的 map 做序列化避免使用map[interface{}]interface{}改成map[string]interface{}这里特别展开说一下unexpected end of JSON input。很多人一看到这个错误就以为 JSON 格式不对但实际上它经常出现在“空字符串”或“纯空白”输入的场景。比如从数据库读出一个空字符串直接传给json.Unmarshal就会报这个错。排查思路是确认数据源不为空或者解析前加一层len(data) 0的判断。6.2 排查思路和经验方法JSON 相关的问题排查难度最高的往往不是报错本身而是数据内容在隐式转换后“没有报错但结果不对”。举例来说我在对接一个内部系统时接口返回的字段orderId在文档里是数字但某些极端情况下会返回超大整数。结构体里定义成int64其实没问题但有个同事为了省事直接用map[string]interface{}接收然后把这个 map 序列化后塞给下流系统。结果就是订单号从小数变成了科学计数法下流系统怎么比对都对不上。这类问题不报错需要你顺着数据流做字段级排查。经验方法有三条第一条尽量少用map[string]interface{}接收数据。在明确知道结构的情况下用具体的 struct。不确定的字段用json.RawMessage兜底这样既能保证可解析性也能在出问题时定位到具体字段。第二条反序列化后做一次数据校验。不要假设解析成功就等于数据正确。关键字段是否为空、数字范围是否符合预期、时间格式是否正常在入口处统一校验一遍省去下游排查的大量精力。第三条给接口层的数据结构写单元测试。尤其是时间格式、数字精度、特殊字符转义这三类用例一旦测过后续重构或者数据结构变动时能快速发现问题。7. 最后的实操心得做个总结的话Go 的 JSON 处理虽然入门门槛低但想要用得稳、用得高效还是有不少值得打磨的细节。我自己的体会是设计和数据结构时尽量把类型定准确不要图省事全用interface{}否则问题会沿着调用链越传越远。结构体 tag 定清晰别混用大小写和不同命名风格团队协作时能少掉很多 battle。遇到不确定的字段字段结构优先用json.RawMessage兜底别着急定死结构。在实际项目里我见过太多因为 JSON 精度丢失导致的对账问题、因为时间格式不一致导致的前后端扯皮、因为omitempty误用导致的字段丢失。这些问题大多数都可以靠类型设计和显式解析来避免。如果你刚开始接触 Go建议从最简单的结构体映射开始慢慢把 tag 规则、类型边界、自定义解析这些点一个个吃透。只要每一个环节都清楚明白Go 的 JSON 处理能从“能跑”变成“稳得很”。