go-logr/logr 深入解析:Go 结构化日志最小 API 的设计、用法与 slog 互操作实践

原创2026-10-11 17:18:311,932 阅读
文章标签:CLI开发工具云原生容器编排DevOps

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" 两节):

  1. Dave 主张放弃日志 API 而改用 fmt.Printf()。logr 不同意,尤其是在输出位置、时间戳、文件行号装饰、结构化日志等需求存在的前提下。logr 把日志 API 收窄为仅两种:info 和 error。
  2. 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

把上述知识落到工程实践,可以总结为四条可操作建议:

  1. 只在入口选择实现:在 main() 附近创建 root logger(用 logimpl.New(...) 或本仓库可见的 stdr.New(log.New(os.Stderr, "", log.LstdFlags|log.Lshortfile)) 模式),其余包一律只声明 logr.Logger 字段或参数,按值传递。
  2. 消息恒定、数据进键值对:消息永远写常量描述;变量一律进键值对;键保持常量、小写/lowerCamelCase,避开 caller、error、level、logger、msg、stacktrace、ts 这些实现方惯用键(logr.go)。
  3. 按需使用 V 级别:以 0/1/10 为锚点建立团队的 V 级别习惯;错误永远走 Error(err, msg, ...),它不受 verbosity 影响。
  4. 测试时替换后端:测试里用 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 级别的数值语义和键值对约定,你就能在自己的项目里写出"后端随时可换、日志可查询、可交叉引用"的结构化日志代码。

登录后查看全文
cli