Go標準庫是Go號稱“開箱即用”的重要因素，而標準庫中的encoding/json包又是標準庫最常用的Go包。雖然其性能不是最好的，但好在由Go團隊維護，對JSON規范兼容性好，且質量很高。但json包也不是沒有“瑕疵”的，Go官方繼math/rand/v2^[1]之后，也開啟了encoding/json/v2的討論^[2]，v2包含了對功能的增強，其中就包含了對空值編碼的改進的考量，以及性能方面的優化。但json/v2畢竟還屬于“長遠”規劃，當前版本的json包的問題也要修正和完善。

一個提出于2021年的issue^[3]近期被即將“功成身退”的Russ Cox^[4]，該issue就當前json包對空值編碼的“瑕疵”做了描述并提出了修正方案。本文就將針對這一問題以及其方案進行探討，希望能幫助大家更好地理解該issue以及其對應的方案。

1. 問題溯源：omitempty的局限性

在encoding/json包中，omitempty標簽是開發者控制JSON序列化行為的重要工具。它的設計初衷是允許開發者指定：當某個字段值為“空”時，在JSON編碼過程中應該被忽略。然而，omitempty的空值定義存在一些固有的局限性。下面是json包中對omitempty的說明：

The "omitempty" option specifies that the field should be omitted from the encoding if the field has an empty value, defined as false, 0, a nil pointer, a nil interface value, and any empty array, slice, map, or string.

總結一下，omitempty標簽的判斷邏輯如下：

• 對于布爾類型：false被視為空
• 對于數值類型：0被視為空
• 對于字符串：""（空字符串）被視為空
• 對于指針、接口：nil被視為空
• 對于數組、切片、map：長度為0被視為空

下面是一個完整的Go示例，展示了omitempty標簽在不同類型上的應用：

package main

import (
 "encoding/json"
 "fmt"
)

type Example struct {
 BoolField      bool           `json:"bool_field,omitempty"`
 IntField       int            `json:"int_field,omitempty"`
 StringField    string         `json:"string_field,omitempty"`
 PointerField   *string        `json:"pointer_field,omitempty"`
 InterfaceField interface{}    `json:"interface_field,omitempty"`
 ArrayField     [0]int         `json:"array_field,omitempty"` // 空數組
 SliceField     []string       `json:"slice_field,omitempty"` // 空切片
 MapField       map[string]int `json:"map_field,omitempty"`   // 空地圖
}

func main() {
 var nilString *string = nil

 example := Example{
  BoolField:      false,            // 布爾類型
  IntField:       0,                // 數值類型
  StringField:    "",               // 空字符串
  PointerField:   nilString,        // nil 指針
  InterfaceField: nil,              // nil 接口
  ArrayField:     [0]int{},         // 空數組
  SliceField:     []string{},       // 空切片
  MapField:       map[string]int{}, // 空地圖
 }

 jsonData, err := json.Marshal(example)
 if err != nil {
  fmt.Println("Error marshalling example:", err)
 }
 fmt.Println(string(jsonData)) // 輸出：{}
}

然而，這種預定義的"空"值判斷邏輯并不能滿足所有實際場景的需求。讓我們來看幾個具體的例子：

• 空結構體問題

package main

import (
 "encoding/json"
 "fmt"
)

type Config struct {
 EmptyStruct struct{} `json:",omitempty"`
}

func main() {
 cfg := Config{}
 data, _ := json.Marshal(cfg)
 fmt.Println(string(data)) // 輸出：{"EmptyStruct":{}}
}

我們看到：在這個例子中，盡管Config中的EmptyStruct字段是一個空結構體類型，且添加了omitempty標簽，但它仍然出現在JSON輸出中。

• 零值結構體

除了空結構體，零值結構體也是目前omitempty標簽語義覆蓋不到的類型：

package main

import (
 "encoding/json"
 "fmt"
)

type ZeroStruct struct {
 A int
 B string
 C float64
}

type Config struct {
 ZeroStruct ZeroStruct `json:",omitempty"`
}

func main() {
 cfg := Config{}
 data, _ := json.Marshal(cfg)
 fmt.Println(string(data)) // 輸出：{"ZeroStruct":{"A":0,"B":"","C":0}}
}

我們看到：即便ZeroStruct中各個類型的值都為零，且有了omitempty標簽，json.Marshal依然輸出了Config中的ZeroStruct字段。

• time.Time類型的處理

在開發實踐中，我們發現json對time.Time類型在omitempty下的處理也與“常理”不符，比如下面這個示例：

