使用 zl - 基于 Zap 的高开发者体验日志库

zl 是一个基于 Uber 的 Zap 日志库构建的 Go 日志插件库，旨在提供更好的开发者体验和更简洁的 API。下面我将介绍如何使用 zl 进行日志记录。

安装

首先安装 zl 库：

go get github.com/go-zing/gozz-kit/zlog

基本使用

初始化日志器

package main

import (
	"github.com/go-zing/gozz-kit/zlog"
	"go.uber.org/zap"
)

func main() {
	// 使用默认配置初始化
	logger := zlog.Default()

	// 或者自定义配置
	customLogger, err := zlog.New(
		zlog.WithLevel(zap.DebugLevel),
		zlog.WithOutputPaths([]string{"stdout", "app.log"}),
		zlog.WithErrorOutputPaths([]string{"stderr"}),
	)
	if err != nil {
		panic(err)
	}
	defer customLogger.Sync()
}

记录日志

func logExample() {
	logger := zlog.Default()

	// 不同级别日志
	logger.Debug("这是一条调试信息")
	logger.Info("这是一条普通信息")
	logger.Warn("这是一条警告信息")
	logger.Error("这是一条错误信息")
	// logger.Fatal("致命错误，会调用os.Exit(1)")
	// logger.Panic("恐慌错误，会引发panic")

	// 带结构化字段的日志
	logger.Info("用户登录",
		zap.String("username", "john"),
		zap.Int("attempt", 3),
		zap.Duration("elapsed", time.Second),
	)

	// 使用Sugar()简化日志记录
	sugar := logger.Sugar()
	sugar.Infow("用户登录",
		"username", "john",
		"attempt", 3,
		"elapsed", time.Second,
	)
	sugar.Infof("用户 %s 登录，尝试次数 %d", "john", 3)
}

高级特性

日志采样

func samplingExample() {
	logger, err := zlog.New(
		zlog.WithSampling(&zap.SamplingConfig{
			Initial:    100,
			Thereafter: 100,
		}),
	)
	if err != nil {
		panic(err)
	}
	defer logger.Sync()

	// 当日志量很大时，采样配置可以帮助减少日志量
	for i := 0; i < 1000; i++ {
		logger.Info("高频率日志消息", zap.Int("count", i))
	}
}

自定义编码器

func encoderExample() {
	logger, err := zlog.New(
		zlog.WithEncoderConfig(zapcore.EncoderConfig{
			TimeKey:        "ts",
			LevelKey:       "level",
			NameKey:        "logger",
			CallerKey:      "caller",
			FunctionKey:    zapcore.OmitKey,
			MessageKey:     "msg",
			StacktraceKey:  "stacktrace",
			LineEnding:     zapcore.DefaultLineEnding,
			EncodeLevel:    zapcore.LowercaseLevelEncoder,
			EncodeTime:     zapcore.ISO8601TimeEncoder,
			EncodeDuration: zapcore.StringDurationEncoder,
			EncodeCaller:   zapcore.ShortCallerEncoder,
		}),
	)
	if err != nil {
		panic(err)
	}
	defer logger.Sync()
}

上下文日志

func contextExample() {
	logger := zlog.Default()

	// 创建带有固定字段的派生logger
	userLogger := logger.With(
		zap.String("userID", "12345"),
		zap.String("traceID", "abcde"),
	)

	// 这些日志都会自动带上userID和traceID字段
	userLogger.Info("用户操作1")
	userLogger.Warn("用户操作2")
}

性能优化

func performanceExample() {
	logger := zlog.Default()

	// 对于性能敏感的场景，可以使用Check+Write组合避免不必要的字段计算
	if ce := logger.Check(zap.InfoLevel, "性能敏感日志"); ce != nil {
		ce.Write(
			zap.String("key", "value"),
			zap.Int("count", 42),
		)
	}
}

最佳实践

1. 合理使用日志级别：

   • Debug: 调试信息
   • Info: 重要业务流程
   • Warn: 预期外的异常但不影响程序运行
   • Error: 影响程序运行的错误

2. 结构化日志：尽量使用结构化字段而非字符串拼接

3. 避免频繁Sync：Sync操作会刷新缓冲区的日志到磁盘，频繁调用会影响性能

4. 生产环境配置：

   func productionConfig() {
       logger, err := zlog.New(
           zlog.WithLevel(zap.InfoLevel), // 生产环境通常用Info级别
           zlog.WithOutputPaths([]string{"stdout"}), // 配合日志收集系统
           zlog.WithDevelopment(false), // 关闭开发模式
       )
       if err != nil {
           panic(err)
       }
       defer logger.Sync()
   }
   

zl 通过封装 Zap 提供了更简洁的 API 和更好的默认配置，同时保留了 Zap 的高性能和灵活性，是 Go 项目中日志记录的一个优秀选择。