Go encoding/json 怎样区分缺失字段和显式 null在批处理代码中减少额外分配

在 Go 的 encoding/json 中，要同时区分字段缺失、显式 null 和正常数值，可以使用包含 Present、Null、Value 的值类型字段，并为它实现 UnmarshalJSON。每条请求先从零值结构开始，字段没有出现时 Present 保持 false；出现 null 时记录 Null；出现整数时保存 Value。普通的 *int 字段在新对象中会把缺失和 null 都表现为 nil，无法直接表达这三种意图。

官方地址：https://pkg.go.dev/encoding/json

先定义缺失、null 与数值的接口含义

以更新查询上限的接口为例：不传 limit 表示保留原设置，传 null 表示清除自定义设置，传 0 表示明确设为零。零是否允许还要由业务规则决定，不能因为它等于 Go 零值就当成没有传。

这里定义的是本文接口契约，不是 JSON 自动赋予 null 的业务含义。旧接口若曾把 null 当成不更新，改成清除会改变调用方行为，应先沟通或通过独立接口逐步采用。

使用值字段记录是否出现

下面示例将 Patch.Limit 定义为 OptionalInt 值字段，而不是 *OptionalInt。这样 null 会交给字段的自定义解码方法处理。非 null 输入再按 int 解码，字符串、数组等不匹配类型返回错误。

package main

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

type OptionalInt struct {
    Present bool
    Null    bool
    Value   int
}

// UnmarshalJSON 只为实际出现的字段调用，成功后一次写入状态。
func (o *OptionalInt) UnmarshalJSON(data []byte) error {
    if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
        *o = OptionalInt{Present: true, Null: true}
        return nil
    }
    var value int
    if err := json.Unmarshal(data, &value); err != nil {
        return err
    }
    *o = OptionalInt{Present: true, Value: value}
    return nil
}

type Patch struct {
    Limit OptionalInt `json:"limit"`
}

// DecodePatch 每份输入使用独立零值，错误时不返回已解析的一部分。
func DecodePatch(data []byte) (Patch, error) {
    data = bytes.TrimSpace(data)
    if len(data) == 0 || data[0] != '{' {
        return Patch{}, fmt.Errorf("请求必须是 JSON 对象")
    }
    var patch Patch
    if err := json.Unmarshal(data, &patch); err != nil {
        return Patch{}, fmt.Errorf("解析更新参数: %w", err)
    }
    return patch, nil
}

func main() {
    inputs := []string{
        `{}`,
        `{"limit":null}`,
        `{"limit":0}`,
        `{"limit":18}`,
        `{"limit":"18"}`,
    }
    for _, input := range inputs {
        patch, err := DecodePatch([]byte(input))
        if err != nil {
            // 单条失败不应用更新；批次可按业务要求继续或终止。
            fmt.Println("拒绝:", err)
            continue
        }
        field := patch.Limit
        switch {
        case !field.Present:
            fmt.Println("保持原设置")
        case field.Null:
            fmt.Println("清除设置")
        default:
            fmt.Println("更新为:", field.Value)
        }
    }
}

按代码逻辑，前四条分别进入保持、清除、更新为零和更新为十八的分支，第五条被拒绝。它们是语义推导的预期，不是实际执行日志。OptionalInt 只在整个字段成功后赋值；失败不会把 Present 改成成功状态。

Present 与 Null 必须按顺序解释：先看 Present，只有字段出现后才需要看 Null；只有出现且非 null 时才读取 Value。这样 Value 为零不会误导业务分支，Null 为 true 时的 Value 也没有业务意义。

解码失败时不要应用部分结果

解码器遇到类型不匹配可能已经处理了别的字段。DecodePatch 因此在局部变量里构造结果，只在成功时返回；错误时返回 Patch 零值，并要求调用者停止应用这一条更新。不能捕获 error 后仍用目标结构里“看起来已经填好”的部分字段更新数据库。

本文还要求顶层必须为对象，拒绝 null、数组和空输入。起始字符判断只表达对象类型要求，不代替 JSON 解析；对象中的语法错误、尾随多余内容仍由 Unmarshal 返回错误。要对 limit 设置上下限，应在解码成功后、应用更新前完成。

批处理避免残留状态与重复解析

批次里最容易出现的错误是反复向同一个 Patch 解码：上一条包含 limit，下一条不包含时，旧 Present 状态可能仍留着。字段缺失不会通过自定义方法来替你执行重置。本文每次调用 DecodePatch 都有一个新的局部零值，不依赖调用者记住清空动作。

不要为了“减少分配”跳过重置；把小结构体赋为零值与清理堆对象也不是同一概念。本例没有为每个字段专门创建指针对象，也没有先把整份文档解成 map 再查字段，但字符串到字节的转换、反射解码和自定义方法中的解析仍有成本，不能据此承诺零分配或比其他方案一定更快。

若要做性能选择，应把相同三态语义、错误处理与同样大小的输入作为前提，比较总时间、每次字节数和分配次数。map[string]json.RawMessage 也能表达键是否存在，适合动态字段；固定接口可以选择本文这种显式结构。不要用只区分两态的指针方案充当等价性能基线。

真正需要复用复杂对象时，先规定每条输入前如何重置，以及失败后是否丢弃全部结果。并发批次应为每条记录提供独立目标对象，不共享一个可变 OptionalInt。

兼容边界与相关问题

omitempty 能解决缺失识别吗？它主要控制编码时的字段省略，不会在解码时自动产生 Present。本文仅实现输入解码；如果还要输出相同三态协议，应另行设计编码对象，不能直接序列化内部三个标记当成原始字段。

字段重复出现会怎样？本例没有拒绝重复对象键，采用 encoding/json 默认处理。需要禁止重复键的协议，应选用能明确报告重复键的解析策略，不要把三态包装误认为完整的输入规范检查。

未知字段是否报错？本例沿用 Unmarshal 默认忽略未知字段的行为。严格协议可改用 Decoder 的相应选项，并同时处理文档结尾；这属于额外接口策略。

能否直接换成 encoding/json/v2？本文固定使用 encoding/json 的行为，切换包或选项需要单独确认自定义方法、null 与字段匹配语义，不作无条件兼容承诺。

先让三种输入意图在类型中可见，再讨论对象复用与性能，才能避免把缺失字段意外执行成一次清除或更新。