第77课 - 结构化日志：Zap

课程： Go 并发编程 模块： 常用库 难度： Intermediate 标签： zap, log, structured, sugar

1. 学习目标

完成本课学习后，你将能够：

理解结构化日志的概念及其相比传统文本日志的优势。
使用 Zap 库进行基本的日志记录。
掌握 SugaredLogger 的便捷语法。
配置不同的日志级别和输出格式（如 JSON）。
了解 Zap 在高并发场景下的高性能特性。

2. 核心概念

什么是结构化日志？

传统的日志通常是一段连贯的文本，例如 "User 12345 logged in from 192.168.1.1"。这种格式对人类阅读友好，但程序难以自动解析和查询。

结构化日志 则像一张表格，每条日志都是一个带有固定字段（键值对）的记录。例如，上面的日志会被记录为：

{
  "level": "info",
  "timestamp": "2023-10-27T10:00:00Z",
  "message": "User logged in",
  "user_id": 12345,
  "ip": "192.168.1.1"
}

这使得日志聚合系统（如 ELK Stack, Splunk）能够轻松地对 user_id、ip 等字段进行索引、搜索和分析。

为什么选择 Zap？

Go 标准库的 log 包功能简单，且性能一般。Zap 是 Uber 开源的高性能结构化日志库，其主要优点：

极高性能：通过内存分配优化和零分配设计，在高并发场景下吞吐量远超标准库。
结构化：天然支持键值对的日志字段。
丰富的功能：支持日志级别、采样、输出到多种目标（文件、标准输出、网络等）、自定义格式。
两种日志器：
- Logger: 需要显式指定键和值，类型安全，性能最好。
- SugaredLogger: 提供了更简洁、类似 fmt.Printf 的语法（w, f, n 后缀），使用更方便。

3. 代码示例

3.1 安装 Zap

go get -u go.uber.org/zap

3.2 基础使用与 SugaredLogger

package main

import (
	"go.uber.org/zap"
)

func main() {
	// 1. 创建一个 Logger（这里使用生产环境配置，输出 JSON 到标准输出）
	// Zap 提供了 Production() 和 Development() 两种预设配置。
	logger, _ := zap.NewProduction()
	// 记得在程序退出前同步缓冲区的日志
	defer logger.Sync()

	// 2. 使用基础的 Logger (性能最高，但语法稍繁琐)
	logger.Info("用户登录成功",
		zap.String("username", "john_doe"), // 键值对
		zap.Int("user_id", 12345),
		zap.String("ip", "192.168.1.100"),
	)

	// 3. 使用 SugaredLogger (更便捷的语法)
	sugar := logger.Sugar()
	// 基础 Info
	sugar.Infow("用户登录成功",
		"username", "john_doe",
		"user_id", 12345,
		"ip", "192.168.1.100",
	)
	// 类似 fmt.Printf
	sugar.Infof("用户 %s (ID: %d) 从 IP %s 登录成功", "john_doe", 12345, "192.168.1.100")

	// 4. 记录错误
	sugar.Errorw("数据库连接失败",
		"error", "connection timeout",
		"db_host", "localhost:5432",
	)
}

运行输出（JSON格式）：

{"level":"info","ts":1698304800.123456,"msg":"用户登录成功","username":"john_doe","user_id":12345,"ip":"192.168.1.100"}
{"level":"info","ts":1698304800.123456,"msg":"用户登录成功","username":"john_doe","user_id":12345,"ip":"192.168.1.100"}
{"level":"info","ts":1698304800.123456,"msg":"用户 john_doe (ID: 12345) 从 IP 192.168.1.100 登录成功"}
{"level":"error","ts":1698304800.123456,"msg":"数据库连接失败","error":"connection timeout","db_host":"localhost:5432"}

3.3 自定义配置与级别

package main

import (
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
)

