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 允许通过链式调用（函数式选项模式）配置以下内容：

日志编码器（JSON 或 Console 格式）
日志级别（Debug、Info、Error 等）
日志输出位置（文件、标准输出、网络等）
上下文字段（添加固定字段到所有日志）
调用栈信息（记录日志调用的代码位置）
钩子（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` 的场景

从配置文件加载：如从 JSON/YAML 文件读取日志配置。
环境预设模板：快速生成生产或开发环境的默认配置。
复杂配置需求：需要同时设置编码器、输出路径、采样策略等多项参数。

5.6.2 使用 `Option` 的场景

增量式扩展：在已有配置上添加功能（如全局字段、调用者信息）。
代码复用：封装常用配置（如 NewLoggerWithMetrics 函数返回预设 Option）。
动态调整：运行时修改 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() 方法 
    }

Write(p []byte) (n int, err error)
- 作用：将日志数据写入目标（如文件、网络等）。
- 输入：p []byte（要写入的日志字节数据）。
- 输出：
  - n int：成功写入的字节数。
  - err error：写入过程中发生的错误（如网络中断）。
Sync() error
- 作用：将缓冲区中的数据同步到底层存储（如刷新文件到磁盘）。
- 输出：error（同步失败时的错误信息）。
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 发送")
}

最后更新于1个月前

1 快速开始

2 子包说明

3 常量

4 函数

4.1 输出控制类​​

4.1.1 CombineWriteSyncers

4.1.2 Open

4.2 编码器配置类​​

4.2.1 NewDevelopmentEncoderConfig

4.2.2 NewProductionEncoderConfig

4.2.3 RegisterEncoder

4.3 标准日志集成类​​

4.3.1 NewStdLog

4.3.2 RedirectStdLog

4.4 全局管理类​​

4.4.1 ReplaceGlobals

4.4.2 LevelFlag

4.4.3 RegisterSink 函数定义​​

5 类型

5.1 AtomicLevel 类型

5.1.1 NewAtomicLevel()

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

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

5.1.4 SetLevel(l zapcore.Level)

5.1.5 Level()

5.1.6 Enabled(l zapcore.Level) bool

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

5.1.8 MarshalText() (v1.3.0+)

5.1.9 UnmarshalText(text []byte) error

5.1.10 String() (v1.4.0+)

5.1.11 完整示例

5.2 Logger类型

5.2.1 New

5.2.2 ​​NewDevelopment​​

5.2.3 ​​NewProduction​​

5.2.4 ​​NewExample​​

5.2.5 ​​NewNop​​

5.2.6 ​​Must​​

5.2.7 Debug​​

5.2.8 ​​Info​​

5.2.9 ​​Warn​​

5.2.10 ​​Error​​

5.2.11 ​​DPanic​​

5.2.12 ​​Panic​​

5.2.13 Fatal​​

5.2.14 Log​​

5.2.15 ​​With​​

5.2.16 ​​WithLazy​​

5.2.17 ​​WithOptions​​

5.2.18 Name()​​

5.2.19 ​​Named()​​

5.2.20 Sync()​​

5.2.21 ​​Sugar()​​

5.2.22 ​​Core()​​

5.2.23 ​​L()​​

5.2.24 ​​Check()​​

5.2.25 Level()​​

5.3 SugaredLogger类型

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

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

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

5.3.4 Desugar() *Logger​​

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

5.3.6 S()

5.4 Config类型

5.4.1 NewDevelopmentConfig​​

5.4.2 ​​NewProductionConfig​​

5.4.3 ​Build 方法​​

5.5 Option接口

5.5.1 AddCaller()​​

5.5.2 AddCallerSkip(skip int)​​

5.5.3 AddStacktrace(lvl zapcore.LevelEnabler)​​

5.5.4 Fields(fs ...Field)​​

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

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

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

5.5.8 ErrorOutput(w zapcore.WriteSyncer)​​

5.5.9 Development()​​

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

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

4.1 输出控制类

4.2 编码器配置类

4.3 标准日志集成类

4.4 全局管理类

4.4.3 RegisterSink 函数定义

5.2.2 NewDevelopment

5.2.3 NewProduction

5.2.4 NewExample

5.2.5 NewNop

5.2.6 Must

5.2.7 Debug

5.2.8 Info

5.2.9 Warn

5.2.10 Error

5.2.11 DPanic

5.2.12 Panic

5.2.13 Fatal

5.2.14 Log

5.2.15 With

5.2.16 WithLazy

5.2.17 WithOptions

5.2.18 Name()

5.2.19 Named()

5.2.20 Sync()

5.2.21 Sugar()

5.2.22 Core()

5.2.23 L()

5.2.24 Check()

5.2.25 Level()

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

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

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

5.3.4 Desugar() *Logger

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

5.4.1 NewDevelopmentConfig

5.4.2 NewProductionConfig

5.4.3 Build 方法

5.5.1 AddCaller()

5.5.2 AddCallerSkip(skip int)

5.5.3 AddStacktrace(lvl zapcore.LevelEnabler)

5.5.4 Fields(fs ...Field)

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

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

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

5.5.8 ErrorOutput(w zapcore.WriteSyncer)

5.5.9 Development()

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

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

5.6.1 使用 `Config` 的场景

5.6.2 使用 `Option` 的场景