1. Zap

zap 是 uber 开源的一个高性能，结构化，分级记录的日志记录包。

Zap特性

• 高性能：zap 对日志输出进行了多项优化以提高它的性能

• 日志分级：有 Debug，Info，Warn，Error，DPanic，Panic，Fatal 等

• 日志记录结构化：日志内容记录是结构化的，比如 json 格式输出

• 自定义格式：用户可以自定义输出的日志格式

• 自定义公共字段：用户可以自定义公共字段，大家输出的日志内容就共同拥有了这些字段

• 调试：可以打印文件名、函数名、行号、日志时间等，便于调试程序

• 自定义调用栈级别：可以根据日志级别输出它的调用栈信息

• Namespace：日志命名空间。定义命名空间后，所有日志内容就在这个命名空间下。命名空间相当于一个文件夹

• 支持 hook 操作

1 快速开始

zap 安装：

go get -u go.uber.org/zap

zap 提供了 2 种日志记录器：SugaredLogger 和 Logger。

在需要性能但不是很重要的情况下，使用 SugaredLogger 较合适。它比其它结构化日志包快 4-10 倍，包括 结构化日志和 printf 风格的 API。看下面使用 SugaredLogger 例子：

logger, _ := zap.NewProduction() 
defer logger.Sync() // zap底层有缓冲。在任何情况下执行 defer logger.Sync() 是一个很好的习惯 
sugar := logger.Sugar() 
sugar.Infow("failed to fetch URL",  
    // 字段是松散类型，不是强类型   
    "url", url,   
    "attempt", 3,   
    "backoff", 
    time.Second, 
    ) 
sugar.Infof("Failed to fetch URL: %s", url)

当性能和类型安全很重要时，请使用 Logger。它比 SugaredLogger 更快，分配的资源更少，但它只支持结构化日志和强类型字段。

logger, _ := zap.NewProduction() 
defer logger.Sync() 
logger.Info("failed to fetch URL",   
    // 字段是强类型，不是松散类型   
    zap.String("url", url),   
    zap.Int("attempt", 3),   
    zap.Duration("backoff", time.Second), 
    )

2 子包说明

Zap日志库除了Zap包之外还有其他搭配的包。

包名	适用阶段	典型场景
zapcore	核心开发	自定义编码器、输出目标、日志级别
zapgrpc	服务开发	集成 gRPC 日志到 Zap 系统
zaptest	测试	单元测试中验证日志输出正确性
buffer	性能优化	减少高频日志场景的内存分配开销
benchmarks	性能评估	对比不同配置下的吞吐量/延迟差异
zapio	系统集成	重定向第三方库的 I/O 输出到 Zap 日志
exp	实验性功能	尝试新特性（如新型编码器、传输协议）

3 常量

// 日志级别详解（按严重性递增排序）
const (
    // DebugLevel (调试级) - 细粒度事件记录
    // 适用场景：函数调用跟踪、变量状态检查
    // 典型输出：HTTP请求参数、SQL语句、中间件执行步骤
    // 生产建议：默认关闭，开发环境开启
    DebugLevel = zapcore.DebugLevel

    // InfoLevel (信息级) - 服务运行状态指示
    // 适用场景：服务启动、配置加载、业务关键流程节点
    // 典型输出：用户登录成功、订单创建完成、定时任务执行
    // 生产建议：长期保持开启
    InfoLevel = zapcore.InfoLevel

    // WarnLevel (警告级) - 非预期但可恢复的异常
    // 适用场景：次要功能异常、第三方服务短暂不可用
    // 典型输出：缓存失效、数据库连接重试、低磁盘空间
    // 生产建议：设置告警阈值（如每小时超过10次）
    WarnLevel = zapcore.WarnLevel

    // ErrorLevel (错误级) - 需要立即关注的故障
    // 适用场景：主流程中断、数据一致性风险
    // 典型输出：支付失败、文件写入错误、API限流触发
    // 生产建议：触发即时告警（邮件/短信通知）
    ErrorLevel = zapcore.ErrorLevel

    // DPanicLevel (开发恐慌级) - 开发环境专用断言
    // 特殊行为：开发环境触发panic，生产环境降级为Error
    // 适用场景：不可恢复的程序状态（仅在开发阶段出现）
    // 使用示例：检测到不可能的代码分支
    DPanicLevel = zapcore.DPanicLevel

    // PanicLevel (恐慌级) - 主动终止程序运行
    // 执行动作：记录日志后调用panic()
    // 适用场景：核心组件初始化失败（数据库连接等）
    // 使用注意：优先考虑优雅降级方案
    PanicLevel = zapcore.PanicLevel

    // FatalLevel (致命级) - 紧急终止程序
    // 执行动作：记录日志后调用os.Exit(1)
    // 适用场景：关键资源不可用（配置文件缺失等）
    // 使用警告：慎用！会跳过defer和清理流程
    FatalLevel = zapcore.FatalLevel
)

级别	环境	响应措施	是否包含堆栈	监控要求
Debug	开发/测试	开发者查看日志	否	不监控
Info	生产	日常运营监控	否	统计数量趋势
Warn	生产	创建工单排查	否	设置阈值告警
Error	生产	立即介入处理	是	实时告警
DPanic	开发	中断开发流程	是	本地IDE提示
Panic	生产	服务重启+告警	是	触发事故流程
Fatal	生产	紧急响应+故障复盘	是	最高优先级事件

4 函数

4.1 输出控制类​​

4.1.1 CombineWriteSyncers

func CombineWriteSyncers(writers ...zapcore.WriteSyncer) zapcore.WriteSyncer

作用​​: 合并多个 zapcore.WriteSyncer 对象，生成一个线程安全的组合输出目标。 ​​参数说明​​:

• writers (可变参数): 类型 zapcore.WriteSyncer 的实例，如 os.Stdout、已打开的文件句柄等 ​​返回值​​: 一个合并后的 zapcore.WriteSyncer 对象 ​​示例​​:

file, _ := os.Create("app.log")
ws := zapcore.AddSync(file)  

// 合并控制台和文件输出，并自动加锁保证线程安全 
combined := zap.CombineWriteSyncers(os.Stdout, ws)  

// 使用组合后的 WriteSyncer 建立核心 
Logger core := zapcore.NewCore(     zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),     combined,     zap.InfoLevel, ) logger := zap.New(core)

4.1.2 Open

func Open(paths ...string) (zapcore.WriteSyncer, func(), error)

​作用​​: 通过路径或协议（如文件路径）创建 WriteSyncer，并自动处理资源管理。支持标准输出和错误。 ​​参数说明​​:

• paths: 形如 "stdout"、"/var/log/app.log" 或协议 URL ​​返回值​​:

• 第1个值 zapcore.WriteSyncer: 合并后的输出目标

• 第2个值 func(): 关闭所有已打开文件的回调函数

• 第3个值 error: 可能的错误 ​​示例​​:

