JSON包新提案：用“omitzero”解决编码中的空值困局

本文永久链接 – https://tonybai.com/2024/09/12/solve-the-empty-value-dilemma-in-json-encoding-with-omitzero

Go标准库是Go号称“开箱即用”的重要因素，而标准库中的encoding/json包又是标准库最常用的Go包。虽然其性能不是最好的，但好在由Go团队维护，对JSON规范兼容性好，且质量很高。但json包也不是没有“瑕疵”的，Go官方继math/rand/v2之后，也开启了encoding/json/v2的讨论，v2包含了对功能的增强，其中就包含了对空值编码的改进的考量，以及性能方面的优化。但json/v2毕竟还属于“长远”规划，当前版本的json包的问题也要修正和完善。

一个提出于2021年的issue近期被即将“功成身退”的Russ Cox 接受(accept)，该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也被重新“唤醒”，针对该提案，目前社区在active discussions。

随着后续encoding/json/v2的到来，我们可以期待Go语言在数据序列化领域会有更出色的表现。这不仅将提升json编解码效率，还将为构建更加健壮和灵活的基于json的Go应用程序铺平了道路。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：