Go 结构化日志库怎么选：标准库 slog、zap 与 zerolog 的取舍

项目里的日志从零散文本 fmt.Println 改成 JSON 格式后，真正的难点不是把普通文本换成键值对，而是选一套团队能长期稳定维护的方案。Go 标准库自带的 log/slog、Uber 开源的 zap 和轻量日志库 zerolog 都支持结构化日志输出，但三者在迁移成本、扩展能力、默认使用体验和运行开销上各有不同的侧重。

先梳理项目现有约束，不要直接盯着性能排行榜选

日志库选型通常出现在两个阶段：新服务刚搭基础脚手架，或者旧服务已经有大量历史日志调用，想补全结构化查询字段。前一种场景可以从 API 设计和依赖数量出发做选择；后一种场景首先要核算迁移成本，换库本身不该变成一次影响面很大的风险改造。

表里的“优先考虑”不是强制规则。比如一个老系统已经把 zap.Logger 的调用逻辑写到了 handler、service 和 repository 各层，为了追求所谓的标准库统一替换全部调用点，最后付出的回归成本可能远高于收益。

log/slog：新项目的默认选型起点

log/slog 的优势不是功能最多，而是它把结构化日志的核心接口直接放进了标准库。应用侧可以用 slog.NewJSONHandler 输出 JSON 格式日志，用 slog.NewTextHandler 保留本地开发时可读性更高的文本格式；日志调用方只需要围绕 Info、Warn、Error 和属性参数组织日志内容。

package main

import (
    "log/slog"
    "os"
)

func main() {
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    })
    logger := slog.New(handler).With("service", "order-api")
    logger.Info("order accepted", "order_id", 1024, "region", "cn-east")
}

它也很适合落地公共日志约定：把服务名、环境名和请求标识通过 With 提前绑定，业务相关的动态字段留在具体日志点位单独补充。这样日志平台收到的字段结构很稳定，检索的时候不用猜某个服务里的订单号字段是写成了 id 还是 order。

需要注意的是，slog 只是日志接口和处理器的组合，不会自动帮你完成日志规范设计。错误字段怎么存放、敏感字段怎么过滤、采样逻辑谁来实现，这些仍然需要团队在项目里提前约定好。标准库只是降低了基础依赖成本，不会自动替你做完所有工程决策。

zap 与 zerolog：更强的自定义能力，对应更鲜明的使用风格

zap 更像一套支持自由组装的日志管线。它的核心 Logger、SugaredLogger 和 Core 组件，让团队可以在编码便捷性、字段类型丰富度和输出策略之间做平衡。已经在用 zap 的项目通常早就把编码器、输出 sink、采样和日志轮转逻辑配置完成，这种情况下继续沿用它，比换成另一套 API 要稳妥得多。

logger, err := zap.NewProduction()
if err != nil {
    panic(err)
}
defer logger.Sync()

logger.Info("order accepted",
    zap.Int64("order_id", 1024),
    zap.String("region", "cn-east"),
)

zerolog 的写法要更紧凑，日志事件对象在调用链末尾统一提交：

log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
log.Info().
    Int64("order_id", 1024).
    Str("region", "cn-east").
    Msg("order accepted")

这种链式 API 对字段定义清晰的服务非常友好，但团队需要适配它独有的调用习惯。如果公共业务包直接暴露 zerolog.Event 或 zap.Field 类型，后续想更换日志实现就会牵连很多上层包；公共边界更适合传递错误、请求标识和少量领域字段，再由应用层转换生成具体的日志对象。

性能测试怎么落地：先固定日志内容，再看分配和吞吐表现

网上不同日志库的基准测试结果很容易失真。有的测试关闭了日志输出只统计调用开销，有的只测 JSON 编码环节，有的把文件写入和轮转的开销也算进去，得到的结果自然不能直接横向对比。更实用的测试方案是固定同一组测试字段、同一个输出目标和同一个日志级别，再分别统计每次调用的内存分配次数、吞吐量和尾延迟。

