Go Zap 怎样用 ObjectMarshaler 输出结构化对象

如果日志里只有几个固定字段，直接写 zap.String、zap.Int64 很直观；但请求元数据、租户信息或领域对象一旦同时出现在多个日志点，逐个拆字段就容易出现命名不一致。Go Zap 提供的 ObjectMarshaler 可以把一个自定义对象交给编码器，让调用方仍然用结构化字段记录对象。

官方地址：https://pkg.go.dev/go.uber.org/zap

本文只解决一个问题：怎样实现 MarshalLogObject，再用 zap.Object 输出一个嵌套结构。核心关系是：对象负责描述自己的字段，ObjectEncoder 负责把字段交给当前编码器，日志调用方只负责决定对象出现在哪个键下。

先区分散字段和结构化对象

下面两种写法都能记录请求信息，但维护边界不同：

• 散字段：调用点直接写 zap.String("trace_id", ...)、zap.String("route", ...)。
• 对象字段：调用点写 zap.Object("request", meta)，由 meta 统一决定内部字段。

当同一个对象要被多个日志点复用，或者希望查询路径稳定为 request.trace_id、request.route 时，对象字段更容易保持一致。它并不是把对象先转换成 JSON 字符串；zap.Object 仍然把对象交给 Zap 的字段编码过程。

ObjectMarshaler 到 ObjectEncoder 的职责怎么分

实现接口时，方法签名是关键：

package main

import "go.uber.org/zap/zapcore"

// RequestMeta 只暴露适合进入日志的请求元数据。
type RequestMeta struct {
	TraceID string
	Route   string
	UserID  int64
}

// MarshalLogObject 将领域对象映射成稳定的结构化字段。
func (m RequestMeta) MarshalLogObject(enc zapcore.ObjectEncoder) error {
	// 使用类型明确的编码方法，避免把数字先格式化成字符串。
	enc.String("trace_id", m.TraceID)
	enc.String("route", m.Route)
	enc.Int64("user_id", m.UserID)
	return nil
}

ObjectMarshaler 的职责是“描述对象怎样展开”，参数 zapcore.ObjectEncoder 的职责是“接收字段并交给当前编码器”。这里使用 String 和 Int64，是为了保留字段的原始类型；不要为了省事全部调用 fmt.Sprint。

为什么返回 error 仍然有意义

示例中的基础字段编码不会主动失败，因此直接返回 nil。接口保留错误返回，是为了让需要自定义编码的对象可以把失败传回日志字段链路。例如对象内部还有一个自定义子对象时，可以把子对象的编码错误原样返回，而不是悄悄写一条不完整日志。

type SessionMeta struct {
	Request RequestMeta
	Region  string
}

// MarshalLogObject 组合两个字段组，并保留子对象编码错误。
func (m SessionMeta) MarshalLogObject(enc zapcore.ObjectEncoder) error {
	// Object 会继续调用 RequestMeta 的 MarshalLogObject。
	if err := enc.AddObject("request", m.Request); err != nil {
		return err
	}
	enc.String("region", m.Region)
	return nil
}

对于需要严格控制编码方式的生产代码，更推荐把子对象也作为显式的 Zap 对象字段来组织，并根据当前版本的 ObjectEncoder 能力选择合适的编码方法。重点不是把所有字段塞进反射，而是让错误边界清楚：编码失败时调用方能知道对象没有完整落盘。

用 zap.Object 把对象放进日志

实现接口后，调用方不需要手工拼接 JSON：

package main

import (
	"go.uber.org/zap"
)

func main() {
	logger, err := zap.NewProduction()
	if err != nil {
		// 初始化失败时直接结束，避免继续使用空 Logger。
		panic(err)
	}
	defer func() {
		// 退出前刷新缓冲；Sync 的错误按应用策略记录或忽略。
		_ = logger.Sync()
	}()

	meta := RequestMeta{
		TraceID: "tr-20261029-001",
		Route:   "/orders",
		UserID:  42,
	}

	// request 是对象边界，内部字段由 MarshalLogObject 决定。
	logger.Info("request finished", zap.Object("request", meta))
}

这里的 request 是外层键，trace_id、route 和 user_id 是对象内部字段。调用点只关心对象放在哪里，不需要知道对象内部每个字段怎样编码，这正是自定义 Marshaler 能减少重复的地方。

指针接收者和字段边界要提前决定

如果 MarshalLogObject 使用值接收者，值和指针通常都能满足接口；如果使用指针接收者，只有指针类型满足 ObjectMarshaler。因此调用 zap.Object 前，要确认传入的类型确实实现了接口，否则会在编译期暴露问题。

type JobMeta struct {
	Name   string
	Attempt int
}

// 指针接收者适合需要保护内部状态或避免复制较大对象的情况。
func (m *JobMeta) MarshalLogObject(enc zapcore.ObjectEncoder) error {
	if m == nil {
		// nil 对象不应访问字段，返回错误让上层决定如何处理。
		return errors.New("job meta is nil")
	}
	enc.String("name", m.Name)
	enc.Int("attempt", m.Attempt)
	return nil
}

这段示例如果采用，需要补充 errors 和 zapcore 导入。更重要的是语义：日志对象只应包含可公开、可检索且不会泄露凭据的字段。密码、访问令牌、完整身份证明和未经脱敏的请求头都不应因为实现了 Marshaler 就自动写入日志。

一张速查表：什么时候用哪种写法

常见问题

ObjectMarshaler 和先调用 json.Marshal 有什么区别？

前者直接参与 Zap 的结构化字段编码，调用方仍能保留对象边界和字段类型；后者通常会先得到一段 JSON 字节或字符串，容易把对象变成日志里的单个字符串字段，也会把字段选择权移到通用 JSON 序列化规则。

为什么不直接把结构体传给 zap.Any？

zap.Any 适合快速记录，但自定义 ObjectMarshaler 可以明确规定日志键名、字段类型和敏感字段过滤，更适合多个调用点共享的稳定日志契约。

MarshalLogObject 里应该记录所有结构体字段吗？

不应该。日志对象应当是面向排查和检索的公开视图，按字段用途选择内容，并在变更时把键名兼容性当成接口的一部分。

归纳起来，ObjectMarshaler 适合把“如何展开对象”集中在类型自身，zap.Object 适合把这个对象作为一个有边界的结构化字段交给日志器。先定义稳定字段，再决定值接收者或指针接收者，最后在编码方法里显式过滤敏感数据，就能避免每个日志调用点重复拼装对象。