FastLog - 高性能 Go 日志库

FastLog 是一个高性能的 Go 日志库，面向生产可用与易用性设计。当前实现采用带缓冲写入与定时刷新（BufferedWriter + FlushInterval），提供严格的配置校验、丰富的日志级别与格式、灵活的输出目标，以及完善的日志轮转与清理支持。配套提供开发/生产/终端三种便捷模式构造函数，便于快速在不同场景落地。

🌟 核心特性

⚙️ 写入与配置

带缓冲写入 + 定时刷新：支持 FlushInterval、MaxBufferSize、MaxWriteCount，兼顾吞吐与时延
轮转与清理：支持 MaxSize/MaxAge/MaxFiles、LocalTime、Compress；Async 控制是否异步清理旧日志（默认同步）
严格配置校验：validateConfig 对不合理配置直接 panic（含输出目标、格式上下界、文件输出前置条件等）
输出目标：文件与控制台可独立开启/关闭，终端输出可配色与加粗（Color/Bold）
调用者信息：可选输出调用文件/函数/行号（CallerInfo）

📊 日志能力

日志级别：DEBUG / INFO / WARN / ERROR / FATAL（位掩码组合与过滤）
输出格式：Def / Json / Timestamp / KVFmt / LogFmt / Custom（Custom 需外部自定义格式化）
使用方式：标准库 fmt 风格（Info/Debug/Warn/Error/Fatal 与 Infof/Debugf/Warnf/Errorf/Fatalf）与键值对字段日志（InfoF/DebugF/WarnF/ErrorF/FatalF + 字段构造器：String/Int/Int64/Float64/Bool/Time/Duration/Uint*/Error）

🔧 开发友好设计

便捷模式构造函数：
- DevConfig：开发模式（Def、DEBUG、短期保留：MaxAge=7/MaxFiles=5）
- ProdConfig：生产模式（Json、压缩、禁用控制台、长期保留：MaxAge=30/MaxFiles=24）
- ConsoleConfig：终端模式（仅控制台、DEBUG、无需文件路径）
完整测试：覆盖高并发性能、格式多样性、Fatal/Fatalf 子进程行为等
简洁 API：通过 NewFastLogConfig + NewFLog 组合使用

📦 安装与引入

# 确保在项目路径下存在 go.mod 文件
go get gitee.com/MM-Q/fastlog

import "gitee.com/MM-Q/fastlog"

🚀 快速开始

最简单的使用方式

如果你不想配置复杂的参数，可以直接使用默认日志记录器：

package main

import "gitee.com/MM-Q/fastlog"

func main() {
    // 获取默认日志记录器（开箱即用）
    logger := fastlog.Default()
    defer logger.Close()

    // 直接使用
    logger.Info("程序启动成功")
    logger.Debugf("用户 %s 登录成功，IP: %s", "张三", "192.168.1.1")
    logger.Warn("内存使用率较高: 85%")
    logger.Error("数据库连接失败")
}

基础使用示例

package main

import "gitee.com/MM-Q/fastlog"

func main() {
    // 创建日志配置
    config := fastlog.NewFastLogConfig("logs", "app.log")

    // 创建日志实例
    logger := fastlog.NewFLog(config)
    defer logger.Close()

    // 记录不同级别的日志
    logger.Debug("这是调试信息")
    logger.Info("这是一条信息日志")
    logger.Warn("这是一个警告")
    logger.Error("发生了一个错误")
  
    // 使用格式化方法
    logger.Infof("用户 %s 登录成功，IP: %s", "张三", "192.168.1.1")
    logger.Errorf("数据库连接失败，重试次数: %d", 3)
}

键值对字段日志示例

package main

import (
    "errors"
    "gitee.com/MM-Q/fastlog"
)

func main() {
    cfg := fastlog.NewFastLogConfig("logs", "kv.log")
    logger := fastlog.NewFLog(cfg)
    defer logger.Close()

    // 使用键值对字段风格
    logger.InfoFields("用户登录成功",
        fastlog.String("username", "zhangsan"),
        fastlog.Int("age", 30),
        fastlog.Bool("vip", true),
    )

    err := errors.New("库存不足")
    logger.ErrorFields("下单失败",
        fastlog.String("orderId", "A123"),
        fastlog.Error("err", err),
    )
}

预设配置模式（推荐）

FastLog 提供了 3 种便捷模式构造函数，覆盖常见使用场景：

package main

import "gitee.com/MM-Q/fastlog"

func main() {
    // 方式1：使用默认日志记录器（最简单）
    logger := fastlog.Default()
    defer logger.Close()
    
    // 方式2：开发模式：文件+控制台、详细格式、彩色加粗、快速刷新
    devCfg := fastlog.DevConfig("logs", "dev.log")
    logger := fastlog.NewFLog(devCfg)
    defer logger.Close()

    // 方式3：生产模式：仅文件、结构化格式、压缩、长期保留
    // prodCfg := fastlog.ProdConfig("logs", "prod.log")
    
    // 方式4：终端模式：仅控制台、时间戳简洁格式、彩色加粗
    // consoleCfg := fastlog.ConsoleConfig()

    // 记录日志
    logger.Info("应用程序启动")
    logger.Debugf("用户ID: %d, 操作: %s", 12345, "登录")
    logger.Warn("内存使用率较高: 85%")
    logger.Error("数据库连接失败")
}

