go-kit/src/logx/writer.Gin.go

package logx

import (
	"io"
	"os"

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

// 单例
var (
	ginWriter io.Writer
)

// InitGinWriter 初始化 Gin 框架专用的日志写入器
//
// 该函数创建一个专门用于 Gin Web 框架的日志器实例，配置了适合 HTTP 请求日志的格式。
// Gin 日志器会记录请求的详细信息，包括时间戳、调用者信息，便于 Web 请求的监控和调试。
//
// 参数:
//
//	writer - Gin 日志输出目标，通常是文件写入器或控制台
//
// 功能特性:
//   - 专门为 Gin 框架优化的日志格式
//   - 使用控制台格式输出，便于阅读 HTTP 请求信息
//   - 禁用颜色输出，适合文件持久化存储
//   - 包含时间戳和调用者信息，便于请求追踪
//   - 实现单例模式，全局共享 Gin 日志器
//
// 使用示例:
//
//	// 创建 Gin 日志文件写入器（推荐启用异步写入）
//	ginWriter := logx.DefaultWriter("gin.log", true)
//
//	// 初始化 Gin 日志器
//	logx.InitGinWriter(ginWriter)
//
//	// 配置 Gin 框架使用自定义日志器
//	gin.DefaultWriter = logx.GinWriter()
//	gin.DefaultErrorWriter = logx.GinWriter()
//
// 注意事项:
//   - Gin 日志通常包含大量的请求信息，建议启用异步写入提高性能
//   - 生产环境中 Gin 日志应该单独存储，便于监控 API 性能
//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
func InitGinWriter(writer io.Writer) {
	// 创建配置完善的 zerolog Gin 日志器：
	// - ConsoleWriter: 使用控制台格式，便于阅读 HTTP 请求信息
	// - Out: writer: 指定 Gin 日志的输出目标
	// - NoColor: true: 禁用颜色输出，适合文件记录
	// - FormatTimestamp: 使用自定义时区格式化请求时间
	// - With().Timestamp(): 自动记录请求发生的时间戳
	// - With().Caller(): 包含请求处理的调用位置信息
	l := zerolog.New(zerolog.ConsoleWriter{
		Out:             writer,                                           // Gin 日志输出目标
		NoColor:         true,                                             // 禁用颜色（适合文件记录）
		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
	}).With().Timestamp().Caller().Logger()

	// 存储单例实例，供全局 Gin 日志记录使用
	// 后续调用 logx.GinWriter() 时会返回这个预配置的日志器
	ginWriter = l
}

// GinWriter 返回配置好的 Gin 框架日志写入器
//
// 该函数实现了智能的 Gin 日志器选择机制：
// 1. 如果已经通过 InitGinWriter() 初始化了专用 Gin 日志器，则返回该日志器
// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
//
// 返回值:
//
//	io.Writer - 符合 Gin 框架要求的日志写入器接口
//
// 主要用途:
//  1. 设置 Gin 框架的标准输出日志器: gin.DefaultWriter = logx.GinWriter()
//  2. 设置 Gin 框架的错误输出日志器: gin.DefaultErrorWriter = logx.GinWriter()
//  3. 自定义 Gin 路由器的日志输出
//
// 使用示例:
//
//	// 配置 Gin 框架使用自定义日志器
//	gin.DefaultWriter = logx.GinWriter()
//	gin.DefaultErrorWriter = logx.GinWriter()
//
//	// 创建 Gin 路由器（将使用配置的日志器）
//	r := gin.Default()
//
//	// 或者创建自定义配置的路由器
//	r := gin.New()
//	r.Use(gin.LoggerWithWriter(logx.GinWriter()))
//
// 功能特性:
//   - 智能选择：优先使用预配置的专用日志器，无配置时回退到控制台
//   - 控制台格式：输出格式便于阅读 HTTP 请求和响应信息
//   - 颜色支持：启用颜色输出，便于在控制台中区分不同类型的日志
//   - 完整信息：包含时间戳、调用者信息，便于请求追踪
//
// 最佳实践:
//   - 生产环境中建议先调用 InitGinWriter() 初始化专用文件日志器
//   - 开发环境可以使用回退的控制台日志器进行调试
//   - Gin 日志通常信息量大，建议配合异步写入器使用
func GinWriter() io.Writer {
	// 检查是否已经初始化了专用 Gin 日志器
	// 如果已初始化，则返回预配置的日志器（通常指向文件或其他持久化存储）
	if ginWriter != nil {
		return ginWriter
	}

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