jimmy/go-common

Fork 0

Files

Jimmy Xue de8fc13f18 日志方法增加异步与同步的方法

2025-11-30 21:01:47 +08:00

8.3 KiB

Raw Blame History

日志工具文档

概述

日志工具提供了统一的日志记录功能，使用Go标准库实现，无需第三方依赖。

功能特性

支持多种日志级别（debug, info, warn, error）
支持多种输出方式（stdout, stderr, file, both）
支持日志文件自动创建
支持日志前缀
支持禁用时间戳
支持带字段的日志记录
支持异步/同步日志模式（默认同步）
使用配置工具统一管理配置

使用方法

1. 从配置创建日志记录器（推荐）

import (
    "git.toowon.com/jimmy/go-common/config"
    "git.toowon.com/jimmy/go-common/factory"
)

// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
    log.Fatal(err)
}

// 使用工厂创建日志记录器（已初始化，可直接使用）
fac := factory.NewFactory(cfg)
logger, err := fac.GetLogger()
if err != nil {
    log.Fatal(err)
}

// 直接使用
logger.Info("Application started")
logger.Error("Failed to connect: %v", err)

2. 直接创建日志记录器

import (
    "git.toowon.com/jimmy/go-common/config"
    "git.toowon.com/jimmy/go-common/logger"
)

// 从配置获取日志配置
cfg, _ := config.LoadFromFile("./config.json")
loggerConfig := cfg.GetLogger()

// 创建日志记录器
logger, err := logger.NewLogger(loggerConfig)
if err != nil {
    log.Fatal(err)
}

// 使用默认配置（如果loggerConfig为nil）
logger, err := logger.NewLogger(nil)

3. 基本日志记录

// 记录不同级别的日志
logger.Debug("Debug message: %s", "debug info")
logger.Info("Info message: %s", "info")
logger.Warn("Warning message: %s", "warning")
logger.Error("Error message: %s", "error")

// 致命错误（会退出程序）
logger.Fatal("Fatal error: %s", "fatal")

// 恐慌错误（会触发panic）
logger.Panic("Panic error: %s", "panic")

4. 带字段的日志记录

// 记录带字段的日志
fields := map[string]interface{}{
    "user_id": 123,
    "action": "login",
}
logger.Infof(fields, "User logged in")
logger.Errorf(fields, "Failed to process request")

5. 异步/同步模式

同步模式（默认）

// 配置中不设置async或设置为false，使用同步模式
// 同步模式：日志直接写入，会阻塞调用方直到写入完成
logger.Info("This is a synchronous log")

异步模式

// 配置中设置async为true，使用异步模式
// 异步模式：日志写入通过channel异步处理，不阻塞调用方
// 配置文件示例：
// {
//   "logger": {
//     "async": true,
//     "bufferSize": 1000
//   }
// }

// 使用异步模式时，程序退出前需要调用Close()确保所有日志写入完成
defer logger.Close()

logger.Info("This is an asynchronous log")

注意：

Fatal 和 Panic 方法始终使用同步模式，确保日志写入后再退出/panic
异步模式下，程序退出前应调用 Close() 方法，确保所有日志写入完成
如果channel已满，会自动降级为同步写入，避免丢失日志

API 参考

NewLogger(cfg config.LoggerConfig) (Logger, error)

创建日志记录器。

参数：

cfg: 日志配置对象（如果为nil，使用默认配置）

返回： 日志记录器实例和错误信息

(l *Logger) Debug(format string, v ...interface{})

记录调试日志。

(l *Logger) Info(format string, v ...interface{})

记录信息日志。

(l *Logger) Warn(format string, v ...interface{})

记录警告日志。

(l *Logger) Error(format string, v ...interface{})

记录错误日志。

(l *Logger) Fatal(format string, v ...interface{})

记录致命错误日志并退出程序。

(l *Logger) Panic(format string, v ...interface{})

记录恐慌日志并触发panic。

(l *Logger) Debugf(fields map[string]interface{}, format string, v ...interface{})

记录调试日志（带字段）。

(l *Logger) Infof(fields map[string]interface{}, format string, v ...interface{})

记录信息日志（带字段）。

(l *Logger) Warnf(fields map[string]interface{}, format string, v ...interface{})

记录警告日志（带字段）。

(l *Logger) Errorf(fields map[string]interface{}, format string, v ...interface{})

记录错误日志（带字段）。

(l *Logger) Close() error

优雅关闭logger（仅异步模式需要）。

说明：

等待所有日志写入完成后再返回
同步模式下调用此方法会立即返回，无需等待
程序退出前应调用此方法，确保所有日志写入完成

配置说明

日志配置通过 config.LoggerConfig 提供：

字段	类型	说明	默认值
Level	string	日志级别: debug, info, warn, error	info
Output	string	输出方式: stdout, stderr, file, both	stdout
FilePath	string	日志文件路径（当output为file或both时必需）	-
Prefix	string	日志前缀	-
DisableTimestamp	bool	禁用时间戳	false
Async	bool	是否使用异步模式	false（同步）
BufferSize	int	异步模式下的缓冲区大小	1000

配置示例

输出到标准输出

{
  "logger": {
    "level": "info",
    "output": "stdout",
    "prefix": "app"
  }
}

输出到文件

{
  "logger": {
    "level": "debug",
    "output": "file",
    "filePath": "./logs/app.log",
    "prefix": "app"
  }
}

同时输出到标准输出和文件

{
  "logger": {
    "level": "info",
    "output": "both",
    "filePath": "./logs/app.log",
    "prefix": "app",
    "disableTimestamp": false
  }
}

异步模式配置

{
  "logger": {
    "level": "info",
    "output": "file",
    "filePath": "./logs/app.log",
    "prefix": "app",
    "async": true,
    "bufferSize": 1000
  }
}