可用的预设配置模式

Default() - 默认模式：文件+控制台、默认格式、INFO级别、彩色加粗、按日期目录存放和按天轮转
DevConfig(logDir, logFile) - 开发模式：文件+控制台、Detailed、DEBUG、彩色加粗、FlushInterval≈200ms、短期保留（示例：MaxFiles=5 / MaxAge=7）
ProdConfig(logDir, logFile) - 生产模式：仅文件、Structured、INFO、无装饰、压缩、MaxSize=100MB、FlushInterval≈1s、长期保留（30天 / 24个）
ConsoleConfig() - 终端模式：仅控制台、Timestamp、DEBUG、彩色加粗、FlushInterval≈500ms（不写文件）

📝 日志格式

FastLog 支持6种不同的日志格式：

格式名称	枚举值	说明
Def	`fastlog.Def`	默认格式，包含时间、级别、文件、函数、行号等完整信息
Json	`fastlog.Json`	JSON 格式输出，便于日志分析和处理
Timestamp	`fastlog.Timestamp`	时间格式
KVFmt	`fastlog.KVFmt`	键值对格式
LogFmt	`fastlog.LogFmt`	日志格式
Custom	`fastlog.Custom`	自定义格式，直接输出原始消息

格式示例

1. Def 格式

2025-01-15T10:30:45 | INFO    | main.go:main:15 - 用户登录成功
2025-01-15T10:30:46 | ERROR   | database.go:Connect:23 - 数据库连接失败

2. JSON 格式

{"time":"2025-01-15T10:30:45","level":"INFO","caller":"main.go:main:15","message":"用户登录成功"}
{"time":"2025-01-15T10:30:46","level":"ERROR","caller":"database.go:Connect:23","message":"数据库连接失败"}

3. Timestamp 格式

2025-01-15T10:30:45 INFO  用户登录成功
2025-01-15T10:30:46 ERROR 数据库连接失败

4. KVFmt 键值对格式

time=2025-01-15T10:30:45 level=INFO message=用户登录成功
time=2025-01-15T10:30:46 level=ERROR message=数据库连接失败

5. LogFmt 日志格式

2025-01-15T10:30:45 [INFO ] 用户登录成功 [username=张三, age=30]
2025-01-15T10:30:46 [ERROR] database.go:Connect:23 数据库连接失败

6. Custom 格式

// 使用 Custom 格式时，直接输出传入的消息内容
logger.Info("自定义格式的日志消息")  // 输出: 自定义格式的日志消息

🎯 核心特性详解

同步写入与关闭

当前实现为同步写入，调用日志方法会直接格式化并写出到目标（文件/控制台）。
优雅关闭：Close 返回错误用于传递关闭阶段的异常；在测试中对 Close 的错误均进行显式处理，保证资源释放。

配置校验与安全

validateConfig 对关键字段进行严格校验：输出目标至少启用一个、级别/格式范围合法、大小/天数/数量不越界。
路径安全：对日志目录与文件名进行路径穿越检测（禁止包含“..”）。
可选项：支持本地时间命名与压缩轮转，便于生产环境长期保留。

日志轮转功能

FastLog 基于轮转参数支持常见的日志管理策略：

config := fastlog.NewFastLogConfig("logs", "app.log")
config.MaxSize = 10                          // 文件大小超过 10MB 时轮转
config.MaxAge = 7                            // 保留 7 天的日志文件
config.MaxFiles = 5                          // 最多保留 5 个备份文件
config.LocalTime = true                      // 使用本地时间命名
config.Compress = true                       // 启用压缩功能
config.DateDirLayout = true                  // 启用按日期目录存放轮转后的日志
config.RotateByDay = true                    // 启用按天轮转
config.CompressType = comprx.CompressTypeZip // 压缩类型

轮转后的日志文件命名格式示例：app_202501010301.log

💡 最佳实践

1. 日志级别使用建议

DEBUG: 仅在开发和调试时使用，包含详细的程序执行信息
INFO: 记录程序的正常运行信息，如启动、关闭、重要操作等
WARN: 记录警告信息，程序可以继续运行但需要注意
ERROR: 记录错误信息，程序遇到问题但可以恢复
FATAL: 记录致命错误，程序无法继续运行

2. 配置与性能建议

// 推荐：根据场景选择合适的预设配置
// 生产环境（仅文件、结构化、长期保留、压缩）
logger := fastlog.NewFLog(fastlog.ProdConfig("logs", "app.log"))

// 开发环境（文件+控制台、详细信息、彩色加粗、快速刷新）
logger := fastlog.NewFLog(fastlog.DevConfig("logs", "debug.log"))

// 终端环境（仅控制台、时间戳简洁格式、彩色加粗）
logger := fastlog.NewFLog(fastlog.ConsoleConfig())

