logger

package
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 5 Imported by: 0

README

logger 日志包

基于 zap + lumberjack 的日志封装:一份配置同时完成日志级别、输出格式、多目标输出(控制台 / 滚动文件)与全局句柄初始化。

特性

  • 包级直用:logger.Info("...") / logger.Infof(...) 全套包级函数,无需先取 L / S 句柄;Init 前内置 stderr 兜底句柄,未初始化直接打日志也不会 nil panic 或丢日志
  • 多输出核:同一份日志可同时写入滚动文件与标准输出,全未配置时兜底输出到 stderr,避免日志静默丢失
  • 滚动归档:基于 lumberjack,按大小切分,支持保留天数、备份数量与 gzip 压缩
  • 全局替换:初始化后替换 zap 全局句柄,全项目可直接用 zap.L() / zap.S(),database 的 gorm SQL 日志同样经此输出
  • 调用信息:自动附带 caller,Error 及以上级别自动记录堆栈
  • 可读时间:自定义 yyyy-MM-dd HH:mm:ss.sss 时间格式,console 模式级别大写醒目

快速开始

package main

import (
	"go.uber.org/zap"

	"gitee.com/usmos/basic-go/logger"
)

func main() {
	err := logger.Init(logger.LogConfig{
		Level:    "info",
		Format:   logger.FormatConsole, // console | json
		Filename: "logs/app.log",
		MaxSize:  100, // MB, 超过切分
		MaxAge:   30,  // 保留 30 天
		Compress: true,
		Console:  true, // 同时输出到控制台
	})
	if err != nil {
		panic(err)
	}
	defer logger.Sync() // 进程退出前刷新缓冲

	// 包级函数直接打日志
	logger.Info("user login", zap.String("user", "note")) // 结构化(性能更好)
	logger.Infof("listen on %d", 8080)                     // 格式化(易用)

	// 句柄仍可直接使用: L 结构化 / S 格式化
	logger.L.Info("via logger.L")
	logger.S.Infof("via logger.S: %d", 8080)

	// 全局替换后, 任意位置 zap.L() 均生效(含 database 的 SQL 日志)
	zap.L().Warn("via zap.L()")
}

与 config 配合,从配置文件加载:

var root struct {
	Log logger.LogConfig `yaml:"log"`
}
cfg, _ := config.New("yaml", config.WithFile("config.yaml"))
_ = cfg.UnmarshalWithDefault(&root)
_ = logger.Init(root.Log)

对应配置文件(字段名与标签一致,注意 maxSize 等为驼峰):

log:
  level: info          # debug/info/warn/error/dpanic/panic/fatal
  format: console      # console | json
  filename: logs/app.log
  maxSize: 100         # 单文件 MB, 超过切分
  maxAge: 30           # 旧日志保留天数
  maxBackups: 10       # 旧日志保留份数
  compress: true       # 旧日志 gzip 压缩
  console: true        # 是否同时输出到控制台

配置字段

见 logger.go 的 LogConfig:

字段 类型 默认行为 说明
level string 非法值回退 info 日志级别
format string 未知值回退 console 输出格式,见 FormatConsole / FormatJSON
filename string 空 = 不写文件 日志文件路径
maxSize int 0 = 不按大小切分 单文件大小上限(MB)
maxAge int 0 = 不限 旧日志保留天数
maxBackups int 0 = 不限 旧日志保留份数
compress bool false 旧日志是否 gzip 压缩
console bool false 是否同时输出到标准输出

输出目标组合:

filename console 实际输出
有值 true 滚动文件 + stdout 双写
有值 false 仅滚动文件
空 true 仅 stdout
空 false 兜底 stderr(防止日志丢失)

接口总览

标识符 说明
Init(cfg) 按配置初始化全局日志,替换 zap.L() / zap.S()
Sync() 刷新缓冲区日志,进程退出前调用
Info / Infof 等包级函数 直接打日志免取句柄;Debug / Info / Warn / Error / DPanic / Panic / Fatal 各级齐全,f 后缀为格式化版
L 全局 *zap.Logger,结构化 API
S 全局 *zap.SugaredLogger,格式化 API
LogConfig 日志配置结构体,带 yaml / toml / json / mapstructure 标签
FormatConsole / FormatJSON 输出格式常量

注意事项

  • 未初始化兜底:跳过 Init 直接打日志不会 panic,走内置标准错误句柄(info 级别、console 格式);Init 后切换为配置输出
  • 初始化顺序:先 logger.Init 再连接数据库(database 的 gorm 日志器经 zap.L() 输出),否则 SQL 日志不落配置的目标
  • Sync 时机:defer logger.Sync() 放在 main 入口;控制台输出不支持 fsync,Sync 内部已忽略该类错误
  • 性能建议:高频路径用强类型版(logger.Info(msg, zap.String(...)),零分配),低频/调试路径用格式化版(logger.Infof);句柄 L / S 仍可直接使用
  • 切割时钟:滚动文件使用本地时间(LocalTime: true),按天保留的旧日志文件名后缀为本地日期

