Go json.MarshalerError.Unwrap 保留底层编码错误的处理方案

自定义 MarshalJSON 返回错误时，json.Marshal 不会只把原始错误字符串抛出来，而是用 *json.MarshalerError 增加类型和调用上下文。处理这类失败的关键，是保留底层错误作为可判断的原因，再用 errors.Is 或 errors.As 做分支。这样日志有上下文，业务代码也不会被一段字符串绑死。

一、让 Marshaler 返回可比较的底层错误

先定义一个哨兵错误，再让自定义类型在不满足编码条件时返回它。示例中的错误只服务于演示：真实项目可以换成字段校验错误、枚举值错误或底层格式化错误。

package main

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

var ErrPayloadField = errors.New("payload field cannot be encoded")

type Payload struct {
    Value string
}

func (p Payload) MarshalJSON() ([]byte, error) {
    // 返回稳定的哨兵错误，调用方才能使用 errors.Is 判断原因。
    if p.Value == "" {
        return nil, ErrPayloadField
    }
    // 正常路径仍交给一个不含自定义方法的别名类型，避免递归调用。
    type plainPayload Payload
    return json.Marshal(plainPayload(p))
}

func main() {
    _, err := json.Marshal(Payload{})
    if err == nil {
        return
    }
    // Is 判断底层原因，忽略 MarshalerError 增加的上下文。
    fmt.Println(errors.Is(err, ErrPayloadField))

    var marshalErr *json.MarshalerError
    // As 提取包装对象，可读取出错的 Go 类型和底层 Err。
    if errors.As(err, &marshalErr) {
        fmt.Println(marshalErr.Type, marshalErr.Err)
    }
}

这里不要直接把 err.Error() 与完整字符串比较。MarshalerError 的文本包含类型信息，适合日志定位，却不适合作为业务协议。

二、先看懂 MarshalerError 与底层 Err 的关系

json.Marshal 调用 Marshaler.MarshalJSON 失败后，返回的错误通常可以按两层理解：外层是 *json.MarshalerError，负责告诉你哪个 Go 类型的 Marshaler 失败；内层是 Err，保存真正的编码原因。Unwrap() 把这层关系接入 Go 的错误链。

三、用 errors.Is 与 errors.As 分工判断

errors.Is 会沿着错误链查找匹配的值，所以它适合把 ErrPayloadField 映射为参数错误。errors.As 则沿链提取目标类型，适合在日志或监控中读取 MarshalerError.Type，定位是哪一种数据结构编码失败。

func classifyJSONError(err error) string {
    // 先判断稳定的底层原因，避免依赖错误字符串。
    if errors.Is(err, ErrPayloadField) {
        return "invalid-payload-field"
    }

    var marshalErr *json.MarshalerError
    // 再提取包装类型，用于日志和指标维度；不要把类型名当公开协议。
    if errors.As(err, &marshalErr) {
        return "marshal-failed:" + marshalErr.Type.String()
    }
    return "json-encode-failed"
}

生产代码可以把 classifyJSONError 的结果转换为统一响应码，同时把原始 err 交给结构化日志。对外返回时不建议透出内部类型名、字段值或底层错误文本。

四、日志、重试与边界处理

编码失败通常不是网络抖动，看到 MarshalerError 不应默认重试。先用 errors.Is 判断是否为输入字段问题；如果是，直接返回可修正的参数错误。若底层错误来自临时依赖，再由更上层的策略决定是否重试，JSON 编码函数本身只负责准确传递链路。

• 日志记录原始 err 和请求关联 ID，便于保留完整上下文。
• 指标按稳定分类计数，不把完整错误字符串作为高基数字段。
• 如果自定义错误还包了一层，用 %w 继续包装，保证 errors.Is 和 errors.As 能穿透。

相关问题

为什么不直接断言 err.(*json.MarshalerError)？

上层可能继续包装错误，直接断言只检查最外层；errors.As 会沿错误链查找，更适合库代码和中间层。

errors.Is 能判断 MarshalerError 吗？

它更适合判断底层哨兵错误；要提取 MarshalerError 的字段，应使用 errors.As。

是否应该比较 err.Error()？

不应该把文本比较当业务契约。错误文本可读性强，但类型和哨兵错误才是更稳定的程序判断入口。