1

src/logx/main.DefaultWriter.go

@@ -1,27 +1,97 @@
 package logx
 
-import "io"
+import (
+	"io"
+)
 
-// DefaultWriter ..
+// DefaultWriter 创建并返回一个使用默认配置的日志写入器
 //
-// e.g.
+// 该函数是日志库的便捷工厂方法，提供预定义的合理默认配置
+// 适用于大多数常见场景，无需手动配置复杂的滚动和异步参数
 //
-//	logx.DefaultWriter("logs/demo.log", true)
+// 参数:
+//
+//	fileName - 日志文件完整路径（如 "logs/app.log"）
+//	useAsync - 是否启用异步写入，true 启用可提高性能，false 使用同步写入
+//
+// 返回值:
+//
+//	io.Writer - 符合标准 io.Writer 接口的日志写入器
+//
+// 默认配置说明:
+//
+//   - 文件滚动配置:
+//
+//   - MaxMegabytes: 1    - 单文件最大 1MB
+//
+//   - MaxDays:      10   - 文件保留 10 天
+//
+//   - MaxBackups:   10   - 最多保留 10 个备份文件
+//
+//   - Compress:     false - 备份文件不压缩
+//
+//   - 异步写入配置（当 useAsync = true 时）:
+//
+//   - BufferSize:   1000 - 异步缓冲区大小（可容纳 1000 条日志）
+//
+//   - PollInterval: 0    - 轮询间隔（0 表示使用默认值）
+//
+//   - Alerter:      nil  - 无丢弃告警函数
+//
+// 设计理念:
+//   - 安全保守: 默认配置偏向保守，避免因日志问题影响应用稳定性
+//   - 性能平衡: 在性能和资源消耗之间取得平衡
+//   - 易于使用: 隐藏复杂配置细节，提供简单接口
+//
+// 使用示例:
+//
+//	// 创建启用异步写入的默认日志写入器
+//	writer := logx.DefaultWriter("logs/app.log", true)
+//	logx.InitInfoWriter(writer)
+//
+//	// 创建同步写入的默认日志写入器
+//	writer := logx.DefaultWriter("logs/debug.log", false)
+//	logx.InitDebugWriter(writer)
+//
+// 适用场景:
+//   - 快速原型开发
+//   - 中小型项目
+//   - 开发环境和测试环境
+//   - 不需要特殊配置的标准场景
+//
+// 性能考虑:
+//   - 异步写入（useAsync=true）: 适合生产环境和高并发场景
+//   - 同步写入（useAsync=false）: 适合开发调试和低负载场景
+//
+// 注意事项:
+//   - 默认配置适用于大多数场景，但可能不适合特殊需求
+//   - 对于高流量应用，建议调整文件大小和备份数量
+//   - 生产环境中建议启用异步写入以提高性能
 func DefaultWriter(fileName string, useAsync bool) io.Writer {
+	// 创建默认的文件滚动配置
+	// 这些参数经过实践检验，在大多数场景下表现良好
 	config := WriterConfig{
 		Rolling: WriterRollingConfig{
-			MaxMegabytes: 1,
-			MaxDays:      10,
-			MaxBackups:   10,
-			Compress:     false,
+			MaxMegabytes: 1,     // 单文件最大 1MB，避免单个文件过大
+			MaxDays:      10,    // 保留 10 天，平衡存储空间和历史追溯需求
+			MaxBackups:   10,    // 最多 10 个备份，控制备份文件数量
+			Compress:     false, // 不压缩备份文件，简化运维但占用更多空间
 		},
 	}
+
+	// 检查是否需要启用异步写入
+	// 异步写入可以提高日志记录性能，但增加内存使用
 	if useAsync {
+		// 配置异步写入参数
+		// 这些参数在性能和资源消耗之间取得平衡
 		config.Async = &WriterAsyncConfig{
-			BufferSize:   1000,
-			PollInterval: 0,
-			Alerter:      nil,
+			BufferSize:   1000, // 缓冲区大小 1000，适合中等并发场景
+			PollInterval: 0,    // 轮询间隔 0，使用库的默认优化值
+			Alerter:      nil,  // 无告警函数，简化配置
 		}
 	}
+
+	// 使用配置创建最终的日志写入器
+	// NewWriter 函数会根据配置组合文件滚动和异步写入功能
 	return NewWriter(fileName, config)
 }