package main

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

type Event struct {
 Time time.Time `json:",omitempty"`
}

func main() {
 evt := Event{Time: time.Time{}} // 零值時間
 data, _ := json.Marshal(evt)
 fmt.Println(string(data)) // 輸出：{"Time":"0001-01-01T00:00:00Z"}
}

我們看到：time.Time類型的零值依然被輸出了。并且輸出的是公元1年1月1日UTC時間。對于很多應用來說，這個時間并不具有實際意義，更合理的零值是"January 01, 1970 00:00:00 UTC"。

很顯然，Gopher們希望json包能更好的處理上述情形。

2. 社區討論與omitzero標簽方案的確認

關于上述問題的解決方法，在Go社區引發了廣泛討論。不過大家普遍認為不要改變現有omitempty語義，那樣會導致破壞性的change，無法向后兼容。

在討論過程中，社區成員提出了一些其他的解決方案：

• 允許MarshalJSON()方法返回nil來完全忽略某個字段

這個方案的優點是利用了已有的接口，不需要引入新的標簽。但缺點是需要為每個支持零值的類型都實現MarshalJSON()方法。

• 添加OmitJSONField方法

這個方案提議為每個類型添加一個OmitJSONField() bool方法，由開發者自己控制字段的忽略邏輯，該方案提供了很大的靈活性，但可能會導致JSON序列化邏輯過于分散。

最終，"omitzero"方案最終被認為是一個相對平衡的解決方案，因為它可以與現有的標簽系統兼容，開發者可以很容易地將omitempty替換為omitzero，或者在需要的地方同時使用兩者。此外，omitzero也保持了簡潔性，相比其他需要大量代碼修改的方案，omitzero只需要添加標簽或實現一個方法(可選項)即可。

"omitzero"標簽提案的核心內容是：在序列化時，"omitzero"選項指定如果字段值為零，則該結構體字段應被省略。如果該類型定義了IsZero bool方法，那么這個零值就通過IsZero方法來判斷；否則是根據字段是否是零值（通過reflect.Value.IsZero判斷）來判斷。該omitzero選項在反序列化(unmarshal)時沒有效果。如果同時指定了"omitempty"和"omitzero"，則字段是否被省略基于兩者的邏輯或關系。 這將意味著，在省略切片時，omitzero會省略空指針切片，但對于長度為零的非空切片，則不會。對于time.Time類型，會省略time.Time{}。

此外，omitzero不強制你實現IsZero方法，但開發者可以利用IsZero方法來自由控制自定義類型在omitzero標簽下是否會被省略。

一旦有了omitzero，我們就可以用它解決上面提到的問題（omitzero尚未實現，下面是偽代碼）：

• 解決空結構體問題

type Config struct {
    EmptyStruct struct{} `json:",omitzero"`
}

cfg := Config{}
data, _ := json.Marshal(cfg)
fmt.Println(string(data)) // 輸出：{}

• 更好地處理time.Time類型

type Event struct {
    Time time.Time `json:",omitzero"`
}

evt := Event{Time: time.Time{}} // 零值時間
data, _ := json.Marshal(evt)
fmt.Println(string(data)) // 輸出：{}

• 自定義類型的"零值"判斷

type CustomInt int

func (ci CustomInt) IsZero() bool {
    return ci <= 0 // 自定義零值判斷邏輯
}

type Data struct {
    Value CustomInt `json:",omitzero"`
}

d := Data{Value: CustomInt(-1)}
data, _ := json.Marshal(d)
fmt.Println(string(data)) // 輸出：{}

3. 小結

通過引入"omitzero"標簽，Go語言在解決JSON編碼中"空"值處理的痛點上邁出了重要一步。這個方案不僅滿足了開發者對更靈活的"空"值定義的需求，還保持了與現有系統的兼容性。目前該omitzero的落地時間尚未確定，最早也要等到Go 1.24版本。此外，encoding/xml等也會效仿json包，增加omitzero標簽。

此外，伴隨著omitzero提案被接受，另外一個在2021年由Josh Bleecher Snyder提出的相關提案：proposal: cmd/vet: warn about structs marked json omitempty^[5]也被重新“喚醒”，針對該提案，目前社區在active discussions。

隨著后續encoding/json/v2的到來，我們可以期待Go語言在數據序列化領域會有更出色的表現。這不僅將提升json編解碼效率，還將為構建更加健壯和靈活的基于json的Go應用程序鋪平了道路。