// 输出到控制台和文件，并返回清理函数
writer, closeFn, _ := zap.Open("stdout", "/var/log/app.log")
defer closeFn() // 程序退出时关闭文件

logger := zap.New(zapcore.NewCore(
    zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
    writer,
    zap.InfoLevel,
))

4.2 编码器配置类​​

4.2.1 NewDevelopmentEncoderConfig

func NewDevelopmentEncoderConfig() zapcore.EncoderConfig

​​作用​​: 生成预配置的开发环境编码器参数（控制台友好格式）。 ​​默认配置​​:

• 时间格式: ISO8601 (2006-01-02T15:04:05Z07:00)

• 级别编码: 彩色大写字符串（如 INFO 蓝色）

• 显示文件名和行号 ​​返回值​​: zapcore.EncoderConfig 结构体（可修改字段） ​​示例​​:

EncodeLevel:    zapcore.CapitalColorLevelEncoder  // 彩色级别 
EncodeTime:     zapcore.ISO8601TimeEncoder       // 可读时间

4.2.2 NewProductionEncoderConfig

func NewProductionEncoderConfig() zapcore.EncoderConfig

​​作用​​：生成生产环境编码配置（结构化 JSON） ​​预设字段​​：

EncodeLevel:    zapcore.LowercaseLevelEncoder    // 小写级别 
EncodeTime:     zapcore.EpochTimeEncoder         // 时间戳

4.2.3 RegisterEncoder

func RegisterEncoder(name string, constructor func(zapcore.EncoderConfig) (zapcore.Encoder, error)) error

​​作用​​：注册自定义编码器（如 XML/YAML 格式） ​​示例​​：

zap.RegisterEncoder("xml", func(cfg zapcore.EncoderConfig) (zapcore.Encoder, error) {
    return NewXMLEncoder(cfg), nil })

4.3 标准日志集成类​​

4.3.1 NewStdLog

func NewStdLog(l *Logger) *log.Logger

​​作用​​：创建兼容标准库的 log.Logger（固定 Info 级别） ​​集成示例​​：

zapLogger, _ := zap.NewProduction() 
stdLogger := zap.NewStdLog(zapLogger) 
stdLogger.Print("Legacy log message")

4.3.2 RedirectStdLog

func RedirectStdLog(l *Logger) func()

​​作用​​：劫持标准库全局日志到 Zap ​​典型用法​​：

logger, _ := zap.NewProduction() 
restore := zap.RedirectStdLog(logger) 
defer restore()

4.4 全局管理类​​

4.4.1 ReplaceGlobals

func ReplaceGlobals(logger *Logger) func()

​作用​​: 替换全局的 zap.L() 和 zap.S() 实例。 ​​参数​​:

• logger: 新的 *zap.Logger ​​返回值​​: 恢复原始 Logger 的函数

newLogger := zap.NewExample()
restore := zap.ReplaceGlobals(newLogger)
defer restore()

zap.L().Info("Now using the new global logger")

4.4.2 LevelFlag

func LevelFlag(name string, defaultLevel zapcore.Level, usage string) *zapcore.Level

​​作用​​: 创建命令行参数以动态设置日志级别（全局 flag 包）。 ​​参数​​:

• name: 参数名（如 "log-level"）

• defaultLevel: 默认级别（如 zap.InfoLevel）

• usage: 帮助信息 ​​返回值​​: 指向当前级别值的指针 ​​示例​​:

# 启动命令 ./app -log=debug

level := zap.LevelFlag("log", zap.InfoLevel, "Log level (debug, info, warn, error)")
flag.Parse()

logger := zap.New(zapcore.NewCore(
    encoder,
    writer,
    *level, // 动态应用级别
))

4.4.3 RegisterSink 函数定义​​

func RegisterSink(scheme string, factory func(*url.URL) (Sink, error)) error

​​作用​​：注册自定义的日志输出目标（Sink），允许 Zap 将日志发送到用户定义的位置（如远程服务、数据库等）。 ​​版本​​：v1.9.0 及以上。​

​​参数​​	​​类型​​	​​说明​​
scheme	string	协议名称（如 http, kafka），需符合 RFC 3986 标准且未被注册过。
factory	func(*url.URL) (Sink, error)	工厂函数，接收 URL 并返回对应的 Sink 实例。
Zap 会自动为 “file” 方案注册一个Sink。

5 类型

5.1 AtomicLevel 类型

AtomicLevel 是 Zap 提供的一个动态日志级别管理类型，支持 ​​线程安全​​ 的运行时日志级别调整。它允许在不重启服务的情况下修改日志级别，适用于生产环境动态调试需求。

5.1.1 NewAtomicLevel()

​​函数定义​​：

func NewAtomicLevel() AtomicLevel

​​作用​​：创建一个默认级别为 InfoLevel 的 AtomicLevel。 ​​示例​​：

atomicLevel := zap.NewAtomicLevel() // 初始级别为 Info

5.1.2 NewAtomicLevelAt(l zapcore.Level) (v1.3.0+)

​​函数定义​​：

func NewAtomicLevelAt(l zapcore.Level) AtomicLevel

​​作用​​：创建指定初始级别的 AtomicLevel。 ​​参数​​：

• l: 初始日志级别（如 zap.DebugLevel） ​​示例​​：

atomicLevel := zap.NewAtomicLevelAt(zap.DebugLevel) // 初始级别为 Debug

5.1.3 ParseAtomicLevel(text string) (v1.21.0+)

​​函数定义​​：

func ParseAtomicLevel(text string) (AtomicLevel, error)

​​作用​​：从字符串（如 "debug"、"INFO"）解析生成 AtomicLevel。 ​​参数​​：

• text: 日志级别的字符串表示（不区分大小写） ​​返回值​​：AtomicLevel 实例或错误 ​​示例​​：

level, err := zap.ParseAtomicLevel("warn") // level 为 WarnLevel

5.1.4 SetLevel(l zapcore.Level)

​​方法定义​​：

func (lvl AtomicLevel) SetLevel(l zapcore.Level)

​​作用​​：直接设置日志级别。 ​​参数​​：

• l: 目标级别（如 zap.ErrorLevel） ​​示例​​：

atomicLevel.SetLevel(zap.ErrorLevel) // 动态调整为 Error 级别

5.1.5 Level()

​​方法定义​​：

func (lvl AtomicLevel) Level() zapcore.Level

​​作用​​：获取当前启用的最低日志级别。 ​​返回值​​：当前级别（如 zap.InfoLevel） ​​示例​​：

currentLevel := atomicLevel.Level() // 获取当前级别 
fmt.Println(currentLevel)           // 输出: info

5.1.6 Enabled(l zapcore.Level) bool

​​方法定义​​：

func (lvl AtomicLevel) Enabled(l zapcore.Level) bool

​​作用​​：判断指定级别的日志是否会被记录。 ​​参数​​：

• l: 待检查的日志级别 ​​返回值​​：true 表示该级别日志会输出 ​​示例​​：

