Go log/slog.Logger 怎样处理可选字段

使用 log/slog.Logger 记录结构化日志时，可选字段不要直接用空字符串、0 或 nil 代替“字段不存在”。更稳妥的做法是先判断字段是否存在，再条件追加 slog.Attr；这样既能省掉无意义的键，也不会把一个真实的零值误删。

官方地址：https://pkg.go.dev/log/slog

一句话规则：缺失字段不追加，存在但为零值的字段照常追加；请求级可选字段用 LogAttrs，稳定上下文才用 With。

先把“可选”拆成三种状态

日志里的可选字段通常来自请求参数、配置对象或数据库查询结果。它至少有三种状态：字段没有提供、字段提供了但值恰好是零值、字段提供了一个明确的 nil。如果只看最终值，三种状态很容易被压成一个空字符串或数字零。

因此，判断依据应来自 ok、指针是否为 nil 或输入结构的字段掩码，而不是来自值本身。slog.String("name", "") 仍然是一个存在的属性，不会自动变成“省略 name”。

可选字段的判断：缺失不等于零值

如果一个整数的零值和“未提供”含义不同，就给它保留一个存在性标记。下面的辅助函数把“是否追加”与“追加什么”放在一起，调用方不用到处复制判断。

package main

import "log/slog"

// appendOptionalInt 只在字段确实存在时追加属性；0 仍然是有效值。
func appendOptionalInt(attrs []slog.Attr, key string, value int, ok bool) []slog.Attr {
	if !ok {
		// ok=false 表示字段缺失，而不是 value 的零值。
		return attrs
	}
	return append(attrs, slog.Int(key, value))
}

这个约定适合解析查询参数、配置补丁或部分更新请求。调用方传入 value=0, ok=true 时，日志会保留 page_size=0；传入 value=0, ok=false 时，日志完全没有这个键。

用 LogAttrs 组装请求级字段

Logger.LogAttrs 接受一组已经构造好的 slog.Attr，适合在一条日志需要根据请求内容动态增减字段时使用。先准备容量，再按存在性追加，最后一次输出，字段顺序和边界都比较清楚。

package main

import (
	"context"
	"log/slog"
	"os"
)

type RequestInfo struct {
	RequestID string
	UserID    int
	HasUserID bool
	TraceID   *string
}

func logRequest(logger *slog.Logger, req RequestInfo) {
	// 预留常见字段容量，减少动态追加时的扩容。
	attrs := make([]slog.Attr, 0, 3)
	attrs = append(attrs, slog.String("request_id", req.RequestID))
	attrs = appendOptionalInt(attrs, "user_id", req.UserID, req.HasUserID)

	if req.TraceID != nil {
		// 指针非 nil 表示 trace_id 被明确提供，即使内容为空也保留。
		attrs = append(attrs, slog.String("trace_id", *req.TraceID))
	}

	// LogAttrs 只接收 Attr，适合请求级的可选字段集合。
	logger.LogAttrs(context.Background(), slog.LevelInfo, "request finished", attrs...)
}

func appendOptionalInt(attrs []slog.Attr, key string, value int, ok bool) []slog.Attr {
	if !ok {
		// 缺失字段不写入日志，避免把缺失误报成 0。
		return attrs
	}
	return append(attrs, slog.Int(key, value))
}

func main() {
	// TextHandler 便于直接观察字段是否出现；真实服务可替换为 JSONHandler。
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
	traceID := "tr-42"
	logRequest(logger, RequestInfo{RequestID: "req-7", HasUserID: true, TraceID: &traceID})
}

这里没有把 TraceID 的空字符串当成缺失，因为指针的存在性已经表达了调用方的选择。若业务规定空字符串也必须省略，可以在指针非空后再增加一次内容判断，但那是业务规则，不是 slog 的默认行为。

nil 是省略还是 null，要由业务规则决定

slog.Any("parent_id", nil) 表达的是“添加一个值为 nil 的属性”，它不等价于“完全不添加 parent_id”。如果日志消费者依赖字段是否存在做检索或聚合，就必须在构造 Attr 前明确约定。

