go-kit/src/logx

Go-Kit Logx 日志库

基于 zerolog 构建的高性能、结构化 Go 语言日志库，支持文件滚动、异步写入和多种日志类型。

特性

• 🚀 高性能：基于 zerolog 的零分配日志记录
• 📁 文件滚动：自动日志文件轮转和备份管理
• ⚡ 异步写入：无锁、无阻塞的异步日志写入
• 🌍 时区支持：自定义时区格式化时间戳
• 🏷️ 多种日志类型：Info、Error、Debug、Gin、Gorm、Nano 等
• 🔧 灵活配置：支持自定义滚动和异步参数

安装

go get git.ooo.ink/root/go-kit/src/logx

快速开始

基本使用

package main

import "git.ooo.ink/root/go-kit/src/logx"

func main() {
    // 快速初始化（推荐）
    logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error", "debug")

    // 记录日志
    logx.Info().Msg("应用启动成功")
    logx.Error().Msg("发生了一个错误")
    logx.Debug().Any("data", map[string]interface{}{"key": "value"}).Send()
}

自定义配置

package main

import (
    "time"
    "git.ooo.ink/root/go-kit/src/logx"
)

func main() {
    // 自定义写入器配置
    config := logx.WriterConfig{
        Rolling: logx.WriterRollingConfig{
            MaxMegabytes: 10,    // 单文件最大 10MB
            MaxDays:      30,    // 保留 30 天
            MaxBackups:   50,    // 最多 50 个备份文件
            Compress:     true,  // 压缩备份文件
        },
        Async: &logx.WriterAsyncConfig{
            BufferSize:   5000,                    // 异步缓冲区大小
            PollInterval: time.Millisecond * 100,  // 轮询间隔
        },
    }

    // 创建写入器
    writer := logx.NewWriter("logs/app.log", config)

    // 初始化日志写入器
    logx.InitInfoWriter(writer)
    logx.InitErrorWriter(writer)

    // 使用日志
    logx.Info().Msg("自定义配置初始化完成")
}

API 文档

初始化函数

InitDefault(filePath, locationName string, useAsync bool, tags ...string)

快速初始化日志系统。

参数：

• filePath：日志文件路径前缀
• locationName：时区名称（如 "Asia/Shanghai"）
• useAsync：是否启用异步写入
• tags：要启用的日志类型标签（"info", "error", "debug", "gin", "gorm", "nano"）

示例：

logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error", "debug")

InitInfoWriter(writer io.Writer)

初始化 Info 日志写入器。

InitErrorWriter(writer io.Writer)

初始化 Error 日志写入器（支持错误堆栈）。

InitDebugWriter(writer io.Writer)

初始化 Debug 日志写入器。

InitGinWriter(writer io.Writer)

初始化 Gin 框架专用日志写入器。

InitGormWriter(writer io.Writer)

初始化 GORM 数据库操作日志写入器。

InitNanoWriter(writer io.Writer)

初始化微服务专用日志写入器。

日志记录函数

Info() *zerolog.Event

记录信息级别日志。

示例：

logx.Info().Msg("用户登录成功")
logx.Info().Str("username", "john").Int("age", 25).Send()

Error() *zerolog.Event

记录错误级别日志（自动包含错误堆栈）。

示例：

err := errors.New("数据库连接失败")
logx.Error().Err(err).Msg("操作失败")

Debug() *zerolog.Event

记录调试级别日志。

示例：

logx.Debug().Any("request", req).Msg("收到请求")

配置结构体

WriterConfig

日志写入器配置。

type WriterConfig struct {
    Rolling WriterRollingConfig  // 滚动配置
    Async   *WriterAsyncConfig   // 异步配置（可选）
}

WriterRollingConfig

文件滚动配置。

type WriterRollingConfig struct {
    MaxMegabytes int  // 单文件最大存储容量（兆字节）
    MaxDays      int  // 最大存储天数
    MaxBackups   int  // 最大备份文件数量
    Compress     bool // 备份文件是否压缩
}

WriterAsyncConfig

异步写入配置。

type WriterAsyncConfig struct {
    BufferSize   int           // 生产者缓冲区大小
    PollInterval time.Duration // 消费者轮询间隔
    Alerter      diode.Alerter // 丢弃告警函数
}

工具函数

DefaultWriter(fileName string, useAsync bool) io.Writer

创建默认配置的写入器。

默认配置：

• 滚动：1MB/文件，保留10天，10个备份，不压缩
• 异步：1000缓冲区（如果启用）

NewWriter(fileName string, c WriterConfig) io.Writer

根据配置创建新的写入器。

日志文件结构

使用 InitDefault 初始化后，会生成如下结构的日志文件：

logs/
├── app.info.log      # Info 级别日志
├── app.error.log     # Error 级别日志
├── app.debug.log     # Debug 级别日志
├── app.gin.log       # Gin 框架日志
├── app.gorm.log      # GORM 数据库日志
└── app.nano.log      # 微服务日志

日志格式

日志采用结构化格式，包含：

<timestamp> <level> <caller> <message> <fields>

示例输出：

CST 2024-01-15 10:30:25 INFO main.go:15 用户登录成功 username=john age=25
CST 2024-01-15 10:30:26 ERROR main.go:20 数据库操作失败 error="connection timeout"

性能优化

异步写入

启用异步写入可以显著提高日志记录性能，防止日志 I/O 阻塞主程序：

logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error")

合理的滚动配置

根据应用需求调整滚动参数：

config := logx.WriterConfig{
    Rolling: logx.WriterRollingConfig{
        MaxMegabytes: 100,  // 大文件减少文件数量
        MaxDays:      7,    // 短期保留节省空间
        MaxBackups:   10,   // 控制备份数量
        Compress:     true, // 压缩节省磁盘空间
    },
}

最佳实践

1. 生产环境：启用异步写入和文件压缩
2. 开发环境：可以禁用异步以便实时查看日志
3. 错误日志：始终启用 Error 日志以捕获异常堆栈
4. 敏感信息：避免在日志中记录密码、密钥等敏感信息
5. 日志级别：根据环境调整日志级别（生产环境可关闭 Debug）

故障排除

常见问题

Q: 日志文件没有生成？ A: 检查文件路径权限，确保应用有写入权限。

Q: 异步写入丢失日志？ A: 增大 BufferSize 或减少 PollInterval。

Q: 时区显示不正确？ A: 确认 locationName 参数使用正确的时区名称。

调试模式

可以临时启用控制台输出进行调试：

// 不初始化文件写入器，使用标准输出
logx.Info().Msg("调试信息")

依赖项

• zerolog - 高性能日志库
• lumberjack - 日志文件轮转
• zerolog/diode - 异步写入器

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！