src/logx/main.Init.go

@@ -0,0 +1,110 @@
+package logx
+
+import (
+	"io"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/pkgerrors"
+)
+
+// Init 日志库的核心初始化函数，提供最大的灵活性和控制能力
+//
+// 该函数是日志库最基础的初始化方法，允许完全自定义日志写入器的创建方式
+// 适用于需要精细控制日志配置、单元测试、特殊需求等高级场景
+//
+// 参数:
+//
+//	locationName - 时区名称，用于日志时间戳格式化（如 "Asia/Shanghai"）
+//	getWriter    - 写入器获取函数，接收标签参数返回对应的 io.Writer
+//	tags         - 要初始化的日志类型标签（可变参数）
+//
+// 支持的标签类型:
+//   - "info"   : 信息级别日志
+//   - "error"  : 错误级别日志（自动包含堆栈信息）
+//   - "debug"  : 调试级别日志
+//   - "gin"    : Gin 框架专用日志
+//   - "gorm"   : GORM 数据库专用日志
+//   - "nano"   : Nano 游戏服务器框架专用日志
+//
+// 使用示例:
+//
+//	// 基础使用：为不同标签创建不同的文件写入器
+//	logx.Init("Asia/Shanghai", func(tag string) io.Writer {
+//	    return logx.DefaultWriter("logs/app."+tag+".log", true)
+//	}, "info", "error", "debug")
+//
+//	// 高级配置：为不同标签使用不同的配置
+//	logx.Init("UTC", func(tag string) io.Writer {
+//	    switch tag {
+//	    case "error":
+//	        // 错误日志使用更大的文件和更长的保留时间
+//	        return logx.NewWriter("logs/error.log", logx.WriterConfig{
+//	            Rolling: logx.WriterRollingConfig{
+//	                MaxMegabytes: 100,
+//	                MaxDays:      90,
+//	                MaxBackups:   100,
+//	                Compress:     true,
+//	            },
+//	        })
+//	    default:
+//	        // 其他日志使用标准配置
+//	        return logx.DefaultWriter("logs/"+tag+".log", true)
+//	    }
+//	}, "info", "error", "debug")
+//
+//	// 单元测试：使用内存缓冲区
+//	var infoBuffer, errorBuffer bytes.Buffer
+//	logx.Init("UTC", func(tag string) io.Writer {
+//	    switch tag {
+//	    case "info":
+//	        return &infoBuffer
+//	    case "error":
+//	        return &errorBuffer
+//	    default:
+//	        return io.Discard
+//	    }
+//	}, "info", "error")
+//
+// 设计优势:
+//   - 完全控制: 可以为每个日志标签单独配置写入器
+//   - 灵活性强: 支持任意复杂的写入器创建逻辑
+//   - 易于测试: 便于单元测试中模拟不同的写入器行为
+//   - 架构清晰: 分离了初始化逻辑和写入器创建逻辑
+//
+// 注意事项:
+//   - 这是最底层的初始化函数，需要手动处理所有配置细节
+//   - 对于简单场景，建议使用 InitDefault 或 InitDefaultWithWriter
+//   - 确保为每个需要的标签提供有效的写入器
+func Init(locationName string, getWriter func(tag string) io.Writer, tags ...string) {
+	// 配置 zerolog 的错误堆栈序列化器
+	// 启用错误堆栈信息记录，便于调试和问题追踪
+	zerolog.ErrorStackMarshaler = pkgerrors.MarshalStack
+
+	// 设置全局时区配置
+	// 影响所有日志记录的时间戳格式化
+	loggingLocationName = locationName
+
+	// 遍历所有传入的标签，为每个标签初始化对应的日志写入器
+	for _, tag := range tags {
+		switch tag {
+		case "info":
+			// 初始化信息级别日志写入器
+			InitInfoWriter(getWriter(tag))
+		case "error":
+			// 初始化错误级别日志写入器（自动包含堆栈信息）
+			InitErrorWriter(getWriter(tag))
+		case "debug":
+			// 初始化调试级别日志写入器
+			InitDebugWriter(getWriter(tag))
+		case "gin":
+			// 初始化 Gin 框架专用日志写入器
+			InitGinWriter(getWriter(tag))
+		case "gorm":
+			// 初始化 GORM 数据库专用日志写入器
+			InitGormWriter(getWriter(tag))
+		case "nano":
+			// 初始化 Nano 游戏服务器框架专用日志写入器
+			InitNanoWriter(getWriter(tag))
+		}
+	}
+}

