go-kit/src/logx/Gorm.go

package logx

import (
	"io"
	"os"

	"github.com/5-say/go-tool/logx/tool"
	"github.com/rs/zerolog"
	"gorm.io/gorm/logger"
)

// 单例
var (
	gormWriter logger.Writer
)

// InitGormWriter 初始化 GORM 框架专用的日志写入器
//
// 该函数创建一个专门用于 GORM 数据库操作日志的日志器实例，配置了适合 SQL 查询日志的格式。
// GORM 日志器会记录数据库操作的详细信息，包括 SQL 语句、执行时间等，便于数据库性能监控和调试。
//
// 参数:
//
//	writer - GORM 日志输出目标，通常是文件写入器或控制台
//
// 功能特性:
//   - 专门为 GORM 框架优化的日志格式
//   - 使用控制台格式输出，便于阅读 SQL 查询和执行信息
//   - 禁用颜色输出，适合文件持久化存储
//   - 包含时间戳信息，便于数据库操作的时间追踪
//   - 实现单例模式，全局共享 GORM 日志器
//
// 使用示例:
//
//	// 创建 GORM 日志文件写入器（推荐启用异步写入）
//	gormWriter := logx.DefaultWriter("gorm.log", true)
//
//	// 初始化 GORM 日志器
//	logx.InitGormWriter(gormWriter)
//
//	// 配置 GORM 使用自定义日志器
//	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
//	    Logger: logx.GormLogger(logger.Config{
//	        SlowThreshold: 200 * time.Millisecond,
//	        LogLevel:      logger.Warn,
//	    }),
//	})
//
// 注意事项:
//   - GORM 日志可能包含敏感信息（如 SQL 参数），生产环境中需谨慎处理
//   - 建议启用异步写入以提高数据库操作性能
//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
//   - 与标准日志不同，GORM 日志器不包含调用者信息，避免日志过于冗长
func InitGormWriter(writer io.Writer) {
	// 创建配置完善的 zerolog GORM 日志器：
	// - ConsoleWriter: 使用控制台格式，便于阅读 SQL 查询和执行信息
	// - Out: writer: 指定 GORM 日志的输出目标
	// - NoColor: true: 禁用颜色输出，适合文件记录
	// - FormatTimestamp: 使用自定义时区格式化数据库操作时间
	// - With().Timestamp(): 自动记录数据库操作的时间戳
	// 注意：GORM 日志器不包含调用者信息，避免 SQL 日志过于冗长
	l := zerolog.New(zerolog.ConsoleWriter{
		Out:             writer,                                           // GORM 日志输出目标
		NoColor:         true,                                             // 禁用颜色（适合文件记录）
		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
	}).With().Timestamp().Logger() // 仅包含时间戳，不包含调用者信息

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

// GormLogger 根据配置创建并返回 GORM 框架的日志器接口
//
// 该函数实现了智能的 GORM 日志器选择机制：
// 1. 如果已经通过 InitGormWriter() 初始化了专用 GORM 日志器，则基于该日志器创建 GORM 日志器
// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
//
// 参数:
//
//	config - GORM 日志配置，包含慢查询阈值、日志级别等参数
//
// 返回值:
//
//	logger.Interface - 符合 GORM 框架要求的日志器接口
//
// 主要用途:
//  1. 配置 GORM 数据库连接使用自定义日志器
//  2. 控制 GORM 的日志输出级别和格式
//  3. 监控数据库操作的性能和错误
//
// 使用示例:
//
//	db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
//	    Logger: logx.GormLogger(logger.Config{
//	        SlowThreshold:             200 * time.Millisecond, // 慢查询阈值
//	        IgnoreRecordNotFoundError: false,                 // 是否忽略记录未找到错误
//	        ParameterizedQueries:      false,                 // 是否参数化查询
//	        LogLevel:                  logger.Warn,           // 日志级别
//	    }),
//	})
//
// 配置参数说明:
//   - SlowThreshold: 慢查询阈值，超过该时间的查询会被记录为慢查询
//   - IgnoreRecordNotFoundError: 是否忽略 "记录未找到" 错误
//   - ParameterizedQueries: 是否在日志中显示参数化查询的具体参数
//   - LogLevel: 日志级别（Silent、Error、Warn、Info）
//
// 智能配置特性:
//   - 专用日志器模式: 禁用颜色输出（Colorful = false），适合文件记录
//   - 回退控制台模式: 启用颜色输出（Colorful = true），便于控制台调试
//   - 自动适配: 根据是否初始化专用日志器自动调整颜色配置
//
// 最佳实践:
//   - 生产环境建议使用专用文件日志器，并设置适当的日志级别
//   - 开发环境可以使用回退的控制台日志器进行 SQL 调试
//   - 根据应用需求调整慢查询阈值和日志级别
func GormLogger(config logger.Config) logger.Interface {
	// 检查是否已经初始化了专用 GORM 日志器
	// 如果已初始化，则基于预配置的日志器创建 GORM 日志器
	if gormWriter != nil {
		// 专用日志器模式下禁用颜色输出，适合文件记录
		config.Colorful = false
		// 创建符合 GORM 接口的日志器
		return logger.New(gormWriter, config)
	}

	// 如果没有初始化专用 GORM 日志器，创建临时控制台日志器作为回退
	// 控制台输出适合开发环境调试使用，启用颜色便于识别 SQL 查询类型
	l := zerolog.New(zerolog.ConsoleWriter{
		Out:             os.Stdout,                                        // 输出到标准输出
		NoColor:         false,                                            // 启用颜色输出（便于控制台识别）
		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
	}).With().Timestamp().Logger() // 包含时间戳信息

	// 回退模式下启用颜色输出，便于在控制台中区分不同类型的 SQL 日志
	config.Colorful = true

	// 创建符合 GORM 接口的日志器，使用临时控制台日志器
	return logger.New(&l, config)
}