Go zap日志

前言

感谢开源项目gin-vue-admin，以及1010工作室的教程，项目文档
我只是在跟着学习，然后记录下笔记而已，可能会有新的代码加入，但是本质还是跟着学习的一个过程。
这里记录的是开源项目的源码，感兴趣的可以直接撸源码去哈

zap创建实例

通过调用zap.NewProduction()/zap.NewDevelopment()或者zap.Example()创建一个Logger。这三个方法的区别在于它将记录的信息不同，参数只能是string类型

三种创建方式对比：

• Example和Production使用的是json格式输出，Development使用行的形式输出
• Development
• • 从警告级别向上打印到堆栈中来跟踪
• • 始终打印包/文件/行（方法）
• • 在行尾添加任何额外字段作为json字符串
• • 以大写形式打印级别名称
• • 以毫秒为单位打印ISO8601格式的时间戳
• Production
• • 调试级别消息不记录
• • Error,Dpanic级别的记录，会在堆栈中跟踪文件，Warn不会
• • 始终将调用者添加到文件中
• • 以时间戳格式打印日期
• • 以小写形式打印级别名称
    实际上不难发现，这官方自带的示例，其实在项目中并不具备太大的优势，因为在实际项目中，往往更喜欢采用高度定制化打印的zap.New()，自己去根据需要来定制打印格式

创建前 3 个logger时，zap会使用一些预定义的设置，它们的使用场景也有所不同。Example适合用在测试代码中，Development在开发环境中使用，Production用在生成环境。

定制zap打印日志格式

函数入口：

func Zap() (logger *zap.Logger)

PathExists()

检测文件目录是否存在
函数原型：

//@author: [piexlmax](https://github.com/piexlmax)
//@function: PathExists
//@description: 文件目录是否存在
//@param: path string
//@return: bool, error

func PathExists(path string) (bool, error) {
	_, err := os.Stat(path)
	if err == nil {
		return true, nil
	}
	if os.IsNotExist(err) {
		return false, nil
	}
	return false, err
}

在这里主要用到了两个基础函数
os.Stat(path)实现读取当前输入路径的文件信息，如果成功则返回FileInfo，失败则返回err。
os.IsNotExist(err)实现根据操作文件时发生的错误，判断这个目录是否存在，目录存在(但打开错误)返回True，目录不存在(当然打开失败)返回False。

os.Stat(path)

函数原型：

// Stat returns a FileInfo describing the named file.
// If there is an error, it will be of type *PathError.
func Stat(name string) (FileInfo, error) {
	testlog.Stat(name)
	return statNolog(name)
}

描述：
Stat返回描述命名文件的FileInfo。如果有错误，则类型为*PathError。

os.IsNotExist(err)

函数原型：

// IsNotExist returns a boolean indicating whether the error is known to
// report that a file or directory does not exist. It is satisfied by
// ErrNotExist as well as some syscall errors.
//
// This function predates errors.Is. It only supports errors returned by
// the os package. New code should use errors.Is(err, os.ErrNotExist).
func IsNotExist(err error) bool {
	return underlyingErrorIs(err, ErrNotExist)
}

描述：
IsNotExist返回一个布尔值，指示是否已知报告文件或目录不存在的错误。ErrNotExist以及一些系统调用错误都满足了这一要求。

此函数早于errors.Is。它只支持操作系统包返回的错误。新代码应该使用errors.Is（err，os.ErrNotExist）。

os.Mkdir()

函数原型：

// Mkdir creates a new directory with the specified name and permission
// bits (before umask).
// If there is an error, it will be of type *PathError.
func Mkdir(name string, perm FileMode) error {
	if runtime.GOOS == "windows" && isWindowsNulName(name) {
		return &PathError{Op: "mkdir", Path: name, Err: syscall.ENOTDIR}
	}
	longName := fixLongPath(name)
	e := ignoringEINTR(func() error {
		return syscall.Mkdir(longName, syscallMode(perm))
	})

	if e != nil {
		return &PathError{Op: "mkdir", Path: name, Err: e}
	}

	// mkdir(2) itself won't handle the sticky bit on *BSD and Solaris
	if !supportsCreateWithStickyBit && perm&ModeSticky != 0 {
		e = setStickyBit(name)

		if e != nil {
			Remove(name)
			return e
		}
	}

	return nil
}

描述：
Mkdir使用指定的名称和权限位（在umask之前）创建一个新目录。如果有错误，则类型为*PathError。

zap.New

函数原型：

// New constructs a new Logger from the provided zapcore.Core and Options. If
// the passed zapcore.Core is nil, it falls back to using a no-op
// implementation.
//
// This is the most flexible way to construct a Logger, but also the most
// verbose. For typical use cases, the highly-opinionated presets
// (NewProduction, NewDevelopment, and NewExample) or the Config struct are
// more convenient.
//
// For sample code, see the package-level AdvancedConfiguration example.
func New(core zapcore.Core, options ...Option) *Logger {
	if core == nil {
		return NewNop()
	}
	log := &Logger{
		core:        core,
		errorOutput: zapcore.Lock(os.Stderr),
		addStack:    zapcore.FatalLevel + 1,
	}
	return log.WithOptions(options...)
}

//New从提供的zapcore.Core和Options构建一个新的记录器。如果传递的zapcore.Core为nil，则返回使用no op。

//这是构造记录器最灵活的方法，但也是最冗长的方法。对于典型用例，高度预设的（NewProduction、NewDevelopment和NewExample）或配置结构更为方便。

getEncoderCore()

函数原型：

// getEncoderCore 获取Encoder的zapcore.Core
func getEncoderCore() (core zapcore.Core) {
	writer, err := utils.GetWriteSyncer() // 使用file-rotatelogs进行日志分割
	if err != nil {
		fmt.Printf("Get Write Syncer Failed err:%v", err.Error())
		return
	}
	return zapcore.NewCore(getEncoder(), writer, level)
}

zap logger中加入file-rotatelogs

GetWriteSyncer

函数原型：

//@author: [SliverHorn](https://github.com/SliverHorn)
//@function: GetWriteSyncer
//@description: zap logger中加入file-rotatelogs
//@return: zapcore.WriteSyncer, error

func GetWriteSyncer() (zapcore.WriteSyncer, error) {
	fileWriter, err := zaprotatelogs.New(
		path.Join(global.GVA_CONFIG.Zap.Director, "%Y-%m-%d.log"),
		zaprotatelogs.WithMaxAge(7*24*time.Hour),
		zaprotatelogs.WithRotationTime(24*time.Hour),
	)
	if global.GVA_CONFIG.Zap.LogInConsole {
		return zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(fileWriter)), err
	}
	return zapcore.AddSync(fileWriter), err
}

其中zaprotatelogs是如下的库别名

zaprotatelogs "github.com/lestrrat-go/file-rotatelogs"

file-rotatelogs.New()

New函数原型

// New creates a new RotateLogs object. A log filename pattern
// must be passed. Optional `Option` parameters may be passed
func New(p string, options ...Option) (*RotateLogs, error) {
	globPattern := p
	for _, re := range patternConversionRegexps {
		globPattern = re.ReplaceAllString(globPattern, "*")
	}

	pattern, err := strftime.New(p)
	if err != nil {
		return nil, errors.Wrap(err, `invalid strftime pattern`)
	}

	var clock Clock = Local
	rotationTime := 24 * time.Hour
	var rotationCount uint
	var linkName string
	var maxAge time.Duration
	var handler Handler
	var forceNewFile bool

	for _, o := range options {
		switch o.Name() {
		case optkeyClock:
			clock = o.Value().(Clock)
		case optkeyLinkName:
			linkName = o.Value().(string)
		case optkeyMaxAge:
			maxAge = o.Value().(time.Duration)
			if maxAge < 0 {
				maxAge = 0
			}
		case optkeyRotationTime:
			rotationTime = o.Value().(time.Duration)
			if rotationTime < 0 {
				rotationTime = 0
			}
		case optkeyRotationCount:
			rotationCount = o.Value().(uint)
		case optkeyHandler:
			handler = o.Value().(Handler)
		case optkeyForceNewFile:
			forceNewFile = true
		}
	}

	if maxAge > 0 && rotationCount > 0 {
		return nil, errors.New("options MaxAge and RotationCount cannot be both set")
	}

	if maxAge == 0 && rotationCount == 0 {
		// if both are 0, give maxAge a sane default
		maxAge = 7 * 24 * time.Hour
	}

	return &RotateLogs{
		clock:         clock,
		eventHandler:  handler,
		globPattern:   globPattern,
		linkName:      linkName,
		maxAge:        maxAge,
		pattern:       pattern,
		rotationTime:  rotationTime,
		rotationCount: rotationCount,
		forceNewFile:  forceNewFile,
	}, nil
}