func main() {
	// 自定义配置
	config := zap.Config{
		Level:       zap.NewAtomicLevelAt(zapcore.DebugLevel), // 设置最低日志级别为 Debug
		Development: true, // 开发模式，会在日志中增加调用栈信息
		Encoding:    "console", // 输出格式： “console”(彩色文本) 或 “json”
		EncoderConfig: zapcore.EncoderConfig{
			MessageKey:  "msg",
			LevelKey:    "level",
			EncodeLevel: zapcore.CapitalLevelEncoder, // 级别大写，如 INFO, ERROR
			TimeKey:     "ts",
			EncodeTime:  zapcore.ISO8601TimeEncoder, // ISO8601 时间格式
			// ... 其他字段配置
		},
		OutputPaths:      []string{"stdout"}, // 输出到标准输出
		ErrorOutputPaths: []string{"stderr"}, // 错误输出到标准错误
	}

	// 根据配置构建 Logger
	logger, _ := config.Build()
	defer logger.Sync()

	// 这条日志会被记录（Debug 级别 >= 配置的 Debug 级别）
	logger.Debug("应用正在启动，读取配置文件...", zap.String("config_path", "/etc/app/config.yaml"))

	// 这条日志不会被记录（Info 级别 > 配置的 Debug 级别是 false，这里 Debug 配置更低）
	// 实际上 Info > Debug，所以会被记录。我们用下面的例子演示级别过滤。
	// 假设我们想跳过更低级别的日志，需要将配置的 Level 设置得更高，例如 Info。
	logger.Info("配置文件读取完成", zap.Int("items", 42))
}

4. 实践练习

练习 1：基础记录

使用 SugaredLogger 编写一个简单的函数，模拟处理订单。该函数接收订单ID和金额作为参数，并记录一条包含这些信息的 Info 级别日志。 预期输出（类似）：

{"level":"info","ts":...,"msg":"开始处理订单","order_id":"ORD-2023-1027","amount":99.9}

练习 2：级别与格式

创建一个配置，将最低日志级别设置为 Warn。
输出格式设置为 json。
同时记录一条 Info 和一条 Warn 的日志，验证只有 Warn 级别的日志被输出。 预期行为： 控制台只出现 Warn 级别的 JSON 日志。

练习 3：集成到服务（进阶）

修改一个简单的 HTTP 服务器（例如之前课程中出现的），为每个传入的请求记录一条结构化日志。日志应包含：

请求方法 (method)
请求路径 (path)
客户端 IP (client_ip)
请求处理耗时 (latency_ms) 提示： 在 Handler 函数开始时记录请求开始，在结束时记录结束和耗时。使用 time.Since 计算耗时。

5. 常见错误

混淆 Logger 和 SugaredLogger：直接使用 Logger.Info("msg", zap.String("k", "v"))，而不是 Sugar.Infow("msg", "k", "v")。Logger 的方法需要显式的 zap.Field，而 SugaredLogger 的 *w 方法接受交替的键值对。
忘记 Sync()：Zap 为了性能会缓冲日志。程序退出前（defer logger.Sync()）必须调用 Sync() 将缓冲区中的日志刷写到目标（如文件、标准输出），否则可能丢失最后几条日志。
不正确的初始化：在包级别（var log *zap.Logger）直接使用 zap.NewProduction()，这可能在程序启动阶段（如 init 函数前）就被调用，导致问题。更好的做法是在 main 函数中初始化并作为全局变量，或通过依赖注入传递。
输出格式配置错误：Encoding 字段拼写错误（如 “json” 写成 “JSON”）会导致配置无效，Zap 可能会回退到默认格式。
在高并发下不安全地复用 SugaredLogger：虽然 Logger 和 SugaredLogger 的实例本身是并发安全的，但如果你从一个 Logger 实例派生出多个 SugaredLogger 并发使用，是没问题的。避免在循环中为每次循环创建新的 Logger 实例，应复用同一个。

6. 小结

结构化日志 以键值对形式记录数据，极大地方便了机器解析、搜索和分析。
Zap 是一个高性能的 Go 结构化日志库，核心优势在于速度、丰富的 API 和灵活的配置。
Logger 提供类型安全和最佳性能；SugaredLogger 提供更便捷的语法，适合快速开发。
务必在程序退出前调用 logger.Sync() 以刷新日志缓冲区。
通过 zap.Config 可以精细控制日志级别、输出格式（console/json）和目标。
在并发程序中，合理使用 Zap 能够提供清晰、可追踪的运行时日志，是生产环境项目的标配。

掌握 Zap，将为你构建健壮、可观测的 Go 应用打下坚实的基础。下一课，我们将学习如何使用 go-playground/validator 来验证数据。

结构化日志：Zap