Documentation

Overview

Package logger 提供基于 zap + lumberjack 的日志封装。

一份配置(LogConfig)同时完成日志级别、输出格式、多目标输出(控制台/滚动文件)与 全局句柄初始化; Init 后替换 zap 全局句柄, 全项目可直接使用 zap.L()/zap.S(), database 包的 gorm SQL 日志同样经此输出。

打日志直接用包级函数, 无需先取 L/S 句柄; Init 之前调用同样安全 (内置标准错误兜底句柄, 日志不会静默丢失):

logger.Info("user login", zap.String("user", "note")) // 结构化日志
logger.Infof("listen on %d", 8080)                    // 格式化日志

使用示例:

err := logger.Init(logger.LogConfig{
	Level:   "info",
	Format:  logger.FormatConsole, // console | json
	Console: true,
})
if err != nil {
	panic(err)
}
defer logger.Sync() // 进程退出前刷新缓冲

Index

Constants

View Source
const (
	FormatConsole = "console"
	FormatJSON    = "json"
)

日志输出格式,由 log.format 配置

Variables

View Source
var (
	// L 全局日志句柄; Init 之前为标准错误兜底句柄, 未初始化直接使用也不会 nil panic
	L = defaultLogger()
	// S 全局 sugared 日志句柄, 随 L 一起在 Init 时重建
	S = L.Sugar()
)

Functions

func DPanic added in v1.0.2

func DPanic(msg string, fields ...zap.Field)

DPanic 输出 dpanic 级别日志; 开发模式下 panic。

func DPanicf added in v1.0.2

func DPanicf(template string, args ...any)

DPanicf 输出 dpanic 级别格式化日志; 开发模式下 panic。

func Debug added in v1.0.2

func Debug(msg string, fields ...zap.Field)

Debug 输出 debug 级别日志。

func Debugf added in v1.0.2

func Debugf(template string, args ...any)

Debugf 输出 debug 级别格式化日志。

func Error added in v1.0.2

func Error(msg string, fields ...zap.Field)

Error 输出 error 级别日志。

func Errorf added in v1.0.2

func Errorf(template string, args ...any)

Errorf 输出 error 级别格式化日志。

func Fatal added in v1.0.2

func Fatal(msg string, fields ...zap.Field)

Fatal 输出 fatal 级别日志, 随后 os.Exit(1)。

func Fatalf added in v1.0.2

func Fatalf(template string, args ...any)

Fatalf 输出 fatal 级别格式化日志, 随后 os.Exit(1)。

func Info added in v1.0.2

func Info(msg string, fields ...zap.Field)

Info 输出 info 级别日志。

func Infof added in v1.0.2

func Infof(template string, args ...any)

Infof 输出 info 级别格式化日志。

func Init

func Init(cfg LogConfig) error

Init 根据配置初始化全局日志并替换兜底句柄,进程退出前需调用 Sync

func Panic added in v1.0.2

func Panic(msg string, fields ...zap.Field)

Panic 输出 panic 级别日志, 随后 panic。

func Panicf added in v1.0.2

func Panicf(template string, args ...any)

Panicf 输出 panic 级别格式化日志, 随后 panic。

func Sync

func Sync()

Sync 刷新缓冲区日志

func Warn added in v1.0.2

func Warn(msg string, fields ...zap.Field)

Warn 输出 warn 级别日志。

func Warnf added in v1.0.2

func Warnf(template string, args ...any)

Warnf 输出 warn 级别格式化日志。

Types

type LogConfig

type LogConfig struct {
	Level      string `yaml:"level" toml:"level" json:"level" mapstructure:"level"`
	Format     string `yaml:"format" toml:"format" json:"format" mapstructure:"format"`
	Filename   string `yaml:"filename" toml:"filename" json:"filename" mapstructure:"filename"`
	MaxSize    int    `yaml:"maxSize" toml:"maxSize" json:"maxSize" mapstructure:"maxSize"`
	MaxAge     int    `yaml:"maxAge" toml:"maxAge" json:"maxAge" mapstructure:"maxAge"`
	MaxBackups int    `yaml:"maxBackups" toml:"maxBackups" json:"maxBackups" mapstructure:"maxBackups"`
	Compress   bool   `yaml:"compress" toml:"compress" json:"compress" mapstructure:"compress"`
	Console    bool   `yaml:"console" toml:"console" json:"console" mapstructure:"console"`
}

LogConfig 日志配置

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL