Go slog.LogValuer 怎么延迟展开业务对象

要让 slog 延迟展开业务对象，不要在日志调用参数里先构造昂贵字符串或映射，而是传入一个实现 slog.LogValuer 的轻量包装值。日志级别被关闭时，内置 Handler 不会调用它的 LogValue；级别启用时，再由 LogValue 计算派生字段并返回 slog.GroupValue。这既推迟计算，也把脱敏和字段白名单收拢到业务类型旁边。

官方文档：https://pkg.go.dev/log/slog

先划清延迟展开的边界

我第一次把订单对象接入 slog 时，直接在 Debug 参数里调用了一个摘要函数。日志虽然默认只输出 Info 及以上，但摘要函数仍会执行，因为 Go 会先求值函数参数，再进入日志方法。真正要延迟的是“构造日志值”这一步，而不是把已经算好的结果换一种写法传进去。

// 错误示例：Debug 被关闭时，buildOrderSummary 仍会先执行。
logger.Debug("checkout state", "order", buildOrderSummary(order))

// 正确方向：这里只创建轻量包装值，展开逻辑留给 LogValue。
logger.Debug("checkout state", slog.Any("order", orderLogValue{order: order}))

LogValuer 适合延迟字符串拼接、摘要计算和结构化字段组装。它不是通用异步机制，也不会推迟日志方法之外的所有工作：创建包装器时执行的表达式仍会立即求值。

给业务对象加一个专用日志视图

我更倾向于为日志单独定义包装类型，而不是让核心 Order 直接实现 LogValuer。这样业务对象仍能保留完整字段，日志视图则明确决定哪些字段可以出现，也能为不同场景准备不同粒度的视图。

package main

import (
	"log/slog"
	"strings"
)

type Item struct {
	SKU string
}

type Order struct {
	ID            string
	CustomerEmail string
	AmountCents   int64
	Items         []Item
	AccessToken   string // 敏感字段：不进入日志组
}

// orderLogValue 只保存业务对象引用，创建成本很低。
type orderLogValue struct {
	order *Order
}

// customerDomain 是需要时才计算的派生字段。
func customerDomain(email string) string {
	_, domain, ok := strings.Cut(email, "@")
	if !ok {
		return "unknown"
	}
	return domain
}

// LogValue 在日志记录真正被处理时才组装结构化字段。
func (v orderLogValue) LogValue() slog.Value {
	if v.order == nil {
		return slog.StringValue("")
	}

	return slog.GroupValue(
		slog.String("order_id", v.order.ID),
		slog.Int64("amount_cents", v.order.AmountCents),
		slog.Int("item_count", len(v.order.Items)),
		slog.String("customer_domain", customerDomain(v.order.CustomerEmail)),
	)
}

这里使用白名单而不是“先完整序列化再删字段”。AccessToken 从未进入 GroupValue，所以以后即使 Order 增加字段，也不会被反射或 JSON 序列化顺带写进日志。

用 GroupValue 固定输出结构

slog.GroupValue 返回一个由多个 slog.Attr 组成的分组值。把它挂到键名 order 后，JSON Handler 会得到嵌套对象；Text Handler 通常使用带组名前缀的键。业务字段名由 LogValue 固定，不依赖对象的默认格式。

// 调用方只交出便宜的包装值，不提前计算客户域名或摘要。
func logCheckout(logger *slog.Logger, order *Order) {
	logger.Debug(
		"checkout state",
		slog.Any("order", orderLogValue{order: order}),
	)
}

如果 Debug 级别关闭，包装值不会被展开；启用后，内置 Handler 才会解析它。相较于把整个 Order 交给 slog.Any，专用日志视图还带来一个意外收益：日志结构变成稳定接口，不会因为业务结构体新增内部字段而漂移。

把它接入 Logger 的完整用法

下面的示例把 Debug 级别显式打开，并使用 JSON Handler。注释标出了资源和字段边界；示例用于说明调用方式，不把配图当作运行证据。

package main

import (
	"log/slog"
	"os"
)

func main() {
	// 显式允许 Debug，便于观察 LogValue 展开后的分组结构。
	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelDebug,
	})
	logger := slog.New(handler)

	order := &Order{
		ID:            "ORD-2048",
		CustomerEmail: "buyer@example.com",
		AmountCents:   25900,
		Items:         []Item{{SKU: "GO-BOOK"}, {SKU: "MUG"}},
		AccessToken:   "must-not-appear",
	}

	// 只把专用日志视图交给 slog，敏感字段不会进入 GroupValue。
	logger.Debug("checkout state", slog.Any("order", orderLogValue{order: order}))
}

对应的 JSON 结构应包含 order.order_id、amount_cents、item_count 和 customer_domain，但不应包含 AccessToken。如果实际项目使用 Info 级别，把调用和 Handler 的最低级别一起调整，避免把 Debug 用途的详细对象长期写入生产日志。

可变对象和自定义 Handler 的注意点

包装器不是快照。上面的 orderLogValue 保存指针，适合内置同步 Handler 的常见用法。但如果自定义 Handler 把记录送到异步队列后才解析值，业务对象可能已经被修改。需要稳定历史值时，在包装器里复制必要标量，或在入队前完成 Resolve 和记录复制；不要把一个仍在并发修改的对象引用长期留给后台处理。

自定义 Handler 要解析 LogValuer。官方文档建议 Handler 作者使用 Value.Resolve，而不是直接调用一次 LogValue。原因是 LogValue 返回的 Value 还可能继续实现 LogValuer，Resolve 会处理这种链式情况，并限制递归问题。

func handleAttr(a slog.Attr) slog.Attr {
	// Resolve 会展开连续的 LogValuer，并处理异常递归边界。
	a.Value = a.Value.Resolve()
	return a
}

LogValue 保持无副作用。不要在里面扣库存、写数据库或改变对象状态。Handler 何时、以何种方式解析值属于日志实现细节；把它当成纯粹的日志表示函数，更容易测试和复用。

常见误区

• 先调用昂贵函数再塞进包装器：昂贵函数已经发生，延迟失效。包装器应保存便宜参数或对象引用。
• 直接记录整个业务结构体：字段会随结构体演化，敏感信息也更容易被意外带出。优先返回字段白名单。
• 把 LogValuer 当缓存：LogValue 的职责是生成日志表示，不保证只调用一次；需要缓存时应另设受控机制。
• 忽略 nil：包装器持有指针时应显式返回可读的 nil 值，避免在日志路径触发 panic。
• 异步 Handler 留住可变指针：应复制必要字段，或在同步边界内解析为稳定 Value。

实现速查表

相关问题

LogValuer 和 fmt.Stringer 有什么区别？

fmt.Stringer 只提供字符串表示；LogValuer 返回 slog.Value，可以保留分组和字段类型，更适合结构化日志、脱敏和延迟字段组装。

什么时候直接检查 logger.Enabled 更合适？

如果日志调用前还有大量与多个字段相关的准备工作，或需要提前决定是否收集上下文数据，先用 logger.Enabled(ctx, level) 短路会更直观。单个对象的日志表示和字段控制则更适合封装进 LogValuer。

LogValue 返回错误会怎样？

LogValue 没有 error 返回值。无法计算时应返回稳定、可识别的 slog.Value，例如固定字符串或包含状态字段的组，避免在日志路径中 panic。