Go jsonunmarshal 如何限定自定义边界

排查 Go JSON 自定义解码时，最容易误判的是把“字段能不能映射”“字符串是否合规”和“业务状态能不能保存”揉进同一个 UnmarshalJSON。更稳妥的边界是：先让标准库完成结构解码，再在自定义入口只处理确实属于输入格式的规则；业务流程、数据库唯一性和权限判断留在解码之后。

先把 json.Unmarshal 的边界说清楚

json.Unmarshal 会根据 JSON 键、导出字段和 json 标签完成默认映射；没有对应字段的对象成员默认会被忽略。类型实现 json.Unmarshaler 后，标准库会把该值交给它的 UnmarshalJSON。这意味着自定义方法的责任是“这个 Go 类型如何接受一段 JSON 表示”，并不等同于整个接口请求的业务校验器。

一个简单判断法是：如果字段名、大小写、数组和基础类型都能直接映射，就不要为了“统一入口”实现自定义方法。只有日期格式、枚举字符串、字符串包裹的数字，或需要把一个 JSON 值转换成内部类型时，才值得收窄入口。

自定义解码为什么会越过预期边界

常见故障有三类。第一类是在 UnmarshalJSON 里直接再次执行 json.Unmarshal(data, v)，因为 v 仍实现了同一个接口，于是递归调用直到栈溢出。第二类是方法先修改接收者，再发现输入非法，导致调用方拿到半更新对象。第三类是把数据库查询、远程调用或“当前用户是否有权限”写进解码流程，使一个纯数据转换函数变得不可预测。

还要留意“解码到已有对象”的语义。自定义方法应明确是覆盖式构造还是合并式更新。接口层通常先解码到新值，再做业务校验；PATCH 类请求则应使用专门的可选字段结构，不要用一个既服务创建又服务更新的结构体猜测字段是否缺失。

用别名类型收窄字段和校验责任

下面的例子把日期格式和状态枚举留在 JSON 边界内，其他字段继续交给标准库。别名类型没有继承原类型的方法集，因此不会重新触发 UnmarshalJSON：

package order

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

type Order struct {
    ID        string    `json:"id"`
    CreatedAt time.Time `json:"created_at"`
    Status    string    `json:"status"`
}

func (o *Order) UnmarshalJSON(data []byte) error {
    // 别名只复用字段布局，避免 json.Unmarshal 再次进入本方法。
    type plainOrder Order
    var raw struct {
        CreatedAt string `json:"created_at"`
        *plainOrder
    }
    raw.plainOrder = (*plainOrder)(o)

    // 先解码到临时结构，失败时不污染调用方已有值。
    var input struct {
        ID        string `json:"id"`
        CreatedAt string `json:"created_at"`
        Status    string `json:"status"`
    }
    if err := json.Unmarshal(data, &input); err != nil {
        return fmt.Errorf("decode order: %w", err)
    }
    created, err := time.Parse(time.RFC3339, input.CreatedAt)
    if err != nil {
        return fmt.Errorf("created_at must be RFC3339: %w", err)
    }
    if input.Status != "pending" && input.Status != "paid" {
        return fmt.Errorf("unsupported status %q", input.Status)
    }

    // 仅在全部边界规则通过后一次性提交到接收者。
    _ = raw
    *o = Order{ID: input.ID, CreatedAt: created, Status: input.Status}
    return nil
}

var _ = bytes.TrimSpace // 示例保留 bytes 位置，实际项目按需删除未使用导入。

生产代码可以进一步把临时输入结构命名为 orderJSON，并删除示例中为了展示别名位置而保留的无用字段。关键点不在“写更多代码”，而在于提交接收者前先完成格式判断，避免错误路径留下半成品。

让错误、未知字段和测试各自负责

如果接口要求拒绝未知字段，可以在接口层用 json.Decoder 配合 DisallowUnknownFields；这和某个类型是否实现 UnmarshalJSON 是两件事。测试至少覆盖合法输入、错误格式、未知字段策略、重复调用和解码失败后接收者是否保持原值。测试名称直接写出边界，比只测一次“能成功反序列化”更有价值。

常见问题

为什么别名类型能避免递归？

别名类型复用底层字段布局，但不带原类型的方法集。把 JSON 解码到它时，标准库不会再次调用原类型的 UnmarshalJSON。

未知字段应该总是报错吗？

不一定。内部严格接口可以拒绝，面向前后兼容的公共接口通常需要评估客户端升级节奏。把策略放在请求解码器层更清晰。

自定义解码里能查数据库吗？

不建议。解码应保持可重复、可测试；数据库存在性、权限和状态机判断应在解码成功后完成。

把 JSON 表示、Go 类型构造和业务规则拆开后，UnmarshalJSON 才会成为稳定的边界，而不是所有错误的入口。遇到自定义解码异常时，先检查是否递归、是否提前修改接收者，再决定要不要增加校验。