go-kit/src/logx/Info.go

package logx

import (
	"io"
	"os"

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

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

// InitInfoWriter 初始化 Info 级别的日志写入器
//
// 该函数创建一个专门用于处理信息级别日志的 zerolog 日志器实例。
// Info 日志器用于记录应用程序的正常运行状态、业务操作信息等常规日志。
//
// 参数:
//
//	writer - 信息日志输出目标，可以是文件、控制台或其他实现了 io.Writer 接口的对象
//
// 功能特性:
//   - 使用控制台格式输出，便于人类阅读和分析
//   - 禁用颜色输出（NoColor: true），适合文件持久化存储
//   - 自动包含时间戳，使用配置的时区格式化
//   - 包含调用者信息（文件名和行号），便于问题定位
//   - 实现单例模式，全局共享同一个日志器实例
//
// 使用示例:
//
//	// 使用默认配置创建异步文件写入器
//	writer := logx.DefaultWriter("info.log", true)
//
//	// 初始化 Info 日志器
//	logx.InitInfoWriter(writer)
//
// 注意事项:
//   - 该函数应该在应用程序启动时调用一次
//   - 如果多次调用，后一次的配置会覆盖前一次
//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
//   - Info 日志通常包含业务操作信息，建议单独存储便于分析
func InitInfoWriter(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.Info() 时会使用这个预配置的日志器
	infoLogger = &l
}

// Info 返回一个 Info 级别的日志事件，用于记录常规信息
//
// 该函数实现了智能的日志器选择机制：
// 1. 如果已经通过 InitInfoWriter() 初始化了专用信息日志器，则使用该日志器
// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
//
// 返回值:
//
//	*zerolog.Event - 可用于链式调用的信息日志事件对象
//
// 使用方式:
//  1. 直接记录消息: logx.Info().Msg("业务操作完成")
//  2. 添加结构化字段: logx.Info().Str("user", "john").Int("count", 10).Send()
//  3. 记录业务数据: logx.Info().Any("order", orderData).Send()
//
// 使用示例:
//
//	// 简单信息记录
//	logx.Info().Msg("用户登录成功")
//
//	// 带结构化字段的记录
//	logx.Info().
//	    Str("username", "john").
//	    Int("loginCount", 5).
//	    Msg("用户登录统计")
//
//	// 记录业务数据
//	logx.Info().
//	    Any("request", req).
//	    Any("response", resp).
//	    Send()
//
// 最佳实践:
//   - 使用 Info 日志记录应用程序的正常运行状态和业务操作
//   - 生产环境中 Info 日志应该单独存储，便于业务分析
//   - 使用结构化字段而不是字符串拼接，便于日志分析和查询
//   - 避免在 Info 日志中记录敏感信息
func Info() *zerolog.Event {
	// 检查是否已经初始化了专用信息日志器
	// 如果已初始化，则使用预配置的日志器（通常指向文件或其他持久化存储）
	if infoLogger != nil {
		return infoLogger.Info()
	}

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

	// 返回 Info 级别的日志事件，可以继续链式调用添加字段和消息
	return l.Info()
}