src/logx/main.InitDefault.go

@@ -1,40 +0,0 @@
-package logx
-
-import (
-	"io"
-
-	"github.com/rs/zerolog"
-	"github.com/rs/zerolog/pkgerrors"
-)
-
-// 初始化日志，使用默认配置快速初始化
-//
-// e.g.
-//
-//	logx.InitDefault("logs/app", "Asia/Shanghai", useAsync, "info", "error", "debug", "gorm", "gin")
-//	logx.InitDefault("logs/app", "Asia/Shanghai", useAsync, "info", "error", "debug", "gorm", "nano")
-func InitDefault(filePath, locationName string, useAsync bool, tags ...string) {
-
-	zerolog.ErrorStackMarshaler = pkgerrors.MarshalStack
-
-	loggingLocationName = locationName
-	w := func(tag string) io.Writer {
-		return DefaultWriter(filePath+"."+tag+".log", useAsync)
-	}
-	for _, tag := range tags {
-		switch tag {
-		case "info":
-			InitInfoWriter(w(tag))
-		case "error":
-			InitErrorWriter(w(tag))
-		case "debug":
-			InitDebugWriter(w(tag))
-		case "gin":
-			InitGinWriter(w(tag))
-		case "gorm":
-			InitGormWriter(w(tag))
-		case "nano":
-			InitNanoWriter(w(tag))
-		}
-	}
-}

src/logx/main.NewWriter.go

@@ -29,11 +29,67 @@ type WriterAsyncConfig struct {
 	Alerter      diode.Alerter // 丢弃告警函数
 }
 
