1

src/logx/Error.go

@@ -13,27 +13,105 @@ var (
 	errorLogger *zerolog.Logger
 )
 
-// InitErrorWriter
+// InitErrorWriter 初始化 Error 级别的日志写入器
 //
-// e.g.
+// 该函数创建一个专门用于处理错误级别日志的 zerolog 日志器实例。
+// Error 日志器会自动包含错误堆栈信息，便于调试和问题追踪。
 //
-//	logx.InitErrorWriter(logx.DefaultWriter("error.log", true))
+// 参数:
+//
+//	writer - 错误日志输出目标，通常是文件写入器或控制台
+//
+// 功能特性:
+//   - 自动包含完整的错误堆栈信息（通过 zerolog.ErrorStackMarshaler 配置）
+//   - 使用控制台格式输出，便于阅读和分析
+//   - 禁用颜色输出，适合文件持久化存储
+//   - 包含时间戳和调用者信息，便于问题定位
+//   - 实现单例模式，全局共享错误日志器
+//
+// 使用示例:
+//
+//	// 创建错误日志文件写入器（推荐启用异步写入）
+//	errorWriter := logx.DefaultWriter("error.log", true)
+//
+//	// 初始化 Error 日志器
+//	logx.InitErrorWriter(errorWriter)
+//
+// 注意事项:
+//   - 错误日志通常需要单独的文件存储，便于监控和告警
+//   - 建议在生产环境中始终启用 Error 日志记录
+//   - 错误堆栈信息需要在全局初始化时配置（参见 logx.InitDefault）
 func InitErrorWriter(writer io.Writer) {
-	l := zerolog.New(zerolog.ConsoleWriter{Out: writer, NoColor: true, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Caller().Logger()
-	// 存储单例
+	// 创建配置完善的 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 返回一个 Error 级别的日志事件，用于记录错误信息
+//
+// 该函数实现了智能的错误日志器选择机制：
+// 1. 如果已经通过 InitErrorWriter() 初始化了专用错误日志器，则使用该日志器
+// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
 //
-// e.g.
+// 返回值:
 //
-//	logx.Error().Msg("")
-//	logx.Error().Any("data", data).Send()
+//	*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()
+
+	// 如果没有初始化专用错误日志器，创建临时控制台日志器作为回退
+	// 这种设计确保即使没有显式初始化，错误日志也能正常工作
+	// 控制台输出适合开发环境调试使用，启用颜色便于识别
+	l := zerolog.New(zerolog.ConsoleWriter{
+		Out:             os.Stdout,                                        // 输出到标准输出
+		NoColor:         false,                                            // 启用颜色输出（便于控制台识别错误）
+		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
+	}).With().Timestamp().Caller().Logger() // 包含时间戳和调用者信息
+
+	// 返回 Error 级别的日志事件，可以继续链式调用添加错误信息和上下文
 	return l.Error()
 }

src/logx/Gin.go

@@ -13,27 +13,108 @@ var (
 	ginWriter io.Writer
 )
 
-// InitGinWriter
+// InitGinWriter 初始化 Gin 框架专用的日志写入器
 //
-// e.g.
+// 该函数创建一个专门用于 Gin Web 框架的日志器实例，配置了适合 HTTP 请求日志的格式。
+// Gin 日志器会记录请求的详细信息，包括时间戳、调用者信息，便于 Web 请求的监控和调试。
 //
-//	logx.InitGinWriter(logx.DefaultWriter("gin.log", true))
+// 参数:
+//
+//	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.InitDefault() 或设置 loggingLocationName 以确保时区正确
 func InitGinWriter(writer io.Writer) {
-	l := zerolog.New(zerolog.ConsoleWriter{Out: writer, NoColor: true, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Caller().Logger()
-	// 存储单例
+	// 创建配置完善的 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
+// GinWriter 返回配置好的 Gin 框架日志写入器
 //
-// e.g.
+// 该函数实现了智能的 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
 	}
-	return zerolog.New(zerolog.ConsoleWriter{Out: os.Stdout, NoColor: false, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Caller().Logger()
+
+	// 如果没有初始化专用 Gin 日志器，创建临时控制台日志器作为回退
+	// 这种设计确保即使没有显式初始化，Gin 框架也能正常使用日志功能
+	// 控制台输出适合开发环境调试使用，启用颜色便于识别不同类型的日志
+	return zerolog.New(zerolog.ConsoleWriter{
+		Out:             os.Stdout,                                        // 输出到标准输出
+		NoColor:         false,                                            // 启用颜色输出（便于控制台识别）
+		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
+	}).With().Timestamp().Caller().Logger() // 包含时间戳和调用者信息
 }

src/logx/Gorm.go

@@ -14,33 +14,128 @@ var (
 	gormWriter logger.Writer
 )
 
-// InitGormWriter
+// InitGormWriter 初始化 GORM 框架专用的日志写入器
 //
-// e.g.
+// 该函数创建一个专门用于 GORM 数据库操作日志的日志器实例，配置了适合 SQL 查询日志的格式。
+// GORM 日志器会记录数据库操作的详细信息，包括 SQL 语句、执行时间等，便于数据库性能监控和调试。
 //
-//	logx.InitGormWriter(logx.DefaultWriter("gorm.log", true))
+// 参数:
+//
+//	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) {
-	l := zerolog.New(zerolog.ConsoleWriter{Out: writer, NoColor: true, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Logger()
-	// 存储单例
+	// 创建配置完善的 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
+// GormLogger 根据配置创建并返回 GORM 框架的日志器接口
+//
+// 该函数实现了智能的 GORM 日志器选择机制：
+// 1. 如果已经通过 InitGormWriter() 初始化了专用 GORM 日志器，则基于该日志器创建 GORM 日志器
+// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
+//
+// 参数:
 //
-// e.g.
+//	config - GORM 日志配置，包含慢查询阈值、日志级别等参数
 //
-//	logx.GormLogger(logger.Config{
-//		SlowThreshold:             200 * time.Millisecond,
-//		IgnoreRecordNotFoundError: false,
-//		ParameterizedQueries:      false,
-//		LogLevel:                  logger.Warn,
+// 返回值:
+//
+//	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)
 	}
-	l := zerolog.New(zerolog.ConsoleWriter{Out: os.Stdout, NoColor: false, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Logger()
+
+	// 如果没有初始化专用 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)
 }

src/logx/Info.go

@@ -13,27 +13,107 @@ var (
 	infoLogger *zerolog.Logger
 )
 
-// InitInfoWriter
+// InitInfoWriter 初始化 Info 级别的日志写入器
 //
-// e.g.
+// 该函数创建一个专门用于处理信息级别日志的 zerolog 日志器实例。
+// Info 日志器用于记录应用程序的正常运行状态、业务操作信息等常规日志。
 //
-//	logx.InitInfoWriter(logx.DefaultWriter("info.log", true))
+// 参数:
+//
+//	writer - 信息日志输出目标，可以是文件、控制台或其他实现了 io.Writer 接口的对象
+//
+// 功能特性:
+//   - 使用控制台格式输出，便于人类阅读和分析
+//   - 禁用颜色输出（NoColor: true），适合文件持久化存储
+//   - 自动包含时间戳，使用配置的时区格式化
+//   - 包含调用者信息（文件名和行号），便于问题定位
+//   - 实现单例模式，全局共享同一个日志器实例
+//
+// 使用示例:
+//
+//	// 使用默认配置创建异步文件写入器
+//	writer := logx.DefaultWriter("info.log", true)
+//
+//	// 初始化 Info 日志器
+//	logx.InitInfoWriter(writer)
+//
+// 注意事项:
+//   - 该函数应该在应用程序启动时调用一次
+//   - 如果多次调用，后一次的配置会覆盖前一次
+//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - Info 日志通常包含业务操作信息，建议单独存储便于分析
 func InitInfoWriter(writer io.Writer) {
-	l := zerolog.New(zerolog.ConsoleWriter{Out: writer, NoColor: true, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Caller().Logger()
-	// 存储单例
+	// 创建配置完善的 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 返回一个 Info 级别的日志事件，用于记录常规信息
+//
+// 该函数实现了智能的日志器选择机制：
+// 1. 如果已经通过 InitInfoWriter() 初始化了专用信息日志器，则使用该日志器
+// 2. 如果没有初始化，则创建一个临时的控制台输出日志器作为回退方案
 //
-// e.g.
+// 返回值:
 //
-//	logx.Info().Msg("")
-//	logx.Info().Any("data", data).Send()
+//	*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()
 	}
-	l := zerolog.New(zerolog.ConsoleWriter{Out: os.Stdout, NoColor: false, FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName)}).With().Timestamp().Caller().Logger()
+
+	// 如果没有初始化专用日志器，创建临时控制台日志器作为回退
+	// 这种设计确保即使没有显式初始化，Info 日志也能正常工作
+	// 控制台输出适合开发环境调试使用，启用颜色便于识别
+	l := zerolog.New(zerolog.ConsoleWriter{
+		Out:             os.Stdout,                                        // 输出到标准输出
+		NoColor:         false,                                            // 启用颜色输出（便于控制台识别）
+		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
+	}).With().Timestamp().Caller().Logger() // 包含时间戳和调用者信息
+
+	// 返回 Info 级别的日志事件，可以继续链式调用添加字段和消息
 	return l.Info()
 }

src/logx/Nano.go

@@ -11,17 +11,145 @@ import (
 
 type nanoLogger struct{}
 
+// Println 实现标准日志接口的 Println 方法，用于记录信息级别的微服务日志
+//
+// 该方法提供了智能的日志级别检查和性能优化：
+// 1. 首先检查 Info 级别的日志是否启用，避免不必要的字符串格式化开销
+// 2. 如果 Info 级别已启用，才执行字符串格式化和日志记录操作
+//
+// 参数:
+//
+//	v - 可变参数，支持任意类型的日志内容
+//
+// 功能特性:
+//   - 性能优化：先检查日志级别，避免不必要的字符串格式化
+//   - 调用栈调整：跳过1层调用栈，准确定位日志调用位置
+//   - 自动格式化：使用 fmt.Sprint 自动格式化各种类型参数
+//   - 级别控制：遵循配置的日志级别，支持动态启用/禁用
+//
+// 使用示例:
+//
+//	logger := logx.NanoLogger()
+//	logger.Println("微服务启动完成")
+//	logger.Println("用户ID:", userID, "操作:", "登录")
+//	logger.Println("请求参数:", req, "响应:", resp)
+//
+// 性能优化说明:
+//   - e.Enabled() 检查可以避免在日志级别禁用时执行昂贵的字符串格式化
+//   - 这种设计特别适合高频调用的微服务日志场景
+//   - 在生产环境中，当 Info 级别被禁用时，此方法几乎无性能开销
+//
+// 调用栈调整:
+//   - CallerSkipFrame(1) 跳过当前方法本身的调用栈帧
+//   - 确保日志显示的是调用 Println 的代码位置，而不是此方法内部
 func (nanoLogger) Println(v ...interface{}) {
+	// 获取 Info 级别的日志事件，并检查该级别是否启用
+	// 这种设计避免在日志级别禁用时执行不必要的字符串格式化操作
 	if e := nanoWriter.Info(); e.Enabled() {
+		// 跳过当前方法本身的调用栈帧（CallerSkipFrame(1)）
+		// 确保日志显示的调用位置是实际业务代码的位置
+		// 使用 fmt.Sprint 自动格式化所有参数为字符串
 		e.CallerSkipFrame(1).Msg(fmt.Sprint(v...))
 	}
 }
 
+// Fatal 实现标准日志接口的 Fatal 方法，用于记录致命错误并终止程序
+//
+// 该方法用于处理无法恢复的严重错误，记录错误信息后会立即终止应用程序。
+// 在微服务架构中，Fatal 日志通常表示服务遇到了不可恢复的致命问题。
+//
+// 参数:
+//
+//	v - 可变参数，支持任意类型的致命错误信息
+//
+// 功能特性:
+//   - 立即终止：记录日志后立即调用 os.Exit(1) 终止程序
+//   - 自动格式化：使用 fmt.Sprint 自动格式化各种类型参数
+//   - 致命级别：使用 Fatal 级别记录，便于监控系统识别
+//   - 微服务适配：专为微服务环境优化的致命错误处理
+//
+// 使用示例:
+//
+//	logger := logx.NanoLogger()
+//
+//	// 数据库连接失败，无法继续运行
+//	if err := connectDatabase(); err != nil {
+//	    logger.Fatal("数据库连接失败:", err)
+//	}
+//
+//	// 关键配置缺失，服务无法启动
+//	if config.APIKey == "" {
+//	    logger.Fatal("API密钥配置缺失，服务无法启动")
+//	}
+//
+// 注意事项:
+//   - Fatal 方法会立即终止程序，请谨慎使用
+//   - 仅在遇到不可恢复的致命错误时使用
+//   - 确保在调用 Fatal 前已经记录了足够的错误上下文信息
+//   - 微服务环境中，监控系统应该对 Fatal 日志进行告警
+//
+// 与 Panic 的区别:
+//   - Fatal: 记录日志后立即终止程序（os.Exit(1)）
+//   - Panic: 抛出异常，可以被 recover 捕获和处理
 func (nanoLogger) Fatal(v ...interface{}) {
+	// 使用 Fatal 级别的日志事件记录致命错误信息
+	// Fatal 级别会自动调用 os.Exit(1) 终止应用程序
+	// 使用 fmt.Sprint 自动格式化所有参数为字符串
 	nanoWriter.Fatal().Msg(fmt.Sprint(v...))
 }
 
+// Fatalf 实现标准日志接口的 Fatalf 方法，用于格式化记录致命错误并终止程序
+//
+// 该方法与 Fatal 方法类似，但支持格式化字符串，便于记录结构化的致命错误信息。
+// 在微服务架构中，Fatalf 用于记录包含具体错误代码、状态等详细信息的致命错误。
+//
+// 参数:
+//
+//	format - 格式化字符串模板，支持标准 fmt 包占位符
+//	v - 可变参数，用于填充格式化字符串的占位符
+//
+// 功能特性:
+//   - 立即终止：记录日志后立即调用 os.Exit(1) 终止程序
+//   - 格式化支持：支持使用格式化字符串模板记录结构化错误信息
+//   - 致命级别：使用 Fatal 级别记录，便于监控系统识别
+//   - 微服务适配：专为微服务环境优化的格式化致命错误处理
+//
+// 使用示例:
+//
+//	logger := logx.NanoLogger()
+//
+//	// 数据库连接失败，包含具体错误代码
+//	if err := connectDatabase(); err != nil {
+//	    logger.Fatalf("数据库连接失败，错误码: %d, 错误信息: %s", err.Code, err.Message)
+//	}
+//
+//	// 配置验证失败，包含具体配置项
+//	if !validateConfig(config) {
+//	    logger.Fatalf("配置验证失败，缺失配置项: %s，当前环境: %s", missingKey, env)
+//	}
+//
+//	// 服务端口被占用
+//	if err := startServer(port); err != nil {
+//	    logger.Fatalf("服务启动失败，端口 %d 已被占用，错误: %v", port, err)
+//	}
+//
+// 格式化占位符支持:
+//   - %s: 字符串
+//   - %d: 整数
+//   - %f: 浮点数
+//   - %v: 默认格式
+//   - %+v: 详细格式（包含结构体字段名）
+//   - 其他标准 fmt 包支持的占位符
+//
+// 注意事项:
+//   - Fatalf 方法会立即终止程序，请谨慎使用
+//   - 仅在遇到不可恢复的致命错误时使用
+//   - 格式化字符串可以包含具体的错误代码、状态等详细信息
+//   - 微服务环境中，监控系统应该对 Fatalf 日志进行告警和分析
 func (nanoLogger) Fatalf(format string, v ...interface{}) {
+	// 使用 Fatal 级别的日志事件记录格式化致命错误信息
+	// Fatal 级别会自动调用 os.Exit(1) 终止应用程序
+	// 使用 Msgf 方法支持格式化字符串模板
 	nanoWriter.Fatal().Msgf(format, v...)
 }
 
@@ -30,17 +158,56 @@ var (
 	nanoWriter *zerolog.Logger
 )
 
-// InitNanoWriter
+// InitNanoWriter 初始化微服务专用的日志写入器
 //
-// e.g.
+// 该函数创建一个专门用于微服务架构的日志器实例，配置了适合分布式系统日志的格式。
+// Nano 日志器特别优化了调用栈信息，便于在微服务环境中追踪跨服务调用链。
+//
+// 参数:
+//
+//	writer - 微服务日志输出目标，通常是文件写入器或控制台
+//
+// 功能特性:
+//   - 专门为微服务架构优化的日志格式
+//   - 使用控制台格式输出，便于阅读分布式系统日志
+//   - 禁用颜色输出，适合文件持久化存储
+//   - 包含时间戳和精确的调用者信息
+//   - 跳过多层调用栈（CallerWithSkipFrameCount(3)），准确定位业务代码位置
+//   - 实现单例模式，全局共享微服务日志器
+//
+// 使用示例:
+//
+//	// 创建微服务日志文件写入器（推荐启用异步写入）
+//	nanoWriter := logx.DefaultWriter("nano.log", true)
+//
+//	// 初始化微服务日志器
+//	logx.InitNanoWriter(nanoWriter)
+//
+//	// 获取微服务日志器接口
+//	logger := logx.NanoLogger()
 //
-//	logx.InitNanoWriter(logx.DefaultWriter("nano.log", true))
+// 注意事项:
+//   - 微服务日志通常需要包含完整的调用链信息，便于分布式追踪
+//   - CallerWithSkipFrameCount(3) 确保跳过框架内部调用，准确定位业务代码
+//   - 建议在生产环境中启用异步写入以提高微服务性能
+//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
 func InitNanoWriter(writer io.Writer) {
+	// 创建配置完善的 zerolog 微服务日志器：
+	// - ConsoleWriter: 使用控制台格式，便于阅读分布式系统日志
+	// - Out: writer: 指定微服务日志的输出目标
+	// - NoColor: true: 禁用颜色输出，适合文件记录
+	// - FormatTimestamp: 使用自定义时区格式化日志时间
+	// - With().Timestamp(): 自动记录日志时间戳
+	// - With().Caller(): 包含基础调用者信息
+	// - With().CallerWithSkipFrameCount(3): 跳过3层调用栈，准确定位业务代码位置
 	l := zerolog.New(zerolog.ConsoleWriter{
-		Out: writer, NoColor: true,
-		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName),
+		Out:             writer,                                           // 微服务日志输出目标
+		NoColor:         true,                                             // 禁用颜色（适合文件记录）
+		FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
 	}).With().Timestamp().Caller().CallerWithSkipFrameCount(3).Logger()
-	// 存储单例
+
+	// 存储单例实例，供全局微服务日志记录使用
+	// 后续通过 nanoLogger 结构体的方法使用这个预配置的日志器
 	nanoWriter = &l
 }
 
@@ -48,15 +215,61 @@ func InitNanoWriter(writer io.Writer) {
 //
 // e.g.
 //
+// # NanoLogger 返回微服务专用的日志器接口
+//
+// 该函数实现了智能的微服务日志器初始化机制：
+// 1. 如果已经通过 InitNanoWriter() 初始化了专用微服务日志器，则直接返回 nanoLogger 实例
+// 2. 如果没有初始化，则自动创建一个临时的控制台输出日志器作为回退方案
+//
+// 返回值:
+//
+//	nanoLogger - 实现了标准日志接口的微服务日志器
+//
+// 主要用途:
+//  1. 为微服务框架提供兼容的日志器接口
+//  2. 确保即使没有显式初始化，微服务也能正常使用日志功能
+//  3. 支持分布式系统中的日志记录和追踪
+//
+// 使用示例:
+//
+//	// 配置微服务框架使用自定义日志器
 //	nano.WithLogger(logx.NanoLogger())
+//
+// 功能特性:
+//   - 懒加载初始化：首次调用时自动创建日志器实例
+//   - 智能回退：无专用配置时使用控制台输出作为回退
+//   - 颜色支持：启用颜色输出便于控制台调试
+//   - 精确调用栈：跳过3层调用栈，准确定位业务代码
+//   - 线程安全：单例模式确保全局一致性
+//
+// 智能初始化逻辑:
+//   - 检查 nanoWriter 单例是否已初始化
+//   - 如果未初始化，创建临时控制台日志器并存储为单例
+//   - 返回 nanoLogger 结构体实例，该结构体实现了标准日志接口
+//
+// 最佳实践:
+//   - 生产环境建议先调用 InitNanoWriter() 初始化专用文件日志器
+//   - 开发环境可以使用自动回退的控制台日志器进行调试
+//   - 微服务环境中确保所有服务使用相同的日志配置
 func NanoLogger() nanoLogger {
+	// 检查微服务日志器单例是否已经初始化
+	// 如果未初始化，执行懒加载初始化流程
 	if nanoWriter == nil {
+		// 创建临时的控制台微服务日志器作为回退方案
+		// 这种设计确保即使没有显式初始化，微服务框架也能正常使用日志功能
 		l := zerolog.New(zerolog.ConsoleWriter{
-			Out: os.Stdout, NoColor: false,
-			FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName),
+			Out:             os.Stdout,                                        // 输出到标准输出
+			NoColor:         false,                                            // 启用颜色输出（便于控制台调试）
+			FormatTimestamp: tool.ZerologFormatTimestamp(loggingLocationName), // 自定义时区时间戳
 		}).With().Timestamp().Caller().CallerWithSkipFrameCount(3).Logger()
-		// 存储单例
+
+		// 存储单例实例，供后续调用使用
+		// 确保整个应用程序中使用同一个微服务日志器实例
 		nanoWriter = &l
 	}
+
+	// 返回 nanoLogger 结构体实例
+	// nanoLogger 实现了标准日志接口（Println、Fatal、Fatalf）
+	// 微服务框架可以通过这个接口记录日志
 	return nanoLogger{}
 }