// 自定义配置（在预设不满足需求时使用）
config := fastlog.NewFastLogConfig("logs", "app.log")
config.FlushInterval = 1 * time.Second    // 增加刷新间隔减少 IO（根据需求调整）
config.LogLevel = fastlog.INFO            // 生产环境避免 DEBUG 噪音
config.MaxSize = 100                      // 增大文件大小减少轮转频率

// 使用格式化方法，避免不必要的字符串拼接
logger.Infof("用户 %s 执行操作 %s", username, action)  // 推荐
// logger.Info("用户 " + username + " 执行操作 " + action)  // 不推荐

3. 错误处理建议

// 推荐：在关键位置使用 defer 并显式处理 Close 的错误（满足 errcheck）
func main() {
    logger := fastlog.NewFLog(config)
    defer func() {
        logger.Info("程序正在关闭...")
        if err := logger.Close(); err != nil {
            // 生产环境可记录到标准错误或告警系统
            // 此处简单打印或忽略均可根据需要处理
            _ = err
        }
    }()
  
    // 业务逻辑...
}

🔧 依赖信息

FastLog 依赖以下外部库（与 go.mod 保持一致）：

require (
    gitee.com/MM-Q/colorlib v1.3.2      // 终端颜色与样式
    gitee.com/MM-Q/logrotatex v1.2.3    // 日志文件轮转（大小/时间/数量、压缩、本地时间）
    gitee.com/MM-Q/comprx v0.1.6        // 压缩工具
    gitee.com/MM-Q/go-kit v0.0.13       // 常用工具集
)

colorlib：提供终端颜色输出与样式支持
logrotatex：提供日志文件轮转功能，支持按大小、时间和数量轮转，以及压缩与本地时间
comprx：提供压缩工具支持
go-kit：提供通用工具函数（如字符串/配置等）

📋 版本要求

Go 版本：1.25.0 或更高版本
操作系统：支持 Windows、Linux、macOS

❓ 常见问题

Q: 如何在生产环境中使用？

A: 建议在生产环境中：

设置日志级别为 INFO 或更高（避免 DEBUG 噪音）
使用 Structured 或 JSON 格式便于日志分析
禁用控制台输出，仅输出到文件（ProdConfig 默认如此）
配置合适的日志轮转策略（MaxSize/MaxAge/MaxFiles，建议启用压缩）

Q: 如何处理高并发场景？

A: 当前实现为同步写入，建议：

使用 ProdConfig("logs", "app.log")，开启压缩与结构化格式
将日志级别设为 INFO 或更高，减少无关日志
适度增大 FlushInterval（如 1s）与 MaxSize（如 100MB），降低 I/O 频率
采用结构化/JSON 格式，便于后续日志聚合与分析

Q: 日志文件过大怎么办？

A: 配置日志轮转参数：

config.MaxSize = 50      // 50MB 轮转（可根据场景调整为 100MB）
config.MaxAge = 7        // 保留 7 天
config.MaxFiles = 10     // 最多 10 个备份
config.Compress = true   // 启用压缩

Q: 如何自定义日志格式？

A: 使用 Custom 格式：

config.LogFormat = fastlog.Custom
logger.Info("自定义格式的消息")  // 直接输出原始消息

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

开发规范

遵循 Go 代码规范
添加必要的单元测试
更新相关文档
确保所有测试通过

📄 许可证

本项目采用 GPL 许可证 - 查看 LICENSE 文件了解详情。

📞 联系方式

项目主页：https://deepwiki.com/QiaoMuDe/fastlog
Gitee：https://gitee.com/MM-Q/fastlog
GitHub：https://github.com/QiaoMuDe/fastlog

📚 相关文档

API 文档 - 详细的 API 参考文档

FastLog - 让日志记录更简单、更高效！ 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 237 Commits
internal		internal
.gitignore		.gitignore
APIDOC.md		APIDOC.md
LICENSE		LICENSE
README.md		README.md
fastlog.go		fastlog.go
fastlog包快速使用指南.md		fastlog包快速使用指南.md
go.mod		go.mod
go.sum		go.sum
http.go		http.go
http_test.go		http_test.go

Folders and files

Latest commit

History

Repository files navigation

FastLog - 高性能 Go 日志库

🌟 核心特性

⚙️ 写入与配置

📊 日志能力

🔧 开发友好设计

📦 安装与引入

🚀 快速开始

最简单的使用方式

基础使用示例

键值对字段日志示例

预设配置模式（推荐）

可用的预设配置模式

📝 日志格式

格式示例

1. Def 格式

2. JSON 格式

3. Timestamp 格式

4. KVFmt 键值对格式

5. LogFmt 日志格式

6. Custom 格式

🎯 核心特性详解

同步写入与关闭

配置校验与安全

日志轮转功能

💡 最佳实践

1. 日志级别使用建议

2. 配置与性能建议

3. 错误处理建议

🔧 依赖信息

📋 版本要求

❓ 常见问题

Q: 如何在生产环境中使用？

Q: 如何处理高并发场景？

Q: 日志文件过大怎么办？

Q: 如何自定义日志格式？

🤝 贡献指南

开发规范

📄 许可证

📞 联系方式

📚 相关文档

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages