Go JSON null 解码到指针后怎样区分缺省

在 Go 里把 JSON 字段解码到 *T，字段缺省和显式 null 都很容易表现成 nil，所以不能仅靠指针判断“没有传”还是“明确清空”。如果接口只关心一个字段，可以先解码到 map[string]json.RawMessage；如果这个语义会在多个请求中复用，更适合使用带状态的 Optional[T] 包装。

结论：*T 只能表达“当前有没有值”，不能表达“字段有没有出现”。要区分缺省、null 和具体值，至少需要额外保存一个字段存在标记。

为什么 *T 无法区分缺省和 null

encoding/json 对指针字段的规则很直接：JSON 值是 null 时把指针设为 nil，JSON 是具体值时再分配或填充指向对象。对于结构体中没有出现在 JSON 对象里的字段，解码器不会触碰它，因此零值指针也仍然是 nil。

package main

import (
	"encoding/json"
	"fmt"
)

type Patch struct {
	// 指针只能表示当前有没有一个 int 值，不能记录字段是否出现。
	Limit *int `json:"limit"`
}

func main() {
	var missing, explicitNull Patch
	_ = json.Unmarshal([]byte(`{}`), &missing)
	_ = json.Unmarshal([]byte(`{"limit":null}`), &explicitNull)

	// 两个输入都会让 Limit 为 nil，信息已经在普通解码后合并。
	fmt.Println(missing.Limit == nil, explicitNull.Limit == nil)
}

因此，若业务含义是“缺省时保留旧值，null 时清空旧值，数字时更新为数字”，普通 *int 会丢掉一个关键分支。

只处理一个字段时，用 RawMessage 判断是否出现

一次性处理补丁请求时，可以先把对象解码成 map[string]json.RawMessage。map 的第二个返回值表示键是否存在，原始字节再用 bytes.Equal 判断是不是 JSON null。

package main

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

func readLimit(data []byte) (present, isNull bool, value int, err error) {
	var fields map[string]json.RawMessage
	if err = json.Unmarshal(data, &fields); err != nil {
		return false, false, 0, err
	}

	// map 的 ok 区分字段缺省；RawMessage 保留 null 这个字面量。
	raw, ok := fields["limit"]
	if !ok {
		return false, false, 0, nil
	}
	if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
		return true, true, 0, nil
	}

	// 只有字段存在且不是 null 时，才把原始值解码成 int。
	if err = json.Unmarshal(raw, &value); err != nil {
		return true, false, 0, err
	}
	return true, false, value, nil
}

func main() {
	for _, input := range []string{`{}`, `{"limit":null}`, `{"limit":20}`} {
		present, isNull, value, err := readLimit([]byte(input))
		fmt.Println(input, present, isNull, value, err)
	}
}

这种方式的优点是改动小，特别适合只有一两个可选字段的接口。缺点是每个调用点都要重复判断，字段一多就容易出现默认值和错误处理不一致。

用 Optional 保存三种字段状态

可复用的做法是让字段类型自己记录状态。自定义 UnmarshalJSON 只会在字段实际出现在 JSON 对象中时被调用，所以缺省字段保持 Set=false；显式 null 会进入方法并设置 Null=true。

package main

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

type Optional[T any] struct {
	Value T
	Set   bool // 字段是否出现在 JSON 对象中。
	Null  bool // 字段出现后，值是否明确为 JSON null。
}

func (o *Optional[T]) UnmarshalJSON(data []byte) error {
	o.Set = true
	if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
		// null 不应沿用上一次的 Value，先恢复 T 的零值。
		var zero T
		o.Value = zero
		o.Null = true
		return nil
	}

	// 非 null 值交给标准库继续解码，错误原样返回给调用方。
	o.Null = false
	return json.Unmarshal(data, &o.Value)
}

type Patch struct {
	// 缺省、null 和整数分别对应三种可判断状态。
	Limit Optional[int] `json:"limit"`
}

func main() {
	for _, input := range []string{`{}`, `{"limit":null}`, `{"limit":20}`} {
		var patch Patch
		if err := json.Unmarshal([]byte(input), &patch); err != nil {
			fmt.Println("decode error:", err)
			continue
		}
		fmt.Printf("%s => set=%v null=%v value=%d\n", input, patch.Limit.Set, patch.Limit.Null, patch.Limit.Value)
	}
}

三种状态可以按下面的业务规则处理：

默认值和回写时要守住的边界

默认值应该只在 Set == false 时填入。例如配置读取可以把缺省的 limit 变成 100，但显式 null 仍然要保留为“清空”的业务信号。不要直接写成 if patch.Limit.Value == 0，因为 0 可能是用户明确传入的合法值。

如果把请求对象再次编码成 JSON，还要单独决定三种状态如何回写。Optional[T] 默认会被当作普通结构体编码，不能自动得到“缺省字段不输出、null 输出 null、具体值输出数字”的完整 PATCH 语义。需要回写时，应为包装类型设计对应的 MarshalJSON 或在更外层组装 map[string]any，并明确哪些字段允许出现在响应中。

另外，字段名必须使用和协议一致的 JSON tag；未知字段是否报错属于另一个策略问题，不要拿它代替字段存在性判断。本文的范围只覆盖字段缺省、显式 null 和具体值的区分。

相关问题

指针字段传入 null 会报错吗？

对普通指针字段，JSON null 会把指针设为 nil，通常不会因为这个值本身产生类型错误；真正需要注意的是它与字段缺省在结果上相同。

为什么不直接用零值判断？

零值可能是有效输入，例如整数 0、布尔值 false 或空字符串。零值判断不能可靠表达字段有没有出现。

只需要判断 null 时还要 Optional 吗？

如果不关心缺省与 null 的区别，普通指针即可；如果只在一个入口判断字段是否存在，RawMessage 更轻；多个结构共享这套语义时，再使用 Optional 更合适。