-// 实例化日志写入器，支持 滚动 与 异步
+// NewWriter 创建并返回一个配置完善的日志写入器，支持文件滚动和异步写入
+//
+// 该函数是日志库的核心工厂方法，根据配置创建具有不同特性的日志写入器
+// 支持文件自动轮转、备份管理、压缩存储以及高性能异步写入等功能
+//
+// 参数:
+//
+//	fileName - 日志文件路径，包含完整路径的文件名（如 "logs/app.log"）
+//	c - 写入器配置，包含滚动配置和可选的异步配置
+//
+// 返回值:
+//
+//	io.Writer - 符合标准 io.Writer 接口的日志写入器
+//
+// 功能特性:
+//   - 文件滚动: 自动管理日志文件大小和数量，防止单个文件过大
+//   - 备份管理: 支持配置最大备份数量和保留天数
+//   - 压缩存储: 可选启用备份文件压缩，节省磁盘空间
+//   - 异步写入: 可选启用无阻塞异步写入，提高日志记录性能
+//   - 灵活配置: 支持组合不同的配置选项满足不同场景需求
+//
+// 使用示例:
+//
+//	config := logx.WriterConfig{
+//	    Rolling: logx.WriterRollingConfig{
+//	        MaxMegabytes: 10,    // 单文件最大 10MB
+//	        MaxDays:      30,    // 保留 30 天
+//	        MaxBackups:   50,    // 最多 50 个备份
+//	        Compress:     true,  // 压缩备份文件
+//	    },
+//	    Async: &logx.WriterAsyncConfig{
+//	        BufferSize:   1000,                    // 异步缓冲区大小
+//	        PollInterval: time.Millisecond * 100,  // 轮询间隔
+//	    },
+//	}
+//
+//	writer := logx.NewWriter("logs/app.log", config)
+//	logx.InitInfoWriter(writer)
+//
+// 配置组合说明:
+//   - 仅滚动: 只配置 Rolling 字段，Async 设为 nil
+//   - 滚动+异步: 同时配置 Rolling 和 Async 字段
+//   - 仅异步: 不推荐，异步写入通常需要配合文件滚动使用
+//
+// 性能建议:
+//   - 生产环境: 建议启用异步写入和文件压缩
+//   - 高并发场景: 增大异步缓冲区大小减少日志丢失风险
+//   - 磁盘空间敏感: 合理设置文件大小和备份数量
 func NewWriter(fileName string, c WriterConfig) io.Writer {
+	// 首先创建基础的文件滚动写入器
+	// 该写入器负责日志文件的自动轮转、备份管理和压缩存储
 	var w = tool.FileRollingWriter(fileName, c.Rolling.MaxBackups, c.Rolling.MaxDays, c.Rolling.MaxMegabytes, c.Rolling.Compress)
+
+	// 检查是否配置了异步写入
+	// 如果配置了异步写入，则包装基础写入器为异步写入器
 	if c.Async != nil {
+		// 使用异步写入器包装基础写入器
+		// 异步写入器提供无阻塞的高性能日志记录能力
 		return tool.WrapAsyncWriter(w, c.Async.BufferSize, c.Async.PollInterval, c.Async.Alerter)
 	}
+
+	// 如果没有配置异步写入，直接返回基础的文件滚动写入器
 	return w
 }

src/logx/main.SetLocation.go

@@ -1,13 +1,49 @@
 package logx
 
-// loggingLocationName
+// loggingLocationName 全局时区名称变量，用于配置日志时间戳的时区
+// 默认值为 "UTC"，表示使用协调世界时
+// 可以通过 SetLocation 函数修改为其他时区，如 "Asia/Shanghai"、"America/New_York" 等
 var loggingLocationName = "UTC"
 
-// SetLocation
+// SetLocation 设置日志时间戳的时区配置
 //
-// e.g.
+// 该函数用于全局配置日志库的时区设置，影响所有日志记录的时间戳显示
+// 时区设置会影响日志文件中时间戳的格式化输出，便于在不同时区的服务器上正确显示时间
 //
+// 参数:
+//
+//	locationName - 时区名称字符串，使用 IANA 时区数据库的标准名称
+//
+// 支持的时区示例:
+//   - "Asia/Shanghai" (中国标准时间)
+//   - "America/New_York" (美国东部时间)
+//   - "Europe/London" (伦敦时间)
+//   - "UTC" (协调世界时)
+//
+// 使用示例:
+//
+//	// 设置日志时区为中国标准时间
 //	logx.SetLocation("Asia/Shanghai")
+//
+//	// 设置日志时区为美国东部时间
+//	logx.SetLocation("America/New_York")
+//
+//	// 恢复为默认的 UTC 时区
+//	logx.SetLocation("UTC")
+//
+// 注意事项:
+//   - 时区设置是全局生效的，会影响所有后续的日志记录
+//   - 建议在应用程序启动时调用此函数进行时区配置
+//   - 时区名称必须使用 IANA 时区数据库的标准名称
+//   - 如果时区名称无效，日志时间戳格式化可能会返回错误信息
+//   - 时区设置不会影响已记录的日志，只影响设置后的新日志
+//
+// 最佳实践:
+//   - 生产环境中根据服务器所在地设置对应的时区
+//   - 开发环境可以使用本地时区便于调试
+//   - 分布式系统中建议所有服务使用统一的时区配置
 func SetLocation(locationName string) {
+	// 更新全局时区配置变量
+	// 后续的日志记录会使用这个时区来格式化时间戳
 	loggingLocationName = locationName
 }