通过注释可以发现这个函数主要是新建一个回滚日志对象，必须指定日志文件的名称，还可以传递可选的’Option’参数

path.Join

这个用大与在python内的是一致的，都是根据输入来拼接成一个路径，例如下面所示的效果

fmt.Println(path.Join("c:", "aa", "bb", "cc.txt"))         //c:/aa/bb/cc.txt

设置WithMaxAge

函数原型：

// WithMaxAge creates a new Option that sets the
// max age of a log file before it gets purged from
// the file system.
func WithMaxAge(d time.Duration) Option {
	return option.New(optkeyMaxAge, d)
}

会创建一个新选项，用于设置日志文件在从文件系统中清除之前的最大保存时间。

设置WithRotationTime

函数原型：

// WithRotationTime creates a new Option that sets the
// time between rotation.
func WithRotationTime(d time.Duration) Option {
	return option.New(optkeyRotationTime, d)
}

会创建一个新选项，用于设置回滚间隔时间。

• 输入控制台及文件判断
  这是是这样实现的：

if global.GVA_CONFIG.Zap.LogInConsole {
		return zapcore.NewMultiWriteSyncer(zapcore.AddSync(os.Stdout), zapcore.AddSync(fileWriter)), err
	}
	return zapcore.AddSync(fileWriter), err

通过global.GVA_CONFIG.Zap.LogInConsole代表的配置项进行判断，如果打开的终端打印就将文件句柄和终端句柄一同返回，否则只返回文件句柄

NewMultiWriteSyncer函数原型：

// NewMultiWriteSyncer creates a WriteSyncer that duplicates its writes
// and sync calls, much like io.MultiWriter.
func NewMultiWriteSyncer(ws ...WriteSyncer) WriteSyncer {
	if len(ws) == 1 {
		return ws[0]
	}
	// Copy to protect against https://github.com/golang/go/issues/7809
	return multiWriteSyncer(append([]WriteSyncer(nil), ws...))
}

创建一个WriteSync复制其写入和同步调用，与io.MultiWriter非常相似。可以理解为一个读写的句柄
AddSync函数原型

// AddSync converts an io.Writer to a WriteSyncer. It attempts to be
// intelligent: if the concrete type of the io.Writer implements WriteSyncer,
// we'll use the existing Sync method. If it doesn't, we'll add a no-op Sync.
func AddSync(w io.Writer) WriteSyncer {
	switch w := w.(type) {
	case WriteSyncer:
		return w
	default:
		return writerWrapper{w}
	}
}

AddSync将io.Writer转换为WriteSync。它试图实现智能化：如果io.Writer的具体类型实现WriteSyncer，我们将使用现有的同步方法。如果没有，我们将添加一个无操作同步。

zapcore.NewCore

函数原型：

// NewCore creates a Core that writes logs to a WriteSyncer.
func NewCore(enc Encoder, ws WriteSyncer, enab LevelEnabler) Core {
	return &ioCore{
		LevelEnabler: enab,
		enc:          enc,
		out:          ws,
	}
}

NewCore创建将日志写入WriteSyncer的Core

getEncoder()

函数原型：

// getEncoder 获取zapcore.Encoder
func getEncoder() zapcore.Encoder {
	if global.GVA_CONFIG.Zap.Format == "json" {
		return zapcore.NewJSONEncoder(getEncoderConfig())
	}
	return zapcore.NewConsoleEncoder(getEncoderConfig())
}

zapcore.NewJSONEncoder()

函数原型：

// NewJSONEncoder creates a fast, low-allocation JSON encoder. The encoder
// appropriately escapes all field keys and values.
//
// Note that the encoder doesn't deduplicate keys, so it's possible to produce
// a message like
//   {"foo":"bar","foo":"baz"}
// This is permitted by the JSON specification, but not encouraged. Many
// libraries will ignore duplicate key-value pairs (typically keeping the last
// pair) when unmarshaling, but users should attempt to avoid adding duplicate
// keys.
func NewJSONEncoder(cfg EncoderConfig) Encoder {
	return newJSONEncoder(cfg, false)
}

