go-logr/logr 深入解析:Go 结构化日志最小 API 的设计、用法与 slog 互操作实践
go-logr/logr 深入解析:Go 结构化日志最小 API 的设计、用法与 slog 互操作实践
logr 是 Go 生态中最具影响力的结构化日志抽象层之一:它本身不是日志实现,而是一套刻意保持精简的 API,让应用与库代码只依赖 logr.Logger 即可发出结构化日志,真正的输出行为则由"上游"(如 main() 附近)注入的 LogSink 实现接管。本文将结合本仓库(Docker CLI 及其 vendor 依赖)中 vendor/github.com/go-logr/logr 的完整源码,系统讲解 logr 的两层 API 设计、核心方法语义、V 级别与结构化日志的设计哲学、与标准库 log/slog 的双向互操作,以及 funcr、stdr 等参考实现的落地细节,帮助读者理解并写出可替换后端、可测试、可查询的 Go 日志代码。
logr 是什么:一套最小化的日志 API,而非日志实现
logr 在 README.md 的开篇就给出了明确的自我定位:它提供的是"关于 Go 程序和库应当如何做日志的另一种观点",核心诉求是让代码在写日志时不被某个具体日志实现耦合。它不是一个日志库,而是一个 API——准确说是两套面向不同用户的 API:
Logger类型:面向应用和库的作者。它提供一个小巧的 API,可以在任何需要输出日志的地方使用,把真正写日志的动作(写入文件、stdout 或其他目标)延迟委托给LogSink接口。LogSink接口:面向日志库的实现者。它是一个纯接口,由各日志框架实现,用来提供实际的日志功能。
这种解耦带来一个关键工程收益:应用和库的开发者可以完全以 logr.Logger 为基准编写代码(其依赖扇出非常低),而日志实现由调用方"上移"管理(例如在 main() 或其附近完成),应用开发者可以随时按需替换底层实现——从 zap 换到 logrus,从标准库 log 换到 JSON 输出,业务代码一行都不用改。
在 logr.go 的包文档中,这段设计被概括为:
Packages in the Go ecosystem can depend on this package, while callers can implement logging with whatever backend is appropriate.
即:Go 生态中的包依赖 logr,调用方用任意后端实现日志。
快速上手:root logger 的创建、传递与调用
logr 的典型用法遵循"早期决策、全局传递"的模式。在应用生命周期的最开始,代码会决定要使用哪个日志实现,并创建"根" logger:
func main() {
// ... 其他初始化代码 ...
// 创建 "root" logger:logimpl 是选定的具体实现,
// 它接受一些初始参数并返回 logr.Logger。
logger := logimpl.New(param1, param2)
// ... 其他初始化代码 ...
app := createTheAppObject(logger)
app.Run()
}
logr.Logger 对象可以传给其他库、存入结构体字段,甚至按需用作包级全局变量。除了早期这一处设置,其他包完全不需要知道具体实现的选择,它们只用收到的 logr.Logger 写日志:
type appObject struct {
// ... 其他字段 ...
logger logr.Logger
// ... 其他字段 ...
}
func (app *appObject) Run() {
app.logger.Info("starting up", "timestamp", time.Now())
// ... 应用代码 ...
}
注意这里 Info 的第一参数是常量消息("starting up"),附加信息通过键值对("timestamp", time.Now())表达,而不是 printf 风格的格式化字符串。这正是 logr 结构化日志的核心形态,下文会详细展开。
零值安全与 Discard
Logger 是一个具体 struct 而非接口(性能原因,见后文"为什么不是纯接口"一节),且零值 Logger{} 与 Discard() 完全等价,会丢弃所有日志条目。这一点在 logr.go 中有明确说明:按值接收 Logger 的代码可以直接调用其方法,永远不会崩溃;对于"日志可传可不传"的场合,建议使用 *logr.Logger 指针。Discard() 的实现也非常简单——在 discard.go 中,它就是 New(nil):
// Discard returns a Logger that discards all messages logged to it.
func Discard() Logger {
return New(nil)
}
从 logr.go 的 New 实现可以看到,传入 nil sink 时创建的 Logger 会静默丢弃一切日志,且所有由 Discard() 产生的 Logger 实例彼此相等。
核心 API 详解:Info、Error、V、WithValues、WithName
Logger 的方法集非常克制,全部定义在 logr.go 的 Logger struct 上(内部只有 sink LogSink 和 level int 两个字段)。理解每个方法的语义,就掌握了 logr 的全部日常用法。
Info 与 Error:仅有的两种日志类型
logr 刻意把日志收敛为两种:info(想告诉用户、但不是错误的日志)和 error(错误本身)。设计准则是:如果你的代码从一个下级函数调用收到了 error,并且要记录它而不把它返回给上层,就应该使用 error 日志。
标准库 log 的写法:
log.Printf("setting target value %s", targetValue)
log.Printf("failed to open the pod bay door for user %s: %v", user, err)
logr 结构化写法:
logger.Info("setting target", "value", targetValue)
logger.Error(err, "failed to open the pod bay door", "user", user)
从源码看(logr.go):
Info(msg string, keysAndValues ...any)先检查sink.Enabled(l.level),未启用则直接返回;启用时若 sink 实现了CallStackHelperLogSink,还会先调用其 helper 再输出。Error(err error, msg string, keysAndValues ...any)不检查 verbosity,任何级别下都会输出——error 日志没有详细程度概念。err参数是可选的,没有错误实例时传nil是合法的。
两者分开成独立方法,是为了让 LogSink 实现可以在调用 Error() 时附加额外信息(如堆栈跟踪)。
V 级别:数字化的详细程度
在"verbose 模式"下才输出的日志,用 V() 方法标记。V 级别数字越大,日志越不重要;未被启用的 V 级别(由 LogSink 决定)的日志行根本不会写入。V(0) 是默认级别,logger.V(0).Info() 与 logger.Info() 含义相同;负数 V 级别按 0 处理。
传统写法:
if flVerbose >= 2 {
log.Printf("an unusual thing happened")
}
logr 写法:
logger.V(2).Info("an unusual thing happened")
源码中的 V 实现(logr.go)揭示了两个重要细节:
func (l Logger) V(level int) Logger {
if l.sink == nil {
return l
}
if level < 0 {
level = 0
}
l.level += level
return l
}
- V 级别是累加的:
logger.V(2).V(3).Info(...)等价于logger.V(5).Info(...)。 Logger采用按值传递 + 返回新 Logger 的不可变风格,副本之间互不影响。
WithValues:保存的键值对
WithValues(keysAndValues ...any) 返回一个携带额外键值对的新 Logger,这些键值对会伴随该实例的所有后续日志输出。典型场景是按被管理对象粒度创建 Logger(logr.go 包文档中的例子):
// 初始化阶段:把对象标识预存进 logger
obj.logger = mainLogger.WithValues(
"name", obj.name, "namespace", obj.namespace)
// 后续输出时只需关注本次事件本身
obj.logger.Info("setting foo", "value", targetValue)
WithName:Logger 名称段
WithName(name string) 返回带名称的新 Logger,反复调用会累积名称"段",由 LogSink 实现按自己的方式拼接(如 funcr 用空格、slogsink 用 /)。强烈建议名称段只包含简单标识符(字母、数字、连字符),避免空白、逗号、句点、斜杠、括号、引号等会搅乱输出或拼接的字符(logr.go):
logger.WithName("compactor").Info("started", "time", time.Now())
调用栈定位:WithCallDepth 与 WithCallStackHelper
当业务代码与真正的 Logger 方法调用之间隔着 helper 函数时,调用点归属会出错。logr 通过两个可选接口支持修正:
CallDepthLogSink(logr.go):WithCallDepth(depth)按帧数偏移调用栈,成功调用是累加的。CallStackHelperLogSink(logr.go):基于testing.T的"标记 helper"思路,返回一个必须被调用的函数来标记直接调用者为 helper。
Logger.WithCallStackHelper()(logr.go)会同时尝试两者:先对支持 CallDepthLogSink 的实现调用 WithCallDepth(1),再对支持 CallStackHelperLogSink 的实现获取 helper 函数。需要跳一层时优先用它而不是 WithCallDepth(1)。此外,logr 通过 RuntimeInfo{CallDepth: 1}(logr.go)在 New 时把"logr 库自身引入的调用帧数"告知 LogSink,实现方在打印 file/line 时需要额外向上爬这些帧。
设计背景:为什么会有 logr,它与 slog 有何不同
如果 Go 标准库当初就定义了日志接口,可能就没有这个项目了。当 Go 团队在开发 log/slog 时(对应 Go issue 56345),采纳了 logr 的部分设计,但也舍弃和改写了其他部分。README 中给出的完整对比表如下:
| 特性 | logr | slog |
|---|---|---|
| 高层 API | Logger(按值传递) |
Logger(按指针传递) |
| 底层 API | LogSink |
Handler |
| 栈展开 | 由 LogSink 完成 |
由 Logger 完成 |
| 跳过 helper 函数 | WithCallDepth、WithCallStackHelper |
Logger 不支持 |
| 按需生成待记录值 | Marshaler |
LogValuer |
| 日志级别 | >= 0,数值越大表示"越不重要" | 正负数皆有,0 表示 info,越大表示"越重要" |
| 错误日志条目 | 总是记录,无 verbosity 级别 | 普通日志条目,级别 >= LevelError |
| 通过 context 传递 logger | NewContext、FromContext |
无 API |
| 为 logger 添加名称 | WithName |
无 API |
| 在调用链中修改日志详细程度 | V |
无 API |
| 键值对分组 | 不支持 | WithGroup、GroupValue |
| 传 context 以提取附加值 | 无 API | InfoCtx 等 API 变体 |
需要特别说明的是:slog 的高层 API 被明确设计为可叠加在共享 slog.Handler 之上的众多 API 之一,logr 正是这样一种备选 API,并通过转换函数与 slog 互操作(详见后文)。
与 Dave Cheney 观点的异同
logr 的设计深受 Dave Cheney 著名博文《Let's talk about logging》启发,但在两点上明确分歧(README "Inspiration" 与 "Differences from Dave's ideas" 两节):
- Dave 主张放弃日志 API 而改用
fmt.Printf()。logr 不同意,尤其是在输出位置、时间戳、文件行号装饰、结构化日志等需求存在的前提下。logr 把日志 API 收窄为仅两种:info 和 error。 - info 日志引入 verbosity 级别。这给了开发者表达任意"重要梯度"的机会,而无需为级别赋予"warning""trace""debug"这类带语义的名字。由于 verbosity 是数值,可以安全地假设:以更高 verbosity 运行的应用会产出更多(也更不重要)的日志。
为什么结构化日志?为什么 V 级别?——设计问答
README 的 FAQ 部分对这些设计问题给出了直接回答,理解它们有助于在团队中推广 logr 并避免误用。
为什么结构化日志?
- 更容易查询:键值对形态下,可以按特定键过滤查询(如按错误码搜请求日志、按 name/namespace 搜 Kubernetes reconciler 日志);
- 更容易交叉引用:只要维持键的约定,就能汇总与某个概念相关的全部日志行;
- 支持更精细的过滤维度:可以配置只记录某些键、只记录某键匹配某值的行,而不是仅有 v-level 和 name 两个维度;
- 能更好表达结构化数据:元组型对象等天然结构化的数据可以被原样保留。
为什么 V 级别?
V 级别给了运维人员一种简单的方式控制日志的"话痨程度"。某个包可以通过 V 级别区分日志消息的相对重要性;当某个 logger 或包输出太多消息时,使用者只需调整该库的 V 级别即可,无需改代码。
为什么不用 Info/Warning/Error 这样的命名级别?
因为命名级别被赋予了语义含义,而 verbosity 是纯粹的数字:数字天然支持"数值越大,日志越多"的单调假设,且不会把"warning"这种语义强加给实现者。
为什么不允许格式字符串?
格式字符串会抵消结构化日志的大部分好处:不靠模糊搜索/正则就难以检索;内容被拍平进字符串,无法保存结构化数据;无法交叉引用;由于消息不恒定,难以压缩。除非你把位置参数转成带数字键的键值对——那又成了键无意义的键值日志。
为什么是键值对而不是 map?
键值对更容易围绕分配做性能优化。zap(启发 logr 接口的结构化日志库)的性能测试证明了这一点。接口虽然略显不直观,但换来了潜在更好的性能,也让用户不必每次写日志都敲 map[string]string{}。
不同库的 V 级别不一致怎么办?
没关系。按 logger 粒度控制 V 级别,用 WithName 把不同的 logger 传给不同的库。通常仍建议单个 logger 内部的 V 级别保持相对一致,这样更容易决定请求多高 verbosity 的日志。
怎么选择 V 级别?
这几乎是唯一一条硬约束:V 级别越大代表日志越啰嗦、越偏 debug。起步建议:0 表示"你总是想看"的日志,1 表示"常见但可能想关掉"的日志,10 表示"我想对日志收集链路做性能压测"的日志。之后按需从 10 向下(debug/trace 类)、从 1 向上(更啰嗦的 info 类)填充中间值。作为参照,slog 预定义了 -4 表示 debug(对应 logr 的 4),这也与 Kubernetes 社区的推荐一致。
怎么选择键?
键相当自由,几乎可以是任意字符串,但为了与实现和既有项目惯例兼容,建议:可读、常量键、全代码库一致、键自然对应消息中的部分内容、简单键用小写、复杂键用 lowerCamelCase(Kubernetes 即采用此惯例)。键名虽几乎不受限(空格也允许),仍建议只用可打印 ASCII 字符。
为什么键应该是常量?
键是每条日志消息的"schema"。如果同一日志行在不同实例上使用不同键,结构化日志会变得难以使用。Sprintf() 是给值用的,不是给键用的!
我非要用格式字符串怎么办?
先把"错误到底是什么"用一句话(TL;DR 风格)写成消息;再把每个格式占位符前面的词提取为键值对。README 给了两个来自 Kubernetes 代码库的真实转换示例:
// 原:klog.V(4).Infof("Client is returning errors: code %v, error %v", responseCode, err)
// 新:
logger.Error(err, "client returned an error", "code", responseCode)
// 原:klog.V(4).Infof("Got a Retry-After %ds response for attempt %d to %v", seconds, retries, url)
// 新:
logger.V(4).Info("got a retry-after response when requesting url",
"attempt", retries, "after seconds", seconds, "url", url)
如果实在非用不可,就把 fmt.Sprintf 用在某个键的值里,例如 logger.Info("unable to reflect over type", "type", fmt.Sprintf("%T"))。总之这种需求应当极少。
为什么 Logger 不是纯接口?
Logger 被实现为 struct,是为了让 Go 编译器能够优化"高 V 级别且未被触发的 Info 日志"这类场景(例如 l.sink.Enabled(l.level) 为 false 时直接短路返回,不展开键值对参数)。所有真正的工作都在 LogSink 接口后面。这也解释了为什么 logr 官方要求:实现方应提供返回 Logger(而非 LogSink)的构造函数。
实现生态:LogSink 的参考实现与仓库内的真实用例
README 列出了大量非穷举的 LogSink 实现,覆盖了 Go 生态的主流日志方案:
- funcr:一个函数即可实现的桥接层,可桥接到非结构化日志库(本仓库 vendor 中包含,见下);
- testr:基于
testing.T,输出 JSON 风格,用于 Go 测试; - glogr:
github.com/google/glog的实现; - klogr 与 ktesting:面向 Kubernetes 的
k8s.io/klog实现; - zapr:
go.uber.org/zap的实现; - stdr:Go 标准库
log的实现(本仓库 vendor 中包含); - logrusr:
github.com/sirupsen/logrus的实现; - genericr:便于自己实现后端;
- logfmtr:Heroku 风格 logfmt 输出;
- zerologr:
github.com/rs/zerolog的实现; - gokitlogr:
github.com/go-kit/log的实现(v0.12.0 起兼容 go-kit/kit/log); - buflogr:写入
bytes.Buffer,非常适合在测试中验证值确实被记录。
值得注意的是,本仓库就实际消费了 logr:cmd/docker-trust/go.mod 声明了 github.com/go-logr/logr v1.4.4 与 github.com/go-logr/stdr v1.2.2 两个间接依赖;而 OpenTelemetry Go SDK 的 vendor 代码 internal_logging.go 中,全局日志器正是用 stdr.New(log.New(os.Stderr, "", log.LstdFlags|log.Lshortfile)) 构造的默认实现,并定义了 Info(V(4))、Debug(V(8))、Warn(V(1))、Error(Error())四个门面函数——这是"高层代码只依赖 logr、底层实现可替换"理念的绝佳实例。同时 OTel 的 CHANGELOG 也记载了 Jaeger/Zipkin exporter 采用 logr 作为日志接口。
funcr:把日志输出委托给任意函数
funcr 是 logr 官方仓库中最基础的参考实现,完整源码在本仓库 funcr/funcr.go。它提供两种构造函数:
funcr.New(fn func(prefix, args string), opts Options):JSON 风格的key=value输出;funcr.NewJSON(fn func(obj string), opts Options):严格 JSON 输出。
Options 结构体(funcr/funcr.go)控制输出的方方面面,是理解 logr 输出定制能力的窗口:
| 选项 | 作用 |
|---|---|
LogCaller MessageClass |
是否以及为哪类日志行添加 "caller" 键,有开销 |
LogCallerFunc bool |
额外记录调用函数名(需先启用 LogCaller) |
LogTimestamp bool |
是否添加 "ts" 键,有开销 |
TimestampFormat string |
时间戳格式(Go 的 time.Layout 文档),默认 "2006-01-02 15:04:05.000000" |
LogInfoLevel *string |
info 级别所用键名,默认 "level",置空字符串则不记录级别 |
Verbosity int |
允许产出的最大 V 级别 |
RenderBuiltinsHook / RenderValuesHook / RenderArgsHook |
分别对 funcr 内建键值对、WithValues 保存的键值对、Info/Error 直接参数做审计或改写 |
MaxLogDepth int |
嵌套结构(struct/slice/array/map)的最大记录深度,默认 16,超限渲染为 "<max-log-depth-exceeded>" |
funcr 的 Formatter 还可以嵌入到自定义 LogSink 实现中(见 funcr/funcr.go),在自定义 sink 需要实现额外方法时非常有用。它渲染值时尊重 logr.Marshaler、fmt.Stringer 和 error 接口;渲染 struct 时使用 Go 标准 JSON tag(除 "string" 外)。prettyWithFlags(funcr/funcr.go)的处理顺序是:先给 logr.Marshaler 机会完全接管值的日志形态,再处理 fmt.Stringer/error,最后对常见基本类型走无反射的快路径。
stdr:桥接标准库 log
stdr.New(std StdLogger)(stdr.go)返回基于 Go 标准库 log 实现的 Logger,内部直接复用 funcr 的 Formatter;SetVerbosity(v int) 设置全局 verbosity 阈值(非并发安全,须在单个 goroutine 调用)。Options.Depth 可用于修正"调用代码再隔一层才到 stdr"时的栈深度。
与 log/slog 的双向互操作
从 Go 1.21 起,标准库提供了 log/slog,logr 与它之间的转换是双向的:既可以用 logr.Logger API 驱动一个 slog.Handler,也可以用 slog.Logger API 驱动一个 logr.LogSink。FromSlogHandler 与 ToSlogHandler 负责转换(定义在 slogr.go)。
用 logr.LogSink 作为 slog 的后端
理想情况下,一个 logr sink 实现应当同时支持 logr 与 slog:既实现常规 logr 接口,也实现 SlogSink(slogr.go,额外要求 Handle、WithAttrs、WithGroup)。之所以不能在同一类型上同时实现 slog.Handler 和 logr.Sink,是因为两者的 Enabled 方法参数签名冲突(Go issue 59110)。若两者都支持,日志调用可以从高层 API 直达后端而无需转换参数;FromSlogHandler/ToSlogHandler 也能零包装往返转换——唯一的例外是 Logger.V 曾用于调整 verbosity 时,ToSlogHandler 需要包一层来修正后续调用的级别。
如果 sink 不支持 slog,会有这些代价(README 明确列出):
- 源码位置记录仅在经
slog.Logger调用时正确——因为logr.Sink自己做栈展开,而非使用高层 API 提供的程序计数器; - slog 级别
<= 0可以通过取反无损映射到 logr 级别,但所有> 0的级别(如slog.LevelWarning)在调用 sink 前必须映射到 0,因为 logr 不支持"比 info 更重要"的级别; - slog 的 group 概念只能退化为"键前缀 + 点号分隔",而结构化输出(如 JSON)本可以放入嵌套对象;
- 特殊 slog 值与接口无法按预期工作;
- 开销通常更高。
这些缺点足够严重,因此混用 slog 与 logr 的应用应当切换到统一的后端。
用 slog.Handler 作为 logr 的后端
反方向(用纯 slog.Handler 驱动 logr)要顺利得多:
- 所有 logr verbosity 级别可以通过取反 1:1 映射为 slog 级别;
- 栈展开由
SlogSink完成,得到的程序计数器传给slog.Handler(见 slogsink.go:runtime.Callers(3+l.callDepth, pcs[:])采集调用点,slog.NewRecord携带 PC); WithName累积的名称被汇总为一个键为"logger"、值用/分隔的属性;Logger.Error被转成级别为slog.LevelError的记录,若传了 error 则额外附加键为"err"的属性(常量定义见 slogsink.go)。
主要缺点是 logr.Marshaler 不被支持。类型最好同时实现 logr.Marshaler 与 slog.Valuer;如果不需要与不支持 slog 的 logr 实现兼容,则只实现 slog.Valuer 就够了。
ToSlogHandler 的级别换算(sloghandler.go)可以这样理解:
logrV0 := getMyLogger()
logrV2 := logrV0.V(2)
slogV2 := slog.New(logr.ToSlogHandler(logrV2))
slogV2.Debug("msg") // ≈ logrV2.V(4) ≈ logrV0.V(6)
slogV2.Info("msg") // ≈ logrV2.V(0) ≈ logrV0.V(2)
slogV2.Warn("msg") // ≈ logrV2.V(-4) ≈ logrV0.V(0),负值被钳制为 0
context 支持:在两种 API 间共享日志器
slog 不支持把 logger 存进 context.Context,logr 通过 context_slog.go 补齐了这个缺口:
NewContext(ctx, logger)/FromContext(ctx):存储/取出logr.Logger值;NewContextWithSlogLogger(ctx, slogLogger)/FromContextAsSlogLogger(ctx):存储/取出*slog.Logger,两者共用同一个 context 键(contextKey,见 context.go);FromContextOrDiscard(ctx):找不到时返回丢弃一切日志的 Logger;- 双向自动转换:
NewContextWithSlogLogger之后再FromContext,后者会自动把slog.Logger转成logr.Logger;FromContextAsSlogLogger对反方向做同样的事。
之所以存 *slog.Logger 指针而非 slog.Handler,是为了在取出时避免 slog.Logger 的分配(context_slog.go);代价是来回切换需要更多分配。由于 logr 已被大量包(尤其是 Kubernetes)使用,README 建议在做上下文日志(contextual logging)的代码中使用 logr.Logger API。
注意这些 context API 有 //go:build go1.21 构建约束(context_slog.go 与 context_noslog.go):Go 1.21 以下版本只提供 NewContext/FromContext/FromContextOrDiscard 的纯 logr 版本,且 Go < 1.21 时 context 中永远只存 Logger 值(见 context.go 的注释)。
自定义扩展:"Break Glass" 模式
logr 允许实现方给调用者访问底层日志实现的途径,推荐模式是在 logr.go 的包文档中定义的 Underlier 接口:
// Underlier exposes access to the underlying logging implementation.
type Underlier interface {
GetUnderlying() <underlying-type>
}
由于调用者手里只有 logr.Logger,必须先知道当前用的什么实现,因此这个接口与其说是抽象,不如说是类型转换的测试手段:
func DoSomethingWithImpl(log logr.Logger) {
if underlier, ok := log.GetSink().(impl.Underlier); ok {
implLogger := underlier.GetUnderlying()
// ...
}
}
自定义 With* 扩展可以通过"复制整个 Logger struct 并替换其中的 sink"来实现(logr.go):
func WithFoobar(log logr.Logger, foobar int) logr.Logger {
if foobarLogSink, ok := log.GetSink().(FoobarSink); ok {
log = log.WithSink(foobarLogSink.WithFooBar(foobar))
}
return log
}
两点重要提醒(包文档中明确警告):不要用从既有 Logger 取出的 LogSink 去 New 一个新 Logger(源码位置归属可能出错,且 Logger 的未导出字段会丢失);同一 LogSink 实例可能被多个 Logger 共享,调用会修改 LogSink 状态的方法会影响所有共享者。
实战建议:在项目中落地 logr
把上述知识落到工程实践,可以总结为四条可操作建议:
- 只在入口选择实现:在
main()附近创建 root logger(用logimpl.New(...)或本仓库可见的stdr.New(log.New(os.Stderr, "", log.LstdFlags|log.Lshortfile))模式),其余包一律只声明logr.Logger字段或参数,按值传递。 - 消息恒定、数据进键值对:消息永远写常量描述;变量一律进键值对;键保持常量、小写/lowerCamelCase,避开
caller、error、level、logger、msg、stacktrace、ts这些实现方惯用键(logr.go)。 - 按需使用 V 级别:以 0/1/10 为锚点建立团队的 V 级别习惯;错误永远走
Error(err, msg, ...),它不受 verbosity 影响。 - 测试时替换后端:测试里用 buflogr 或 testr 这类后端验证"值确实被记录",生产环境随时可整体切换到 zap/zerolog/JSON 输出,业务代码零改动。对
Marshaler(logr.go),需要精细控制"复杂类型记录哪些字段 / 记录未导出字段 / 避免被String()方法拍平"时,实现MarshalLog() any即可。
小结
logr 的价值不在功能多,而在边界克制:它只规定"日志长什么样、分几种、如何标记详细程度",把"怎么写出去"完全交给可替换的 LogSink。围绕它生长出的 funcr、stdr、zapr、klogr 等实现,以及针对 Go 1.21+ log/slog 的双向互操作与 context 传递能力,使它成为 Go 生态(尤其是 Kubernetes 及依赖 OTel 的工具链,如本仓库的 Docker CLI 与 docker-trust)中兼具解耦力与实用性的日志抽象层。理解了 Logger 与 LogSink 的分工、V 级别的数值语义和键值对约定,你就能在自己的项目里写出"后端随时可换、日志可查询、可交叉引用"的结构化日志代码。