func BenchmarkOrderLog(b *testing.B) {
    logger := newTestLogger(io.Discard)
    b.ReportAllocs()
    for i := 0; i 

测试场景还要覆盖两类真实使用分支：线上最常见的 Info 级别日志，以及 Error 日志附带错误对象和少量上下文的场景。如果系统开启了日志采样，也要把采样规则固定下来。只测空日志或者只测内存缓冲场景，最后得到的结论大概率只适配基准测试程序本身。

日志迁移流程：先统一字段规范，再替换日志调用入口

从旧的非结构化日志迁移到结构化日志，最容易踩的坑是边改日志库 API 边重命名字段，最后很难定位到底是日志库本身的变化，还是字段命名的变化影响了告警规则。更稳妥的落地顺序是先制定一份精简的规范：time、level、service、request_id、error 和业务主键的命名全部固定下来，明确要求敏感数据禁止写入日志。

1. 先在项目入口层初始化 logger，绑定服务名、环境信息和 request_id。
2. 选一个低风险的业务 handler 接入目标日志库，同时保留旧的日志输出做对照。
3. 检查输出的 JSON 内容能不能被日志平台正常解析，尤其要确认错误堆栈和换行内容的处理是否正常。
4. 用相同的线上流量对比日志产出量、CPU 占用、内存分配、告警命中情况和字段查询可用性。
5. 确认配置好回滚开关后，再批量迁移其他的日志调用点。

如果公共库必须兼容多种日志实现，可以定义一套极精简的通用接口：

type Logger interface {
    Info(msg string, args ...any)
    Error(msg string, args ...any)
}

接口不要一开始就把某款日志库的所有能力都照搬过来。等团队确实需要用到结构化属性组、链路追踪注入或者动态日志级别能力的时候，再为适配器补充对应的稳定语义；否则看似做了一层抽象接口，最后只是把具体日志库的复杂度换了个包装名字而已。

三类不适合盲目更换日志库的场景

第一类，问题根源是日志字段命名不统一，不是日志库本身不够快。日志平台里同一个请求标识有三种不同名字的时候，换任何日志库都不会让查询体验变好。

第二类，服务已经深度依赖 zap 的 Core、采样和自定义编码器能力。除非这些现有能力本身需要重构迭代，否则迁移只会引发大面积的回归问题。

第三类，日志的主要成本来自磁盘写入、网络传输或者日志平台采集环节，而非应用侧的日志编码过程。这种情况下更应该优先做日志级别管控、采样规则优化和输出链路限流，之后再讨论换成哪款 logger 更合适。

决策参考：把选型判断收敛成清晰选择

常见问题

新 Go 项目一定要用 slog 吗？

不一定。如果团队已经有成熟的 zap 或 zerolog 配套基础设施，继续沿用现有方案效率更高；没有历史包袱的场景下，slog 的标准库属性通常能节省不少维护成本。

zap 和 zerolog 哪个性能更好？

不能只靠一张通用排行榜下结论。字段数量、日志级别、输出目标、采样规则和错误对象都会影响最终表现，应该用自己项目的真实日志样本和输出链路跑专属基准测试。

应该把 logger 放进 context.Context 里传递吗？

可以在明确约定的边界内携带请求级别的日志上下文信息，但不要把所有业务依赖都塞进 Context 里。更通用的做法是在请求入口创建带 request_id 的 logger，再显式传给需要记录日志的组件。

结构化日志需要把所有错误堆栈都打出来吗？

不需要在每层代码里重复打印堆栈。选一个统一的边界负责记录完整堆栈，其他层补充稳定的错误类型和业务字段即可，同时注意不要把令牌、身份证号和完整请求体这类敏感内容写入日志。

选日志库的时候，先想清楚“团队要长期维护的方案是什么”，再去对比“单次调用快多少”。新项目可以从 slog 起步；已经有 zap 或者 zerolog 存量资产的项目就优先守住迁移收益；不管最终选择哪一款库，字段规范、采样策略和输出链路的稳定性才是日志体系真正好用的核心决定因素。