函数说明：
NewJSONEncoder创建了一个快速、低分配的JSON编码器。编码器适当地转义所有字段键和值。
请注意，编码器不会消除重复键，因此可以生成类似{“foo”：“bar”，“foo”：“baz”}的消息
JSON规范允许这样做，但不鼓励这样做。在解组时，用户应尝试避免添加重复密钥。

zapcore.NewConsoleEncoder()

函数原型：

// NewConsoleEncoder creates an encoder whose output is designed for human -
// rather than machine - consumption. It serializes the core log entry data
// (message, level, timestamp, etc.) in a plain-text format and leaves the
// structured context as JSON.
//
// Note that although the console encoder doesn't use the keys specified in the
// encoder configuration, it will omit any element whose key is set to the empty
// string.
func NewConsoleEncoder(cfg EncoderConfig) Encoder {
	return consoleEncoder{newJSONEncoder(cfg, true)}
}

函数说明：
NewConsoleEncoder创建了一个编码器，其输出是为人类而不是机器消费而设计的。它以纯文本格式序列化核心日志条目数据（消息、级别、时间戳等），并将结构化上下文保留为JSON。

请注意，尽管控制台编码器不使用编码器配置中指定的键，但它将忽略键设置为空字符串的任何元素。

getEncoderConfig()
函数原型：

// getEncoderConfig 获取zapcore.EncoderConfig
func getEncoderConfig() (config zapcore.EncoderConfig) {
	config = zapcore.EncoderConfig{
		MessageKey:     "message",
		LevelKey:       "level",
		TimeKey:        "time",
		NameKey:        "logger",
		CallerKey:      "caller",
		StacktraceKey:  global.GVA_CONFIG.Zap.StacktraceKey,
		LineEnding:     zapcore.DefaultLineEnding,
		EncodeLevel:    zapcore.LowercaseLevelEncoder,
		EncodeTime:     CustomTimeEncoder,
		EncodeDuration: zapcore.SecondsDurationEncoder,
		EncodeCaller:   zapcore.FullCallerEncoder,
	}
	switch {
	case global.GVA_CONFIG.Zap.EncodeLevel == "LowercaseLevelEncoder": // 小写编码器(默认)
		config.EncodeLevel = zapcore.LowercaseLevelEncoder
	case global.GVA_CONFIG.Zap.EncodeLevel == "LowercaseColorLevelEncoder": // 小写编码器带颜色
		config.EncodeLevel = zapcore.LowercaseColorLevelEncoder
	case global.GVA_CONFIG.Zap.EncodeLevel == "CapitalLevelEncoder": // 大写编码器
		config.EncodeLevel = zapcore.CapitalLevelEncoder
	case global.GVA_CONFIG.Zap.EncodeLevel == "CapitalColorLevelEncoder": // 大写编码器带颜色
		config.EncodeLevel = zapcore.CapitalColorLevelEncoder
	default:
		config.EncodeLevel = zapcore.LowercaseLevelEncoder
	}
	return config
}

函数说明：
得到配置项

zap.AddStacktrace()

函数原型：

// AddStacktrace configures the Logger to record a stack trace for all messages at
// or above a given level.
func AddStacktrace(lvl zapcore.LevelEnabler) Option {
	return optionFunc(func(log *Logger) {
		log.addStack = lvl
	})
}

AddStacktrace将记录器配置为记录给定级别或以上的所有消息的堆栈跟踪。

WithOptions

函数原型：

// WithOptions clones the current Logger, applies the supplied Options, and
// returns the resulting Logger. It's safe to use concurrently.
func (log *Logger) WithOptions(opts ...Option) *Logger {
	c := log.clone()
	for _, opt := range opts {
		opt.apply(c)
	}
	return c
}

函数描述：
WithOptions克隆当前记录器，应用提供的选项，并返回结果记录器。同时使用是安全的。

zap.AddCaller()

函数原型：

// AddCaller configures the Logger to annotate each message with the filename
// and line number of zap's caller.
func AddCaller() Option {
	return optionFunc(func(log *Logger) {
		log.addCaller = true
	})
}

函数描述：
AddCaller将记录器配置为使用zap调用者的文件名和行号注释每条消息。