Go 结构化日志 LogValuer 何时延迟求值

在 Go 的 log/slog 中，LogValuer 的关键价值是把昂贵计算从日志调用参数阶段推迟到“这条日志真的需要处理”时。若 handler 通过日志级别拒绝事件，LogValue 不会被调用；事件启用后，handler 才会解析这个值。因此，适合把查询摘要、复杂格式化或脱敏转换放进 LogValue，不要先在调用点把结果算出来。

先记住一句话：slog.Debug("...", "value", compute()) 会先执行 compute()，而 slog.Debug("...", "value", lazyValue{...}) 可以把计算推迟。

先看日志级别：禁用事件不会解析属性

Handler.Enabled 会在较早阶段判断当前级别是否需要输出。返回 false 时，记录不会进入后续处理，放在 LogValue 里的昂贵计算也就没有触发机会。

package main

import (
	"log/slog"
	"os"
)

type lazyValue struct {
	arg int
}

// LogValue 只在 handler 需要解析这个属性时计算昂贵结果。
func (v lazyValue) LogValue() slog.Value {
	// 这里模拟复杂格式化、聚合或摘要生成。
	return slog.IntValue(v.arg * 10)
}

func main() {
	// Info 默认启用；把最低级别设为 Warn 以丢弃 Debug 和 Info。
	h := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelWarn})
	logger := slog.New(h)

	// Debug 被 handler 拒绝，lazyValue.LogValue 不会执行。
	logger.Debug("调试数据", "value", lazyValue{arg: 7})
	// Warn 被接受，handler 才会解析 lazyValue。
	logger.Warn("需要输出", "value", lazyValue{arg: 7})
}

注意，延迟的是 LogValue 内部的工作，不是所有参数表达式。若把 lazyValue{arg: expensiveInput()} 写在调用点，expensiveInput() 仍会立即执行；应让结构体携带已经具备的轻量输入，把昂贵部分放进方法体。

用 LogValuer 包住昂贵计算

LogValuer 只有一个 LogValue() slog.Value 方法。它可以返回普通值，也可以返回一个 Group。迁移旧日志代码时，先找出“只有日志启用才需要”的格式化、聚合或转换，再把这一段移动到方法里。

type requestSummary struct {
	method string
	path   string
}

// LogValue 在日志需要 requestSummary 时再拼装结构化字段。
func (r requestSummary) LogValue() slog.Value {
	// 返回 Group，避免把多个字段拼成一段不可查询的字符串。
	return slog.GroupValue(
		slog.String("method", r.method),
		slog.String("path", r.path),
	)
}

// 传入轻量对象，不在调用点提前生成摘要字符串。
logger.Debug("请求摘要", "request", requestSummary{method: "GET", path: "/health"})

如果只需要一个数字或字符串，返回 slog.IntValue、slog.StringValue 等具体值；如果要保留字段结构，优先用 slog.GroupValue。这样 JSONHandler 仍能输出可检索的字段，而不是把全部内容塞进一个文本字段。

区分启用日志、结构化输出与敏感字段

当日志事件启用后，handler 会处理记录中的属性，并解析其中的 LogValuer。官方文档把 Value.Resolve 作为处理嵌套 LogValuer 的入口；自定义 handler 不应直接假定值已经是最终形态。

type accessToken string

// LogValue 只返回安全表示，避免把原始令牌写进日志。
func (t accessToken) LogValue() slog.Value {
	// 脱敏值仍是结构化 Value，handler 不需要知道原始令牌。
	return slog.StringValue("REDACTED")
}

func logToken(logger *slog.Logger, token accessToken) {
	// 事件启用后会得到 token=REDACTED，而不是原始字符串。
	logger.Info("认证结果", "token", token)
}

这也是 LogValuer 很实用的第二个边界：它不仅能延迟计算，还能固定一个类型的日志表示。密码、令牌、完整请求对象等内容不应依赖每个调用者自觉处理，类型本身可以把可记录形态限制为脱敏值。

迁移时避开三个常见误区

1. 先算完再传入。 computeExpensiveValue(arg) 写在 slog.Debug 参数中时，日志是否启用都挡不住这次计算；传入实现了 LogValuer 的轻量值。
2. 把 Logger.With 当成每次调用的延迟边界。 With 适合复用公共属性，handler 也可能在添加属性时预处理它们。若某个值只服务于低级别日志，仍应先确认级别，再构造或传入延迟值。
3. 在 LogValue 中做副作用。 该方法应返回稳定的日志表示，不要写数据库、修改共享状态或依赖一次调用只发生一次。需要自定义 handler 时，按 Value.Resolve 的语义处理嵌套值。

可以用下面的迁移表快速判断：

常见问题

LogValue 一定只调用一次吗？不要把业务正确性建立在调用次数上。handler 可能通过解析值来完成输出，嵌套 LogValuer 还涉及递归解析；LogValue 应保持无副作用、可重复计算。

为什么传入指针也能减少无用格式化？像 *url.URL 这类值可以让 handler 在真正需要输出时再调用其表示逻辑；如果调用点先写 r.URL.String()，字符串已经提前生成。

什么时候不该用 LogValuer？如果值很小、计算已经发生，或调用方需要立即拿到结果，直接使用 slog.String、slog.Int 等具体 Attr 更简单。LogValuer 的目标是延迟工作和统一日志表示，不是给每个字段增加一层包装。

总结：先把日志级别判断当作第一道边界，再把昂贵计算放进 LogValue；启用后返回结构化值或脱敏值；同时让 LogValue 保持无副作用。这样既避免禁用日志的无用开销，也不会牺牲结构化日志的查询能力。