if atomicLevel.Enabled(zap.DebugLevel) {
    logger.Debug("Debug message is visible") 
}

5.1.7 ServeHTTP(w http.ResponseWriter, r *http.Request)

​​方法定义​​：

func (lvl AtomicLevel) ServeHTTP(w http.ResponseWriter, r *http.Request)

​​作用​​：提供 HTTP 接口，支持通过 RESTful API 动态修改日志级别。 ​​支持的请求类型​​：

• ​​GET​​：获取当前级别（返回 JSON {"level":"info"}）

• ​​PUT​​：修改当前级别（支持 x-www-form-urlencoded 或 JSON）

​​示例代码​​：

func main() {     
    // 创建 AtomicLevel 并绑定到 Logger     
    atomicLevel := zap.NewAtomicLevel()     
    logger := zap.New(zapcore.NewCore(        
        zapcore.NewJSONEncoder(
            zap.NewProductionEncoderConfig()),
            zapcore.Lock(os.Stdout),         
            atomicLevel,     ))      
    
    // 设置 HTTP 路由     
    http.Handle("/log/level", atomicLevel)     
    go http.ListenAndServe(":8080", nil)    
     
    // 业务代码     
    logger.Info("Server started") }

​​通过 HTTP 修改级别​​：

# 使用 curl 设置级别为 Debug 
curl -X PUT http://localhost:8080/log/level -d 'level=debug'

5.1.8 MarshalText() (v1.3.0+)

​​方法定义​​：

func (lvl AtomicLevel) MarshalText() (text []byte, err error)

​​作用​​：将当前级别序列化为文本（如 []byte("debug")）。 ​​示例​​：

data, _ := atomicLevel.MarshalText() // data = []byte("info")

5.1.9 UnmarshalText(text []byte) error

​​方法定义​​：

func (lvl *AtomicLevel) UnmarshalText(text []byte) error

​​作用​​：从文本反序列化设置级别。 ​​参数​​：

• text: 级别字符串的字节形式（如 []byte("warn")） ​​示例​​：

err := atomicLevel.UnmarshalText([]byte("error")) // 设置级别为 Error

​

5.1.10 String() (v1.4.0+)

​​方法定义​​：

func (lvl AtomicLevel) String() string

​​作用​​：返回当前级别的字符串形式（如 "debug"）。 ​​示例​​：

fmt.Println(atomicLevel.String()) // 输出: debug

5.1.11 完整示例

package main

import (
    "net/http"
    "time"
    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

func main() {
    // 1. 创建 AtomicLevel 并初始化 Logger
    atomicLevel := zap.NewAtomicLevelAt(zap.InfoLevel)
    logger := zap.New(zapcore.NewCore(
        zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
        zapcore.Lock(os.Stdout),
        atomicLevel,
    ))
    defer logger.Sync()

    // 2. 启动 HTTP 服务提供级别管理接口
    http.Handle("/log/level", atomicLevel)
    go http.ListenAndServe(":8080", nil)

    // 3. 模拟日志输出
    go func() {
        for {
            logger.Debug("Debug message")   // 初始级别为 Info，不输出
            logger.Info("Info message")    // 正常输出
            time.Sleep(1 * time.Second)
        }
    }()

    // 4. 5秒后动态调整级别为 Debug
    time.Sleep(5 * time.Second)
    atomicLevel.SetLevel(zap.DebugLevel)    // Debug 消息开始输出

    select {}
}

5.2 Logger类型

在Go语言的zap日志库中，Logger类型是核心组件，用于高效、结构化地记录日志。

zap.Logger是一个高性能的结构化日志记录器，用于：

• ​​记录不同级别的日志​​（Debug、Info、Warn、Error等）。

• ​​输出结构化数据​​（如JSON格式），便于日志收集和分析。

• ​​优化性能​​：避免反射和内存分配，适合高并发场景。

5.2.1 New

函数定义​​：

func New(core zapcore.Core, options ...Option) *Logger

​​作用​​： 通过自定义的 zapcore.Core 和选项创建 Logger，提供最大灵活性。 ​​参数​​：

• core: 日志核心组件，负责实际日志处理（编码、输出等）

• options: 可变参数，用于扩展功能（如添加钩子、修改编码器等） ​​返回值​​：

• *Logger: 日志记录器实例（若 core 为 nil，返回无操作日志器） ​​示例代码​​：

import (     
    "go.uber.org/zap"     
    "go.uber.org/zap/zapcore" 
    )  
    // 自定义核心：输出到文件，JSON 格式，级别为 Debug 
file, _ := os.Create("app.log") 
core := zapcore.NewCore(     
    zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),     
    zapcore.AddSync(file),     
    zap.DebugLevel, )  

// 创建 Logger 并添加调用者信息选项 
logger := zap.New(core, zap.AddCaller()) 
logger.Info("Custom logger created")

​​注意事项​​：

• ​​核心必填​​：必须提供有效的 core，否则日志器不执行任何操作。

• ​​性能考量​​：直接操作 core 需要理解 Zap 核心组件，适合高级用户。

5.2.2 ​​NewDevelopment​​

​​函数定义​​：

func NewDevelopment(options ...Option) (*Logger, error)

​​作用​​： 创建适合开发环境的 Logger，输出人类可读的控制台日志（默认 Debug 级别）。 ​​参数​​：

• options: 可选的扩展配置（如添加字段、修改编码器） ​​返回值​​：

• *Logger: 开发用日志器实例

• error: 可能的配置错误（如无效选项） ​​示例代码​​：

logger, err := zap.NewDevelopment(     
    zap.AddStacktrace(zap.ErrorLevel), // 错误级别及以上记录堆栈 
    ) 
if err != nil {     panic(err) } 
logger.Debug("Debug message visible") // 输出到 stderr

​​注意事项​​：

• ​​性能影响​​：控制台输出和堆栈跟踪可能影响性能，生产环境禁用。

• ​​颜色支持​​：终端需支持 ANSI 颜色，否则颜色代码会以文本形式显示。

5.2.3 ​​NewProduction​​

​​函数定义​​：

func NewProduction(options ...Option) (*Logger, error)

​​作用​​： 创建适合生产环境的 Logger，输出 JSON 格式日志（默认 Info 级别）。 ​​参数​​：

• options: 可选的扩展配置 ​​返回值​​：

• *Logger: 生产用日志器实例

• error: 可能的配置错误 ​​示例代码​​：

