logger

Logger

统一的日志记录接口和默认实现，支持多级别日志、动态级别控制和上下文字段传递。

特性

• 统一接口 - 定义了 Debug、Info、Warn、Error、Fatal 五个标准级别
• 灵活级别控制 - 支持运行时动态调整日志级别
• 上下文字段 - 通过 With 方法添加额外字段到日志中
• 序列化支持 - LogLevel 类型支持 YAML/JSON 序列化
• Zap 集成 - 提供与 uber-go/zap 框架的级别转换
• 多格式支持 - 支持 Gin、JSON、Default 三种日志格式

快速开始

基础使用

package main

import "github.com/lite-lake/litecore-go/logger"

func main() {
    // 创建日志记录器
    log := logger.NewDefaultLogger("MyService")

    // 设置日志级别
    log.SetLevel(logger.DebugLevel)

    // 记录各级别日志
    log.Debug("调试信息", "request_id", "12345")
    log.Info("操作成功", "user_id", 100)
    log.Warn("查询较慢", "duration", "500ms")
    log.Error("连接失败", "host", "example.com")

    // 使用 With 添加上下文字段
    log.With("service", "payment").Info("处理订单", "order_id", "1001")
}

框架集成使用

在框架中使用日志管理器：

type MessageService struct {
    LoggerMgr loggermgr.ILoggerManager `inject:""`
}

func (s *MessageService) CreateMessage(msg string) error {
    s.LoggerMgr.Ins().Info("创建消息", "content", msg)

    // 业务逻辑...

    s.LoggerMgr.Ins().Debug("消息创建完成", "id", 123)
    return nil
}

日志级别

日志级别从低到高依次为：Debug、Info、Warn、Error、Fatal。

设置某个级别后，只会记录该级别及以上的日志。

// 只记录 Error 及以上级别的日志
logger.SetLevel(logger.ErrorLevel)
logger.Debug("这条不会被记录")  // 0 < 3，不记录
logger.Info("这条不会被记录")   // 1 < 3，不记录
logger.Warn("这条不会被记录")   // 2 < 3，不记录
logger.Error("这条会被记录")    // 3 = 3，记录

日志格式

格式类型

Logger 支持 Gin、JSON、Default 三种输出格式：

Gin 格式特点

Gin 格式是默认的控制台输出格式，具有以下特点：

• 统一格式：{时间} | {级别} | {消息} | {字段1}={值1} {字段2}={值2} ...
• 时间固定宽度：2006-01-02 15:04:05.000（23 字符）
• 级别固定宽度：右对齐 5 字符（DEBUG、INFO 、WARN 、ERROR、FATAL）
• 字段格式：key=value，字符串值用引号包裹
• 颜色支持：自动检测终端支持，可手动配置

Gin 格式输出示例

// 普通日志输出
2026-01-24 15:04:05.123 | INFO  | 创建消息 | id=123 nickname="test"

// 请求日志输出（Gin 格式）
2026-01-24 15:04:05.123 | 200   | 1.234ms | 127.0.0.1 | GET | /api/messages
2026-01-24 15:04:05.456 | 404   | 0.456ms | 192.168.1.1 | POST | /api/unknown

配置方法

通过配置文件设置日志格式：

logger:
  driver: "zap"
  zap_config:
    console_enabled: true
    console_config:
      level: "info"                               # 日志级别：debug, info, warn, error, fatal
      format: "gin"                                # 格式：gin | json | default
      color: true                                  # 是否启用颜色
      time_format: "2006-01-02 15:04:05.000"     # 时间格式

颜色配置

• color: 控制是否启用彩色输出（默认 true，由终端自动检测）
• 支持在配置文件中手动关闭颜色：color: false

日志级别颜色

HTTP 状态码颜色

接口定义

type ILogger interface {
    Debug(msg string, args ...any)
    Info(msg string, args ...any)
    Warn(msg string, args ...any)
    Error(msg string, args ...any)
    Fatal(msg string, args ...any)
    With(args ...any) ILogger
    SetLevel(level LogLevel)
}

With 方法

With 方法返回一个新的 Logger 实例，带有额外的上下文字段。

// 基础使用
logger.With("request_id", "12345").Info("处理请求")

// 链式调用，累积字段
logger.With("service", "payment").
       With("version", "1.0").
       Info("服务启动", "port", 8080)

// 原始 Logger 不受影响
log1 := logger.With("key1", "value1")
log2 := logger.With("key2", "value2")  // log2 不包含 key1

日志级别解析

// 从字符串解析
level := logger.ParseLogLevel("debug")      // 返回 DebugLevel
level := logger.ParseLogLevel("INFO")        // 返回 InfoLevel
level := logger.ParseLogLevel("warning")     // 返回 WarnLevel
level := logger.ParseLogLevel("invalid")     // 返回默认的 InfoLevel

// 验证级别字符串是否有效
valid := logger.IsValidLogLevel("debug")   // true
valid := logger.IsValidLogLevel("invalid") // false

序列化支持

LogLevel 类型实现了 encoding.TextMarshaler 和 encoding.TextUnmarshaler 接口，可直接用于 YAML/JSON 配置。

// 序列化
level := logger.InfoLevel
data, _ := level.MarshalText()  // 返回 []byte("info")

// 反序列化
var level logger.LogLevel
level.UnmarshalText([]byte("debug"))  // level = DebugLevel

与 Zap 集成

import "go.uber.org/zap/zapcore"

// 将 LogLevel 转换为 zapcore.Level
zapLevel := logger.LogLevelToZap(logger.InfoLevel)
// zapLevel = zapcore.InfoLevel

// 将 zapcore.Level 转换为 LogLevel
logLevel := logger.ZapToLogLevel(zapcore.DebugLevel)
// logLevel = DebugLevel

自定义 Logger 实现

通过实现 ILogger 接口，可以创建自定义的日志记录器：

type MyLogger struct {
    // 你的字段
}

func (l *MyLogger) Debug(msg string, args ...any) {
    // 自定义实现
}

func (l *MyLogger) Info(msg string, args ...any) {
    // 自定义实现
}

// ... 实现其他接口方法

var _ logger.ILogger = (*MyLogger)(nil)

使用规范

日志级别选择

• Debug: 开发调试信息，生产环境通常关闭
• Info: 正常业务流程，如请求开始、资源创建
• Warn: 降级处理、慢查询、重试等需要注意但不影响功能的情况
• Error: 业务错误、操作失败，需要人工关注
• Fatal: 致命错误，需要立即终止程序

格式选择建议

• 开发环境：使用 Gin 格式（format: "gin"），颜色输出更易读
• 生产环境（控制台）：使用 JSON 格式（format: "json"），便于日志收集
• 生产环境（文件）：使用 Default 格式，日志轮转和压缩

字段传递规范

使用键值对方式传递字段：

// 推荐：结构化字段
logger.Info("用户登录", "user_id", 123, "ip", "192.168.1.1")

// 推荐：使用 With 添加公共字段
log := logger.With("service", "payment")
log.Info("处理订单", "order_id", "1001")
log.Error("支付失败", "order_id", "1002")

敏感信息处理

日志中不应包含密码、token、密钥等敏感信息：

// 不推荐
logger.Info("用户登录", "password", "secret123")

// 推荐
logger.Info("用户登录", "user_id", 123, "has_password", true)

API 参考

接口

函数

方法

配置参数