go-kit/src/logx/Error.go

package logx

import (
	"io"
	"os"

	"git.ooo.ink/root/go-kit/src/logx/tool"
	"github.com/rs/zerolog"
)

// 单例
var (
	errorLogger *zerolog.Logger
)

// InitErrorWriter 初始化 Error 级别的日志写入器
//
// 该函数创建一个专门用于处理错误级别日志的 zerolog 日志器实例。
// Error 日志器会自动包含错误堆栈信息，便于调试和问题追踪。
//
// 参数:
//
//	writer - 错误日志输出目标，通常是文件写入器或控制台
//
// 功能特性:
//   - 自动包含完整的错误堆栈信息（通过 zerolog.ErrorStackMarshaler 配置）
//   - 使用控制台格式输出，便于阅读和分析
//   - 禁用颜色输出，适合文件持久化存储
//   - 包含时间戳和调用者信息，便于问题定位
//   - 实现单例模式，全局共享错误日志器
//
// 使用示例:
//
//	// 创建错误日志文件写入器（推荐启用异步写入）
//	errorWriter := logx.DefaultWriter("error.log", true)
//
//	// 初始化 Error 日志器
//	logx.InitErrorWriter(errorWriter)
//
// 注意事项:
//   - 错误日志通常需要单独的文件存储，便于监控和告警
//   - 建议在生产环境中始终启用 Error 日志记录
//   - 错误堆栈信息需要在全局初始化时配置（参见 logx.InitDefault）
func InitErrorWriter(writer io.Writer) {
	// 创建配置完善的 zerolog 错误日志器：
	// - ConsoleWriter: 使用控制台格式，便于人类阅读错误信息
	// - Out: writer: 指定错误日志的输出目标
	// - NoColor: true: 禁用颜色输出，适合文件记录
	// - FormatTimestamp: 使用自定义时区格式化错误发生时间
	// - With().Timestamp(): 自动记录错误发生的时间戳
	// - With().Caller(): 包含错误发生的调用位置信息
	l := zerolog.New(zerolog.ConsoleWriter{
		Out:             writer,                                           // 错误日志输出目标
		NoColor:         true,                                             // 禁用颜色（适合文件记录）
		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
	}).With().Timestamp().Caller().Logger()

	// 存储单例实例，供全局错误记录使用
	// 后续调用 logx.Error() 时会使用这个预配置的错误日志器
	errorLogger = &l
}

// Error 返回一个 Error 级别的日志事件，用于记录错误信息
//
// 该函数实现了智能的错误日志器选择机制：
// 1. 如果已经通过 InitErrorWriter() 初始化了专用错误日志器，则使用该日志器
// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
//
// 返回值:
//
//	*zerolog.Event - 可用于链式调用的错误日志事件对象
//
// 使用方式:
//  1. 直接记录错误消息: logx.Error().Msg("错误描述")
//  2. 关联错误对象: logx.Error().Err(err).Msg("操作失败")
//  3. 添加错误上下文: logx.Error().Str("module", "auth").Int("code", 500).Send()
//
// 使用示例:
//
//	// 简单错误消息记录
//	logx.Error().Msg("数据库连接失败")
//
//	// 关联具体的错误对象
//	err := errors.New("权限验证失败")
//	logx.Error().Err(err).Msg("用户登录失败")
//
//	// 添加上下文信息
//	logx.Error().
//	    Str("endpoint", "/api/login").
//	    Int("status", 401).
//	    Any("request", req).
//	    Msg("认证失败")
//
// 最佳实践:
//   - 始终记录具体的错误对象（使用 .Err() 方法）
//   - 提供足够的上下文信息便于问题定位
//   - 生产环境中错误日志应该单独存储和监控
//   - 使用结构化字段而不是字符串拼接
func Error() *zerolog.Event {
	// 检查是否已经初始化了专用错误日志器
	// 如果已初始化，则使用预配置的错误日志器（通常指向单独的错误日志文件）
	if errorLogger != nil {
		return errorLogger.Error()
	}

	// 如果没有初始化专用错误日志器，创建临时控制台日志器作为回退
	// 这种设计确保即使没有显式初始化，错误日志也能正常工作
	// 控制台输出适合开发环境调试使用，启用颜色便于识别
	l := zerolog.New(zerolog.ConsoleWriter{
		Out:             os.Stdout,                                        // 输出到标准输出
		NoColor:         false,                                            // 启用颜色输出（便于控制台识别错误）
		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
	}).With().Timestamp().Caller().Logger() // 包含时间戳和调用者信息

	// 返回 Error 级别的日志事件，可以继续链式调用添加错误信息和上下文
	return l.Error()
}