// appendOptionalText 按业务规则省略 nil 和空字符串。
func appendOptionalText(attrs []slog.Attr, key string, value *string) []slog.Attr {
	if value == nil || *value == "" {
		// 这里选择省略；如果下游需要 null，应改为显式的 slog.Any。
		return attrs
	}
	return append(attrs, slog.String(key, *value))
}

// appendNullableText 保留“字段存在但值为 null”的语义。
func appendNullableText(attrs []slog.Attr, key string, value *string, present bool) []slog.Attr {
	if !present {
		// present=false 表示字段没有提供。
		return attrs
	}
	if value == nil {
		// 下游约定需要 null 时，显式写出 nil，而不是静默省略。
		return append(attrs, slog.Any(key, nil))
	}
	return append(attrs, slog.String(key, *value))
}

这两个函数不能混用：前者适用于只关心“有效文本”的日志，后者适用于要区分“未提供”和“明确置空”的审计或同步场景。结构化日志的价值就在于保留这种可检索的区别。

With 和 LogAttrs 的边界：固定属性与动态属性分层

Logger.With 返回一个带固定属性的 Logger，适合服务名、实例名、版本等在整个生命周期内稳定的字段。请求 ID、用户 ID、可选筛选条件则应在每次调用时通过 LogAttrs 追加。把每次请求的字段都放进 With，会让 Logger 不断创建带新上下文的派生对象，也容易把生命周期边界弄乱。

func handle(logger *slog.Logger, req RequestInfo) {
	// 服务级属性稳定，可以在初始化阶段绑定一次。
	requestLogger := logger.With(slog.String("service", "billing"))

	attrs := make([]slog.Attr, 0, 2)
	attrs = append(attrs, slog.String("request_id", req.RequestID))
	attrs = appendOptionalInt(attrs, "user_id", req.UserID, req.HasUserID)

	// 请求级字段每次按实际存在性构造，不污染共享 logger。
	requestLogger.LogAttrs(context.Background(), slog.LevelInfo, "request accepted", attrs...)
}

官方文档还说明，LogAttrs 是只接受 Attr 的更高效版本。调用方已经在切片里完成条件判断时，使用它比把交替的键和值塞进 Log 更不容易出现参数错位。

嵌套字段要控制空分组和字段数量

可选字段经常按 request、user 或 cache 分组。先收集组内字段，只有组内确实有内容时才追加分组，可以避免输出空对象或空分支。

func appendUserGroup(attrs []slog.Attr, userID int, hasUserID bool, role *string) []slog.Attr {
	userAttrs := make([]slog.Attr, 0, 2)
	userAttrs = appendOptionalInt(userAttrs, "id", userID, hasUserID)
	if role != nil && *role != "" {
		// 只把真实存在的 role 放进 user 分组。
		userAttrs = append(userAttrs, slog.String("role", *role))
	}
	if len(userAttrs) == 0 {
		// 组内没有字段时，整个 user 组也省略。
		return attrs
	}
	return append(attrs, slog.Group("user", userAttrs...))
}

在高并发服务里，日志字段不是越多越好。把同一请求的大对象、完整 Header 或高基数字符串全部放进结构化日志，会增加序列化、传输和索引成本。可选字段的判断应与字段白名单、日志级别和 Handler 的采样策略一起设计。

一张速查表：按字段生命周期选择写法

可以把实现模板记成四步：先保留存在性，再构造属性；先区分固定和动态，再选择 With 或 LogAttrs；最后控制分组、字段白名单和日志级别。

相关问题

空字符串会被 slog 自动忽略吗？

不会。只要调用了 slog.String，这个键值就是存在的。是否忽略空字符串应由你的可选字段规则决定。

零值字段应该全部省略吗？

不应该一概而论。若零值是业务上的有效输入，就必须保留存在性标记并照常记录；只有业务明确把零值定义为缺失时，才可以省略。

为什么动态字段不建议全部用 With？

With 适合稳定上下文；动态字段用 LogAttrs 更能表达每次调用的边界，也便于在同一个 Logger 上复用固定上下文。