logger, err := zap.NewProduction(     
    zap.Fields(zap.String("service", "payment")), // 添加全局字段 ) 

if err != nil {     panic(err) } 
logger.Info("Payment processed", zap.Int("amount", 100)) // 输出：{"level":"info","ts":...,"service":"payment","msg":"Payment processed","amount":100}

​​注意事项​​：

• ​​日志采样​​：默认启用采样（防止日志洪泛），可通过 DisableSampling 关闭。

• ​​字段顺序​​：JSON 字段按字母序排列，需注意日志分析工具兼容性。

5.2.4 ​​NewExample​​

​​函数定义​​：

func NewExample(options ...Option) *Logger

​​作用​​： 创建用于测试或文档示例的 Logger，输出到 ioutil.Discard（无实际输出）。 ​​参数​​：

• options: 可选的扩展配置 ​​返回值​​：

• *Logger: 示例日志器（不写入任何输出） ​​示例代码​​：

logger := zap.NewExample() 
logger.Info("This log is discarded") // 无实际输出，但结构可被测试框架捕获

​​注意事项​​：

• ​​无副作用​​：适用于单元测试，避免真实 I/O 操作干扰测试结果。

• ​​性能测试​​：可用于基准测试，测量日志记录逻辑的性能。

5.2.5 ​​NewNop​​

​​函数定义​​：

func NewNop() *Logger

​​作用​​： 创建空操作 Logger，所有日志调用被忽略（不执行任何操作）。 ​​返回值​​：

• *Logger: 空日志器 ​​示例代码​​：

logger := zap.NewNop() 
logger.Error("This message is ignored") // 无输出，不触发错误

​​注意事项​​：

• ​​调试影响​​：禁用日志后可能掩盖问题，仅用于性能测试或特定场景。

• ​​恢复日志​​：可通过 WithOptions 重新启用核心（如 zap.WrapCore）。

5.2.6 ​​Must​​

​​函数定义​​：

func Must(logger *Logger, err error) *Logger

​​作用​​： 简化构造函数错误处理，若 err 非 nil 则触发 panic。 ​​参数​​：

• logger: 构造函数返回的日志器

• err: 构造函数返回的错误 ​​返回值​​：

• *Logger: 成功时的日志器实例 ​​示例代码​​：

// 在全局变量初始化中使用，避免繁琐的错误检查 
var logger = zap.Must(zap.NewProduction())  
func main() {     logger.Info("Server started") }

​​注意事项​​：

• ​​慎用场景​​：仅在应用启动阶段使用，避免运行时 panic。

• ​​替代方案​​：生产代码建议显式处理错误，而非依赖 Must。

5.2.7 Debug​​

​​方法定义​​：

func (log *Logger) Debug(msg string, fields ...Field)

​​作用​​：记录 DebugLevel 日志，用于详细调试信息。 ​​参数​​：

• msg: 日志消息（字符串）

• fields: 可变参数，附加的日志字段（如 zap.String("key", "value")） ​​示例​​：

logger.Debug("用户登录尝试",      
    zap.String("username", "alice"),      
    zap.Int("attempts", 3), ) // 输出（开发环境）： // 2023-07-28T14:20:00Z DEBUG 用户登录尝试  username=alice  attempts=3

​​注意​​：

• 生产环境默认关闭 Debug 级别，需通过配置开启。

• 避免在高频循环中记录大量 Debug 日志，影响性能。

5.2.8 ​​Info​​

​​方法定义​​：

func (log *Logger) Info(msg string, fields ...Field)

​​作用​​：记录 InfoLevel 日志，表示常规操作信息。 ​​示例​​：

logger.Info("服务启动",      
    zap.String("address", "0.0.0.0:8080"),      
    zap.Duration("startup_time", 2*time.Second), ) // 输出： // 2023-07-28T14:21:00Z INFO  服务启动  address=0.0.0.0:8080  startup_time=2s

​​注意​​：

• 适用于关键业务流程的跟踪，如服务启动、配置加载。

5.2.9 ​​Warn​​

​​方法定义​​：

func (log *Logger) Warn(msg string, fields ...Field)

​​作用​​：记录 WarnLevel 日志，表示潜在问题但程序仍可运行。 ​​示例​​：

logger.Warn("高内存使用率",      
    zap.Float64("memory_usage", 85.5), ) // 输出： // 2023-07-28T14:22:00Z WARN  高内存使用率  memory_usage=85.5

​​注意​​：

• 需要监控但无需立即处理的场景，如资源接近阈值。

5.2.10 ​​Error​​

​​方法定义​​：

func (log *Logger) Error(msg string, fields ...Field)

​​作用​​：记录 ErrorLevel 日志，表示操作失败但程序可恢复。 ​​示例​​：

err := errors.New("连接超时") 
logger.Error("请求处理失败",      
    zap.Error(err),      
    zap.String("endpoint", "/api/data"), ) // 输出： // 2023-07-28T14:23:00Z ERROR 请求处理失败  error="连接超时"  endpoint=/api/data

​​注意​​：

• 必须附加 zap.Error(err) 以记录错误堆栈（需配置）。

• 需结合重试或降级策略。

5.2.11 ​​DPanic​​

​​方法定义​​：

func (log *Logger) DPanic(msg string, fields ...Field)

​​作用​​：记录 DPanicLevel 日志，开发环境下触发 panic，生产环境仅记录日志。 ​​示例​​：

logger.DPanic("非预期空指针",      
    zap.String("function", "processOrder"), ) // 开发环境：输出日志后 panic；生产环境：仅记录日志。

​​注意​​：

• 用于捕获开发阶段的不可恢复错误，生产环境需禁用。

5.2.12 ​​Panic​​

​​方法定义​​：

func (log *Logger) Panic(msg string, fields ...Field)

​​作用​​：记录 PanicLevel 日志并触发 panic，无论环境配置。 ​​示例​​：

logger.Panic("关键配置缺失",      
    zap.String("config_key", "database_url"), 
    ) // 输出日志后触发 panic，程序终止。

​​注意​​：

• 仅用于严重错误（如配置缺失），需确保日志已持久化。

5.2.13 Fatal​​

​​方法定义​​：

func (log *Logger) Fatal(msg string, fields ...Field)

​​作用​​：记录 FatalLevel 日志并调用 os.Exit(1) 终止程序。 ​​示例​​：

logger.Fatal("端口被占用",      
    zap.Int("port", 8080), ) // 输出日志后程序退出。

​​注意​​：

• 确保终止前刷新日志缓冲区（调用 Sync()）。

• 避免在常驻服务中频繁使用。

5.2.14 Log​​

​​方法定义​​：

func (log *Logger) Log(lvl zapcore.Level, msg string, fields ...Field)

​​作用​​：动态指定级别记录日志，适用于级别由外部参数决定的场景。 ​​参数​​：

• lvl: 日志级别（如 zapcore.DebugLevel）

• msg: 日志消息

• fields: 附加字段 ​​示例​​：

// 根据环境变量动态设置级别 
level := zapcore.DebugLevel 
logger.Log(level, "动态级别日志",   
    zap.String("env", "development"), 
    ) // 输出：根据 level 值记录对应级别的日志。

​​注意​​：

• 性能略低于直接调用级别方法（需类型检查），高频调用需优化。

• 适用于日志级别由配置或用户输入决定的场景。​

5.2.15 ​​With​​

​​方法定义​​：

func (log *Logger) With(fields ...Field) *Logger

​​作用​​：创建子 Logger，附加固定字段到所有日志。 ​​参数​​：

• fields: 固定字段（如 zap.String("service", "auth")） ​​示例​​：

childLogger := logger.With(     
    zap.String("request_id", "req-123"),     
    zap.String("service", "payment"), ) 

childLogger.Info("支付处理中") // 输出： // 2023-07-28T14:25:00Z INFO  支付处理中  request_id=req-123  service=payment

​​注意​​：

• 字段在所有子日志中自动包含，适用于请求链路的上下文传递。

• 避免创建过多子 Logger，增加内存开销。

5.2.16 ​​WithLazy​​

​​方法定义​​：

func (log *Logger) WithLazy(fields ...Field) *Logger

​​作用​​：创建子 Logger，延迟评估字段值，直到日志实际写入时计算。 ​​示例​​：

var count int 
lazyLogger := logger.WithLazy(     
    zap.Int("current_count", func() int { return count }), 
    ) 
count = 42 
lazyLogger.Info("计数更新") // 输出：current_count=42

​​注意​​：

• 适用于字段值计算成本高或可能变化的场景（如当前时间）。

• 闭包中避免引用外部变量导致竞态条件。

5.2.17 ​​WithOptions​​

​​方法定义​​：

func (log *Logger) WithOptions(opts ...Option) *Logger

​​作用​​：应用新选项创建子 Logger，如修改编码器、添加钩子。 ​​参数​​：

• opts: 配置选项（如 zap.AddCaller()） ​​示例​​：

newLogger := logger.WithOptions(     
    zap.AddCaller(),        // 记录调用位置     
    zap.WrapCore(func(core zapcore.Core) zapcore.Core {        
     return sampledCore                // 自定义采样核心     
     }), 
     ) 
newLogger.Info("带调用者信息的日志") // 输出： // 2023-07-28T14:26:00Z INFO  ...  caller=module/main.go:42

​​注意​​：

• 选项按顺序应用，可能覆盖之前的配置。

• 可用于运行时动态调整日志行为（如切换日志级别）。

5.2.18 Name()​​

​​方法定义​​：

func (log *Logger) Name() string

​​作用​​： 返回当前 Logger 的名称。未命名的 Logger 返回空字符串。 ​​返回值​​：

• string：Logger 名称（例如 "auth" 或 "payment.service"）。 ​​示例​​：

logger := zap.NewExample().Named("auth") fmt.Println(logger.Name()) // 输出: "auth"

​​注意​​：

• 名称通常用于区分不同模块的日志，便于过滤和分析。

5.2.19 ​​Named()​​

​​方法定义​​：

func (log *Logger) Named(s string) *Logger

​​作用​​： 为 Logger 添加名称段（通过 . 连接），生成子 Logger。 ​​参数​​：

• s：名称段（如 "service"）。 ​​示例​​：

parent := zap.NewExample().Named("app") 
child := parent.Named("auth") 
fmt.Println(child.Name()) // 输出: "app.auth"

​​注意​​：

• 名称段应简洁，避免使用动态值（如用户 ID），导致日志分类混乱。

5.2.20 Sync()​​

​​方法定义​​：

func (log *Logger) Sync() error

​​作用​​： 强制刷新缓冲区，确保所有日志写入底层输出（如文件）。 ​​返回值​​：

• error：刷新过程中遇到的错误。 ​​示例​​：

logger := zap.NewExample() 
defer logger.Sync() // 程序退出前确保日志持久化 logger.Info("日志已记录")

​​注意​​：

• ​​必须调用​​：在程序退出前调用 Sync()，否则可能丢失缓冲日志。

• ​​性能影响​​：频繁调用可能影响性能，建议在退出时一次性调用。​

5.2.21 ​​Sugar()​​

​​方法定义​​：

func (log *Logger) Sugar() *SugaredLogger

​​作用​​： 将 Logger 转换为 SugaredLogger，提供更友好但性能稍低的 API。 ​​示例​​：

logger := zap.NewExample() 
sugar := logger.Sugar() 
sugar.Infof("用户 %s 登录成功，耗时 %dms", "Alice", 120) // 输出（JSON 格式）: {"level":"info","msg":"用户 Alice 登录成功，耗时 120ms"}

​​注意​​：

• ​​性能取舍​​：SugaredLogger 的格式化方法（如 Infof）比 Logger 的 Info 稍慢。

• ​​类型安全​​：格式化字符串可能引入类型错误，需谨慎使用。​

5.2.22 ​​Core()​​

​​方法定义​​：

func (log *Logger) Core() zapcore.Core

​​作用​​： 获取 Logger 的底层 zapcore.Core，用于扩展或自定义日志处理逻辑。 ​​示例​​：

logger := zap.NewExample() core := logger.Core()  // 修改核心配置（例如添加钩子） 
newCore := zapcore.NewTee(core, additionalCore) 
newLogger := zap.New(newCore)

​​注意​​：

• ​​高级用法​​：直接操作 Core 需熟悉 Zap 核心组件，不建议新手使用。

• ​​线程安全​​：确保在修改 Core 时无并发写入。​

5.2.23 ​​L()​​

​​函数定义​​：

func L() *Logger

​​作用​​： 获取全局默认 Logger（通过 ReplaceGlobals 修改）。 ​​示例​​：

// 修改全局 Logger 
zap.ReplaceGlobals(zap.NewProduction())  
// 使用全局 Logger 
zap.L().Info("全局日志")

​​注意​​：

• ​​并发安全​​：全局 Logger 的替换和读取是线程安全的。

• ​​慎用全局变量​​：过度依赖全局 Logger 可能导致代码耦合，建议依赖注入。​

5.2.24 ​​Check()​​

​​方法定义​​：

func (log *Logger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry

​​作用​​： 检查是否启用某级别日志，返回 CheckedEntry 避免不必要的字段计算。 ​​参数​​：

• lvl：要检查的日志级别。

• msg：日志消息。 ​​示例​​：

if ce := logger.Check(zap.DebugLevel, "调试信息"); ce != nil {     
    ce.Write(         
        zap.String("detail", "内存使用率 90%"),         
        zap.Int("count", 42),     ) } // 仅当 Debug 级别启用时，才计算字段值。

​​注意​​：

• ​​性能优化​​：用于高频调用路径，避免无效字段计算。

• ​​复杂逻辑​​：需手动管理字段写入，增加代码复杂度。

5.2.25 Level()​​

​​方法定义​​：

func (log *Logger) Level() zapcore.Level

​​作用​​： 返回当前 Logger 的最低启用日志级别（如 zap.InfoLevel）。 ​​示例​​：

if logger.Level() <= zap.DebugLevel {     // 执行调试相关操作（如生成详细日志） }

​​注意​​：

• ​​NopLogger​​：对于 NewNop() 创建的 Logger，返回 zapcore.InvalidLevel。

• ​​动态调整​​：结合 AtomicLevel 可实现运行时级别调整。

5.3 SugaredLogger类型

SugaredLogger 是 Zap 提供的一个更友好、更灵活的日志记录器，相比 Logger，它牺牲了部分性能以换取更简洁的 API，支持类似 fmt.Printf 的格式化日志输出，同时兼容结构化日志字段。 ​​适用场景​​：

• 需要快速编写日志，无需严格类型检查。

• 日志输出需要动态字段或复杂格式。

• 非性能敏感代码（如 CLI 工具、低频后台任务）。

5.3.1 Debugf, Infof, Warnf, Errorf, DPanicf, Panicf, Fatalf​​

​​函数定义​​：

func (s *SugaredLogger) Debugf(template string, args ...interface{}) 
func (s *SugaredLogger) Infof(template string, args ...interface{}) // 其他级别方法类似...

​​作用​​：以 fmt.Printf 风格记录格式化日志，支持动态参数。 ​​示例​​：

userID := 42 err := errors.New("连接超时") 
sugar.Errorf("用户 %d 操作失败: %v", userID, err) // 输出：{"level":"error","msg":"用户 42 操作失败: 连接超时"}

​​注意​​：

• ​​性能影响​​：格式化操作（如 %d、%s）会引入额外开销，高频调用需谨慎。

• ​​类型安全​​：参数类型需与格式化字符串匹配，否则可能引发运行时错误。

5.3.2 ​​Debugw, Infow, Warnw, Errorw, DPanicw, Panicw, Fatalw​​

​​函数定义​​：

func (s *SugaredLogger) Debugw(msg string, keysAndValues ...interface{}) 
func (s *SugaredLogger) Infow(msg string, keysAndValues ...interface{}) // 其他级别方法类似...

​​作用​​：记录带结构化字段的日志，字段以键值对形式传递。 ​​示例​​：

sugar.Infow("用户登录成功",     
    "userID", 42,     
    "username", "alice",     
    "latency", 150*time.Millisecond, ) // 输出：{"level":"info","msg":"用户登录成功","userID":42,"username":"alice","latency":150}

​​注意​​：

• ​​键值对顺序​​：必须成对出现（如 "key1", value1, "key2", value2）。

• ​​动态字段名​​：字段名（键）必须是字符串，值可以是任意类型。

5.3.3 ​​Debugln, Infoln, Warnln, Errorln, DPanicln, Panicln, Fatalln​​

​​函数定义​​：

func (s *SugaredLogger) Debugln(args ...interface{}) 
func (s *SugaredLogger) Infoln(args ...interface{}) // 其他级别方法类似...

​​作用​​：以空格分隔参数记录日志，类似 fmt.Println。 ​​示例​​：

sugar.Infoln("当前温度:", 26.5, "℃", "，状态: 正常") // 输出：{"level":"info","msg":"当前温度: 26.5 ℃ ，状态: 正常"}

​​注意​​：

• ​​适用性​​：适合简单日志，复杂结构化数据建议使用 *w 方法。

• ​​性能​​：参数拼接开销较高，高频场景慎用。

5.3.4 Desugar() *Logger​​

​​作用​​：将 SugaredLogger 转换回高性能的 Logger。 ​​示例​​：

logger := sugar.Desugar() logger.Info("高性能日志", zap.String("key", "value"))

​​注意​​：

• 在性能敏感路径中，使用 Logger 代替 SugaredLogger。

5.3.5 With(args ...interface{}) *SugaredLogger​​

​​作用​​：创建子 SugaredLogger，附加键值对作为全局字段。 ​​参数​​：

• args：交替的键值对（如 "user", "alice"），键必须是字符串。 ​​示例​​：

child := sugar.With("service", "auth", "version", "v1.0") 
child.Info("请求处理")  // 输出：{"level":"info","msg":"请求处理","service":"auth","version":"v1.0"}

​​注意​​：

• 键值对必须成对出现，否则会记录错误。

• 字段在所有子日志中自动包含。

5.3.6 S()

函数定义：

func S() *SugaredLogger

S 返回全局 SugaredLogger，可以使用 ReplaceGlobals 重新配置。并发使用是安全的。

5.4 Config类型

Config 用于声明式配置 Logger，支持常见选项的快速设置。

type Config struct {
    Level             AtomicLevel              // 动态日志级别（可运行时调整）
    Development       bool                     // 开发模式（影响 DPanic 和堆栈跟踪行为）
    DisableCaller     bool                     // 禁用记录调用者信息（文件名和行号）
    DisableStacktrace bool                     // 禁用自动堆栈跟踪捕获
    Sampling          *SamplingConfig         // 日志采样配置（防止日志洪泛）
    Encoding          string                   // 编码格式（"json"、"console" 或自定义）
    EncoderConfig      zapcore.EncoderConfig    // 编码器配置（时间格式、字段键名等）
    OutputPaths       []string                 // 日志输出路径（如文件、stdout）
    ErrorOutputPaths  []string                 // 错误日志输出路径（默认 stderr）
    InitialFields     map[string]interface{}   // 初始字段（全局添加到每条日志）
}

5.4.1 NewDevelopmentConfig​​

​​函数定义​​：

func NewDevelopmentConfig() Config

​​作用​​：生成开发环境默认配置（控制台输出、Debug 级别、包含堆栈跟踪）。 ​​默认值​​：

• Level: DebugLevel

• Development: true

• Encoding: "console"

• OutputPaths: ["stderr"]

• Stacktrace: 在 WarnLevel 及以上触发

​​示例​​：

cfg := zap.NewDevelopmentConfig() 
cfg.OutputPaths = []string{"stdout", "/tmp/dev.log"} // 输出到控制台和文件 
logger, _ := cfg.Build() 
logger.Debug("开发环境日志")

5.4.2 ​​NewProductionConfig​​

​​函数定义​​：

func NewProductionConfig() Config

​​作用​​：生成生产环境默认配置（JSON 输出、Info 级别、错误日志采样）。 ​​默认值​​：

• Level: InfoLevel

• Development: false

• Encoding: "json"

• OutputPaths: ["stderr"]

• Sampling: 每秒最多记录 100 条相同消息

• Stacktrace: 在 ErrorLevel 及以上触发

​​示例​​：

cfg := zap.NewProductionConfig() 
cfg.Level = zap.NewAtomicLevelAt(zap.WarnLevel) // 仅记录 Warn 及以上 
logger, _ := cfg.Build() 
logger.Warn("生产环境警告")

5.4.3 ​Build 方法​​

​​方法定义​​：

func (cfg Config) Build(opts ...Option) (*Logger, error)

​​作用​​：将 Config 转换为 Logger 实例，可附加额外选项。 ​​参数​​：

• opts: 扩展选项（如 zap.AddCaller()） ​​返回值​​：

• *Logger: 构建的 Logger

• error: 配置错误（如无效路径）

​​示例​​：

cfg := zap.Config{     
    Level:            zap.NewAtomicLevelAt(zap.DebugLevel),    
    Encoding:         "json",     
    OutputPaths:      []string{"stdout"},     
    ErrorOutputPaths: []string{"stderr"},     
    EncoderConfig:    zap.NewProductionEncoderConfig(), 
    } 
// 添加调用者信息选项 
logger, err := cfg.Build(zap.AddCaller()) 
if err != nil {     panic(err) } 
logger.Info("自定义配置日志")

5.5 Option接口

用于在创建或修改 zap.Logger 时​​动态配置日志记录器的行为​​。通过传入不同的 Option 参数，可以灵活定制日志的输出格式、性能优化、上下文字段等特性。

zap.Option 允许通过链式调用（函数式选项模式）配置以下内容：

1. ​​日志编码器​​（JSON 或 Console 格式）

2. ​​日志级别​​（Debug、Info、Error 等）

3. ​​日志输出位置​​（文件、标准输出、网络等）

4. ​​上下文字段​​（添加固定字段到所有日志）

5. ​​调用栈信息​​（记录日志调用的代码位置）

6. ​​钩子（Hooks）​​（在日志写入时触发自定义逻辑）

5.5.1 AddCaller()​​

​​函数定义​​：

func AddCaller() Option

​​作用​​：在日志中记录调用者的 ​​文件名、行号、函数名​​。 ​​示例​​：

logger := zap.Must(zap.NewProduction(zap.AddCaller())) 
logger.Info("用户登录")  // 输出：{"level":"info","ts":...,"caller":"main.go:15","msg":"用户登录"}

​​注意​​：

• 生产环境建议启用，便于追踪问题来源。

• 对性能有微小影响，高频日志场景需评估。

5.5.2 AddCallerSkip(skip int)​​

​​函数定义​​：

func AddCallerSkip(skip int) Option

​​作用​​：调整调用栈跳过的层数，适用于封装 Logger。 ​​参数​​：

• skip：跳过的调用栈层数。 ​​示例​​：

// 封装 Logger 的工具函数 
func NewLogger() *zap.Logger {     
    return zap.Must(zap.NewProduction(         
        zap.AddCaller(),         
        zap.AddCallerSkip(1), // 跳过当前函数层     
        )) } // 调用处日志显示实际调用者，而非工具函数内部

​​注意​​：

• 跳过的层数需与实际封装层级匹配，否则调用者信息不准确。

5.5.3 AddStacktrace(lvl zapcore.LevelEnabler)​​

​​函数定义​​：

func AddStacktrace(lvl zapcore.LevelEnabler) Option

​​作用​​：在 ​​指定级别及以上​​ 的日志中记录堆栈跟踪。 ​​示例​​：

logger := zap.Must(zap.NewProduction(     
    zap.AddStacktrace(zap.ErrorLevel), // 仅 Error 及以上记录堆栈 
    )) 
logger.Error("数据库连接失败") // 输出包含堆栈跟踪 
logger.Warn("高延迟警告")     // 无堆栈跟踪

​​注意​​：

• 生产环境可设为 ErrorLevel，避免过多堆栈信息影响性能。

5.5.4 Fields(fs ...Field)​​

​​函数定义​​：

func Fields(fs ...Field) Option

​​作用​​：添加 ​​全局字段​​ 到所有日志中（如服务名、版本）。 ​​示例​​：

logger := zap.Must(zap.NewProduction(     
    zap.Fields(         
        zap.String("service", "payment"),         
        zap.String("version", "v2.1"),     
        ), 
        )) 

logger.Info("支付成功")  // 输出：{"service":"payment","version":"v2.1",...}

​​注意​​：

• 字段在所有日志中自动包含，避免重复添加。

• 复杂对象建议用 zap.Object 或延迟计算的 zap.Lazy。

5.5.5 Hooks(hooks ...func(zapcore.Entry) error)​​

​​函数定义​​：

func Hooks(hooks ...func(zapcore.Entry) error) Option

​​作用​​：注册钩子函数，每次记录日志时触发（如统计、告警）。 ​​示例​​：

// 统计错误日志数量
errorCounter := prometheus.NewCounter(...)
hook := func(e zapcore.Entry) error {
    if e.Level == zap.ErrorLevel {
        errorCounter.Inc()
    }
    return nil
}
logger := zap.Must(zap.NewProduction(zap.Hooks(hook)))

​​注意​​：

• 钩子函数需轻量，避免阻塞日志记录。

• 复杂操作（如发送邮件）应通过消息队列异步处理。

5.5.6 WithFatalHook(hook zapcore.CheckWriteHook)​​ (v1.22.0+)

​​函数定义​​：

func WithFatalHook(hook zapcore.CheckWriteHook) Option

​​作用​​：在 Fatal 日志后执行自定义逻辑（如优雅退出）。 ​​示例​​：

hook := zapcore.WriteThenGoexit // 写入日志后退出当前 goroutine 
logger := zap.New(core, zap.WithFatalHook(hook)) 
logger.Fatal("致命错误") // 日志写入后调用 hook

​​注意​​：

• 钩子中必须终止程序（如 os.Exit）或明确处理流程。

• 避免在钩子中执行耗时操作。

5.5.7 IncreaseLevel(lvl zapcore.LevelEnabler)​​ (v1.14.0+)

​​函数定义​​：

func IncreaseLevel(lvl zapcore.LevelEnabler) Option

​​作用​​：提升 Logger 的最低日志级别（如从 Info 提升到 Warn）。 ​​示例​​：

// 原 Logger 级别为 Info，提升后只记录 Warn 及以上 
logger := zap.Must(zap.NewProduction(     
    zap.IncreaseLevel(zap.WarnLevel), 
    )) 
logger.Info("此日志被过滤")  // 不输出 
logger.Warn("高内存使用率")  // 输出

​​注意​​：

• 仅能提升级别，不能降低（如从 Error 设为 Warn 无效）。

• 结合 AtomicLevel 可实现动态调整。

5.5.8 ErrorOutput(w zapcore.WriteSyncer)​​

​​函数定义​​：

func ErrorOutput(w zapcore.WriteSyncer) Option

​​作用​​：设置内部错误（如日志写入失败）的输出目标。 ​​示例​​：

file, _ := os.Create("internal_errors.log") 
    logger := zap.Must(zap.NewProduction(     zap.ErrorOutput(zapcore.AddSync(file)), ))

​​注意​​：

• 默认输出到 stderr，重定向到文件需确保可写。

• 使用 zapcore.Lock 保证并发安全。

5.5.9 Development()​​

​​函数定义​​：

func Development() Option

​​作用​​：启用开发模式，DPanic 触发 panic，堆栈跟踪更宽松。 ​​示例​​：

logger := zap.Must(zap.NewDevelopment(zap.Development())) 
logger.DPanic("空指针异常") // 触发 panic

​​注意​​：

• 生产环境必须禁用此选项。

• 开发模式下 DisableStacktrace 默认关闭。

5.5.10 WrapCore(f func(zapcore.Core) zapcore.Core)​​

​​函数定义​​：

func WrapCore(f func(zapcore.Core) zapcore.Core) Option

​​作用​​：替换或包装底层 Core，实现自定义日志处理逻辑。 ​​示例​​：

// 添加过滤核心，忽略包含敏感字段的日志 filterCore := zapcore.NewCore( encoder, zapcore.AddSync(os.Stdout), zap.LevelEnablerFunc(func(lvl zapcore.Level) bool { return lvl >= zap.InfoLevel }), ) logger := zap.New(core, zap.WrapCore(func(c zapcore.Core) zapcore.Core { return filterCore }))

​​注意​​：

• 高级用法，需深入理解 zapcore.Core 机制。

• 确保新 Core 线程安全。

5.5.11 WithClock(clock zapcore.Clock)​​ (v1.18.0+)

​​函数定义​​：

func WithClock(clock zapcore.Clock) Option

​​作用​​：自定义日志时间戳的时钟源（如测试时模拟时间）。 ​​示例​​：

type MockClock struct {
    time time.Time
}
func (c *MockClock) Now() time.Time { return c.time }
func (c *MockClock) NewTicker(d time.Duration) *time.Ticker { ... }

logger := zap.New(core, zap.WithClock(&MockClock{time: time.Date(2023, 7, 28, 0, 0, 0, 0, time.UTC)}))

​​注意​​：

• 主要用于测试或特殊时间格式需求。

• 实现 zapcore.Clock 接口需完整。

5.6 Config和Option

​​特性​​	​​Config​​	​​Option​​
​​配置方式​​	声明式（结构体字段）	函数式（链式调用）
​​灵活性​​	适合静态预设，一次性配置	适合动态扩展，逐步添加功能
​​复用性​​	通过结构体模板复用	通过函数封装复用
​​适用场景​​	复杂/完整的配置需求	模块化/增量式配置需求
​​动态调整​​	需结合 AtomicLevel 调整级别	通过 WithOptions 动态修改配置
​​预设支持​​	提供生产/开发环境预设模板	无预设，需手动组合

• 互补关系​​：Config 用于定义基础配置，Option 用于扩展功能。

• ​​组合使用​​：通过 Config.Build(opts ...Option) 可以结合两者。

cfg := zap.NewProductionConfig() 
logger, _ := cfg.Build(zap.AddCaller(), zap.AddStacktrace(zap.ErrorLevel))

5.6.1 使用 Config 的场景​​

1. ​​从配置文件加载​​：如从 JSON/YAML 文件读取日志配置。

2. ​​环境预设模板​​：快速生成生产或开发环境的默认配置。

3. ​​复杂配置需求​​：需要同时设置编码器、输出路径、采样策略等多项参数。

5.6.2 ​​使用 Option 的场景​​

1. ​​增量式扩展​​：在已有配置上添加功能（如全局字段、调用者信息）。

2. ​​代码复用​​：封装常用配置（如 NewLoggerWithMetrics 函数返回预设 Option）。

3. ​​动态调整​​：运行时修改 Logger 的行为（如切换日志级别、添加钩子）。

总结

• ​​Config​​：适合 ​​静态、完整、复杂​​ 的配置需求，尤其是需要从文件加载或使用环境预设模板的场景。

• ​​Option​​：适合 ​​模块化、动态、增量式​​ 的配置需求，尤其是需要灵活扩展和代码复用的场景。

• ​​组合使用​​：两者可以结合，先用 Config 定义基础配置，再用 Option 扩展功能，兼顾灵活性和完整性。

5.7 Field类型

Field是zapcore.Field的别名。

type Field = zapcore.Field

数据类型函数可以参考Field页面

处理 ​​未知或动态类型​​，可能牺牲性能。

• Any(key string, value interface{}) Field 自动选择最佳序列化方式，优先避免反射。

• Reflect(key string, val interface{}) Field 强制使用反射序列化，性能较差。

隔离字段作用域​​，避免键名冲突。

• Namespace(key string) Field 创建嵌套命名空间，后续字段归入此空间。 示例：

    logger.Info("请求",     
    zap.Namespace("user"),     
    zap.String("name", "Alice"),     
    zap.Int("age", 30), 
    ) // 输出：{"user": {"name":"Alice", "age":30}}

5.8 Sink接口

Sink 接口定义了日志输出的目标和生命周期管理方法，用于扩展 Zap 的日志输出方式（如写入远程服务、自定义存储等）。

type Sink interface {     
    zapcore.WriteSyncer  // 继承 Write([]byte) 和 Sync() 方法     
    io.Closer            // 继承 Close() 方法 
    }

1. ​​Write(p []byte) (n int, err error)​​

   • ​​作用​​：将日志数据写入目标（如文件、网络等）。

   • ​​输入​​：p []byte（要写入的日志字节数据）。

   • ​​输出​​：

     • n int：成功写入的字节数。

     • err error：写入过程中发生的错误（如网络中断）。

2. ​​Sync() error​​

   • ​​作用​​：将缓冲区中的数据同步到底层存储（如刷新文件到磁盘）。

   • ​​输出​​：error（同步失败时的错误信息）。

3. ​​Close() error​​

   • ​​作用​​：关闭资源（如文件句柄、网络连接），释放占用的系统资源。

   • ​​输出​​：error（关闭失败时的错误信息）。

package main

import (
    "bytes"
    "net/http"
    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

// HTTPSink 实现 Sink 接口
type HTTPSink struct {
    url    string       // 日志接收地址
    client *http.Client // HTTP 客户端
}

func NewHTTPSink(url string) *HTTPSink {
    return &HTTPSink{
        url:    url,
        client: &http.Client{},
    }
}

// Write 发送日志到 HTTP 端点
func (s *HTTPSink) Write(p []byte) (int, error) {
    resp, err := s.client.Post(s.url, "application/json", bytes.NewReader(p))
    if err != nil {
        return 0, err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return 0, fmt.Errorf("HTTP 状态码异常: %d", resp.StatusCode)
    }
    return len(p), nil
}

// Sync 无操作（HTTP 无需手动同步）
func (s *HTTPSink) Sync() error {
    return nil
}

// Close 释放资源（如关闭 HTTP 长连接）
func (s *HTTPSink) Close() error {
    s.client.CloseIdleConnections()
    return nil
}

// 注册 Sink 工厂函数
func init() {
    // 注册协议 "http"，URL 格式：http://host:port/path
    zap.RegisterSink("http", func(url string) (zap.Sink, error) {
        return NewHTTPSink(url), nil
    })
}

func main() {
    // 配置 Logger 使用自定义 Sink
    cfg := zap.NewProductionConfig()
    cfg.OutputPaths = []string{"http://localhost:8080/logs"} // 使用 http 协议
    logger, err := cfg.Build()
    if err != nil {
        panic(err)
    }
    defer logger.Sync()

    logger.Info("测试日志通过 HTTP Sink 发送")
}