1

src/logx/README.md

@@ -2,24 +2,24 @@
 
 基于 [zerolog](https://github.com/rs/zerolog) 构建的高性能、结构化 Go 语言日志库，支持文件滚动、异步写入和多种日志类型。
 
-## 特性
+## 🚀 核心特性
 
-- 🚀 **高性能**：基于 zerolog 的零分配日志记录
-- 📁 **文件滚动**：自动日志文件轮转和备份管理
-- ⚡ **异步写入**：无锁、无阻塞的异步日志写入
-- 🌍 **时区支持**：自定义时区格式化时间戳
-- 🏷️ **多种日志类型**：Info、Error、Debug、Gin、Gorm、Nano 等
-- 🔧 **灵活配置**：支持自定义滚动和异步参数
+- **⚡ 极致性能**：基于 zerolog 的零分配日志记录，性能远超标准库
+- **📁 智能滚动**：自动日志文件轮转，支持按大小和时间滚动
+- **🔄 异步写入**：无锁、无阻塞的异步日志写入，不影响主程序性能
+- **🌍 时区支持**：自定义时区格式化时间戳，支持全球时区
+- **🔧 多种类型**：Info、Error、Debug、Gin、Gorm、Nano 等专用日志类型
+- **⚙️ 灵活配置**：支持自定义滚动参数、异步参数和写入策略
 
-## 安装
+## 📦 安装
 
 ```bash
-go get git.ooo.ink/root/go-kit/src/logx
+go get git.ooo.ink/root/go-kit
 ```
 
-## 快速开始
+## 🚀 快速开始
 
-### 基本使用
+### 基础用法（推荐）
 
 ```go
 package main
@@ -27,17 +27,30 @@ package main
 import "git.ooo.ink/root/go-kit/src/logx"
 
 func main() {
-    // 快速初始化（推荐）
-    logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
-
-    // 记录日志
-    logx.Info().Msg("应用启动成功")
-    logx.Error().Msg("发生了一个错误")
-    logx.Debug().Any("data", map[string]interface{}{"key": "value"}).Send()
+    // 快速初始化 - 最常用的方式
+    logx.Init("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
+
+    // 记录结构化日志
+    logx.Info().
+        Str("service", "user-service").
+        Int("port", 8080).
+        Msg("服务启动成功")
+
+    logx.Error().
+        Err(errors.New("数据库连接失败")).
+        Str("database", "users").
+        Msg("数据库操作异常")
+
+    logx.Debug().
+        Any("config", map[string]interface{}{
+            "debug": true,
+            "level": "info",
+        }).
+        Send()
 }
 ```
 
-### 自定义配置
+### 高级配置
 
 ```go
 package main
@@ -51,14 +64,14 @@ func main() {
     // 自定义写入器配置
     config := logx.WriterConfig{
         Rolling: logx.WriterRollingConfig{
-            MaxMegabytes: 10,    // 单文件最大 10MB
+            MaxMegabytes: 100,   // 单文件最大 100MB
             MaxDays:      30,    // 保留 30 天
             MaxBackups:   50,    // 最多 50 个备份文件
-            Compress:     true,  // 压缩备份文件
+            Compress:     true,  // 压缩备份文件节省空间
         },
         Async: &logx.WriterAsyncConfig{
-            BufferSize:   5000,                    // 异步缓冲区大小
-            PollInterval: time.Millisecond * 100,  // 轮询间隔
+            BufferSize:   10000,                   // 异步缓冲区大小（可容纳 10000 条日志）
+            PollInterval: time.Millisecond * 50,   // 轮询间隔 50ms
         },
     }
 
@@ -74,52 +87,57 @@ func main() {
 }
 ```
 
-## API 文档
+## 📋 日志类型详解
+
+| 日志类型 | 用途 | 特性 | 适用场景 |
+|---------|------|------|----------|
+| **Info** | 常规信息日志 | 记录应用运行状态、业务操作 | 生产环境监控、业务追踪 |
+| **Error** | 错误日志 | 自动包含错误堆栈信息 | 错误追踪、异常监控 |
+| **Debug** | 调试日志 | 开发环境调试信息 | 开发调试、问题排查 |
+| **Gin** | Gin 框架日志 | HTTP 请求响应记录 | Web 服务请求追踪 |
+| **Gorm** | GORM 数据库日志 | SQL 查询和执行记录 | 数据库操作监控 |
+| **Nano** | Nano 游戏服务器日志 | 游戏服务器专用日志 | 游戏服务器监控 |
 
-### 初始化函数
+## 🔧 API 参考
 
-#### `InitDefault(filePath, locationName string, useAsync bool, tags ...string)`
+### 核心初始化函数
 
-快速初始化日志系统。
+#### `Init(filePath, locationName string, useAsync bool, tags ...string)`
+快速初始化日志系统，使用默认配置。
 
-**参数：**
-- `filePath`：日志文件路径前缀
-- `locationName`：时区名称（如 "Asia/Shanghai"）
-- `useAsync`：是否启用异步写入
-- `tags`：要启用的日志类型标签（"info", "error", "debug", "gin", "gorm", "nano"）
+**参数说明：**
+- `filePath`: 日志文件路径前缀（如 "logs/app"）
+- `locationName`: 时区名称（如 "Asia/Shanghai"）
+- `useAsync`: 是否启用异步写入
+- `tags`: 要初始化的日志类型标签
 
 **示例：**
 ```go
-logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
+logx.Init("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
 ```
 
-#### `InitInfoWriter(writer io.Writer)`
-初始化 Info 日志写入器。
-
-#### `InitErrorWriter(writer io.Writer)`
-初始化 Error 日志写入器（支持错误堆栈）。
-
-#### `InitDebugWriter(writer io.Writer)`
-初始化 Debug 日志写入器。
+#### `InitWithWriter(filePath, locationName string, writerFactory func(string) io.Writer, tags ...string)`
+使用自定义写入器工厂初始化。
 
-#### `InitGinWriter(writer io.Writer)`
-初始化 Gin 框架专用日志写入器。
-
-#### `InitGormWriter(writer io.Writer)`
-初始化 GORM 数据库操作日志写入器。
+**示例：**
+```go
+logx.InitWithWriter("logs/app", "Asia/Shanghai", logx.DefaultWriter, "info", "error")
+```
 
-#### `InitNanoWriter(writer io.Writer)`
-初始化微服务专用日志写入器。
+#### `Init(locationName string, getWriter func(tag string) io.Writer, tags ...string)`
+最灵活的初始化方式，完全控制写入器创建。
 
-### 日志记录函数
+### 日志记录方法
 
 #### `Info() *zerolog.Event`
 记录信息级别日志。
 
 **示例：**
 ```go
-logx.Info().Msg("用户登录成功")
-logx.Info().Str("username", "john").Int("age", 25).Send()
+logx.Info().
+    Str("user_id", "12345").
+    Str("action", "login").
+    Msg("用户登录成功")
 ```
 
 #### `Error() *zerolog.Event`
@@ -127,68 +145,30 @@ logx.Info().Str("username", "john").Int("age", 25).Send()
 
 **示例：**
 ```go
-err := errors.New("数据库连接失败")
-logx.Error().Err(err).Msg("操作失败")
+err := errors.New("权限验证失败")
+logx.Error().
+    Err(err).
+    Str("endpoint", "/api/user").
+    Msg("API 调用失败")
 ```
 
 #### `Debug() *zerolog.Event`
 记录调试级别日志。
 
-**示例：**
-```go
-logx.Debug().Any("request", req).Msg("收到请求")
-```
-
-### 配置结构体
-
-#### `WriterConfig`
-日志写入器配置。
-
-```go
-type WriterConfig struct {
-    Rolling WriterRollingConfig  // 滚动配置
-    Async   *WriterAsyncConfig   // 异步配置（可选）
-}
-```
-
-#### `WriterRollingConfig`
-文件滚动配置。
-
-```go
-type WriterRollingConfig struct {
-    MaxMegabytes int  // 单文件最大存储容量（兆字节）
-    MaxDays      int  // 最大存储天数
-    MaxBackups   int  // 最大备份文件数量
-    Compress     bool // 备份文件是否压缩
-}
-```
-
-#### `WriterAsyncConfig`
-异步写入配置。
-
-```go
-type WriterAsyncConfig struct {
-    BufferSize   int           // 生产者缓冲区大小
-    PollInterval time.Duration // 消费者轮询间隔
-    Alerter      diode.Alerter // 丢弃告警函数
-}
-```
-
-### 工具函数
+### 配置工具函数
 
 #### `DefaultWriter(fileName string, useAsync bool) io.Writer`
 创建默认配置的写入器。
 
-**默认配置：**
-- 滚动：1MB/文件，保留10天，10个备份，不压缩
-- 异步：1000缓冲区（如果启用）
-
 #### `NewWriter(fileName string, c WriterConfig) io.Writer`
 根据配置创建新的写入器。
 
-## 日志文件结构
+#### `SetLocation(locationName string)`
+设置日志时区。
+
+## 📁 日志文件结构
 
-使用 `InitDefault` 初始化后，会生成如下结构的日志文件：
+使用 `Init` 初始化后，会生成如下结构的日志文件：
 
 ```
 logs/
@@ -197,12 +177,12 @@ logs/
 ├── app.debug.log     # Debug 级别日志
 ├── app.gin.log       # Gin 框架日志
 ├── app.gorm.log      # GORM 数据库日志
-└── app.nano.log      # 微服务日志
+└── app.nano.log      # Nano 游戏服务器日志
 ```
 
-## 日志格式
+## 📝 日志格式规范
 
-日志采用结构化格式，包含：
+日志采用结构化格式，包含完整的时间戳、级别、调用位置和上下文信息：
 
 ```
 <timestamp> <level> <caller> <message> <fields>
@@ -210,73 +190,128 @@ logs/
 
 **示例输出：**
 ```
-CST 2024-01-15 10:30:25 INFO main.go:15 用户登录成功 username=john age=25
-CST 2024-01-15 10:30:26 ERROR main.go:20 数据库操作失败 error="connection timeout"
+CST 2024-01-15 10:30:25 INFO main.go:15 用户登录成功 user_id=12345 action=login
+CST 2024-01-15 10:30:26 ERROR main.go:20 API 调用失败 error="权限验证失败" endpoint=/api/user
 ```
 
-## 性能优化
-
-### 异步写入
-启用异步写入可以显著提高日志记录性能，防止日志 I/O 阻塞主程序：
+## ⚡ 性能优化指南
 
+### 启用异步写入提升性能
 ```go
-logx.InitDefault("logs/app", "Asia/Shanghai", true, "info", "error")
+// 启用异步写入，适用于高并发场景
+logx.Init("logs/app", "Asia/Shanghai", true, "info", "error")
 ```
 
-### 合理的滚动配置
-根据应用需求调整滚动参数：
-
+### 合理配置滚动参数
 ```go
 config := logx.WriterConfig{
     Rolling: logx.WriterRollingConfig{
-        MaxMegabytes: 100,  // 大文件减少文件数量
-        MaxDays:      7,    // 短期保留节省空间
-        MaxBackups:   10,   // 控制备份数量
+        MaxMegabytes: 100,  // 大文件减少文件数量，提升写入性能
+        MaxDays:      7,    // 短期保留节省磁盘空间
+        MaxBackups:   10,   // 控制备份数量，避免磁盘爆满
         Compress:     true, // 压缩节省磁盘空间
     },
 }
 ```
 
-## 最佳实践
+### 异步缓冲区优化
+```go
+config := logx.WriterConfig{
+    Async: &logx.WriterAsyncConfig{
+        BufferSize:   50000,  // 大缓冲区减少日志丢失风险
+        PollInterval: time.Millisecond * 10,  // 更短的轮询间隔
+    },
+}
+```
 
-1. **生产环境**：启用异步写入和文件压缩
-2. **开发环境**：可以禁用异步以便实时查看日志
-3. **错误日志**：始终启用 Error 日志以捕获异常堆栈
-4. **敏感信息**：避免在日志中记录密码、密钥等敏感信息
-5. **日志级别**：根据环境调整日志级别（生产环境可关闭 Debug）
+## 🏆 最佳实践
 
-## 故障排除
+### 生产环境配置
+```go
+// 生产环境推荐配置：只记录关键信息，启用异步写入
+logx.Init("logs/prod", "Asia/Shanghai", true, "info", "error")
+```
+
+### 开发环境配置
+```go
+// 开发环境：记录详细日志，使用同步写入便于调试
+logx.Init("logs/dev", "Asia/Shanghai", false, "info", "error", "debug")
+```
+
+### 微服务场景配置
+```go
+// 为不同服务使用不同的日志文件
+serviceName := "user-service"
+logx.Init("logs/"+serviceName, "Asia/Shanghai", true, "info", "error")
+```
 
-### 常见问题
+## 🔒 安全注意事项
+
+- **敏感信息保护**：避免在日志中记录密码、密钥、令牌等敏感信息
+- **生产环境安全**：生产环境建议关闭 Debug 日志，避免信息泄露
+- **文件权限管理**：确保日志文件有适当的文件权限设置
+- **定期清理**：设置合理的日志保留策略，定期清理过期日志
+
+## 🔍 故障排除
+
+### 常见问题解决方案
 
 **Q: 日志文件没有生成？**
-A: 检查文件路径权限，确保应用有写入权限。
+A: 检查文件路径权限，确保应用有写入权限。检查时区名称是否正确。
 
 **Q: 异步写入丢失日志？**
-A: 增大 `BufferSize` 或减少 `PollInterval`。
+A: 增大 `BufferSize` 或减少 `PollInterval`。考虑使用同步写入进行关键日志记录。
 
 **Q: 时区显示不正确？**
-A: 确认 `locationName` 参数使用正确的时区名称。
+A: 确认 `locationName` 参数使用正确的时区名称，如 "Asia/Shanghai"。
+
+**Q: 日志文件过大？**
+A: 调整 `MaxMegabytes` 参数，启用压缩，或减少日志记录频率。
 
 ### 调试模式
 
 可以临时启用控制台输出进行调试：
-
 ```go
-// 不初始化文件写入器，使用标准输出
+// 不初始化文件写入器，使用标准输出进行调试
 logx.Info().Msg("调试信息")
 ```
 
-## 依赖项
+## 📚 技术架构
+
+### 核心组件
+
+- **zerolog**: 高性能结构化日志库
+- **lumberjack**: 日志文件轮转组件
+- **zerolog/diode**: 异步写入器实现
 
-- [zerolog](https://github.com/rs/zerolog) - 高性能日志库
-- [lumberjack](https://github.com/natefinch/lumberjack) - 日志文件轮转
-- [zerolog/diode](https://pkg.go.dev/github.com/rs/zerolog/diode) - 异步写入器
+### 设计原则
 
-## 许可证
+1. **性能优先**: 零分配设计，最小化性能开销
+2. **可靠性**: 异步写入保证主程序不阻塞
+3. **易用性**: 提供简单易用的高级接口
+4. **灵活性**: 支持多种配置方式和扩展点
+
+## 📄 许可证
 
 MIT License
 
-## 贡献
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request！在贡献代码前请确保：
+
+1. 代码符合 Go 语言编码规范
+2. 添加适当的单元测试
+3. 更新相关文档
+4. 通过所有现有测试
+
+## 📞 技术支持
+
+如有问题或建议，请通过以下方式联系：
+
+- 提交 Issue: [项目 Issue 页面]
+- 邮件支持: [技术支持邮箱]
+- 文档更新: 欢迎完善本文档
+
+---
 
-欢迎提交 Issue 和 Pull Request！
+*最后更新: 2024年1月*

src/logx/logger.Debug.go

@@ -40,7 +40,7 @@ var (
 // 注意事项:
 //   - 该函数应该在应用程序启动时调用一次
 //   - 如果多次调用，后一次的配置会覆盖前一次
-//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
 func InitDebugWriter(writer io.Writer) {
 	// 创建 zerolog 日志器实例，配置如下：
 	// - ConsoleWriter: 使用控制台格式输出，便于阅读

src/logx/logger.Error.go

@@ -40,7 +40,7 @@ var (
 // 注意事项:
 //   - 错误日志通常需要单独的文件存储，便于监控和告警
 //   - 建议在生产环境中始终启用 Error 日志记录
-//   - 错误堆栈信息需要在全局初始化时配置（参见 logx.InitDefault）
+//   - 错误堆栈信息需要在全局初始化时配置（参见 logx.Init）
 func InitErrorWriter(writer io.Writer) {
 	// 创建配置完善的 zerolog 错误日志器：
 	// - ConsoleWriter: 使用控制台格式，便于人类阅读错误信息

src/logx/logger.Info.go

@@ -40,7 +40,7 @@ var (
 // 注意事项:
 //   - 该函数应该在应用程序启动时调用一次
 //   - 如果多次调用，后一次的配置会覆盖前一次
-//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
 //   - Info 日志通常包含业务操作信息，建议单独存储便于分析
 func InitInfoWriter(writer io.Writer) {
 	// 创建配置完善的 zerolog 信息日志器：

src/logx/main.Init.go

@@ -70,11 +70,6 @@ import (
 //   - 灵活性强: 支持任意复杂的写入器创建逻辑
 //   - 易于测试: 便于单元测试中模拟不同的写入器行为
 //   - 架构清晰: 分离了初始化逻辑和写入器创建逻辑
-//
-// 注意事项:
-//   - 这是最底层的初始化函数，需要手动处理所有配置细节
-//   - 对于简单场景，建议使用 InitDefault 或 InitDefaultWithWriter
-//   - 确保为每个需要的标签提供有效的写入器
 func Init(locationName string, getWriter func(tag string) io.Writer, tags ...string) {
 	// 配置 zerolog 的错误堆栈序列化器
 	// 启用错误堆栈信息记录，便于调试和问题追踪

src/logx/writer.Gin.go

@@ -44,7 +44,7 @@ var (
 // 注意事项:
 //   - Gin 日志通常包含大量的请求信息，建议启用异步写入提高性能
 //   - 生产环境中 Gin 日志应该单独存储，便于监控 API 性能
-//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
 func InitGinWriter(writer io.Writer) {
 	// 创建配置完善的 zerolog Gin 日志器：
 	// - ConsoleWriter: 使用控制台格式，便于阅读 HTTP 请求信息

src/logx/writer.Gorm.go

@@ -49,7 +49,7 @@ var (
 // 注意事项:
 //   - GORM 日志可能包含敏感信息（如 SQL 参数），生产环境中需谨慎处理
 //   - 建议启用异步写入以提高数据库操作性能
-//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
 //   - 与标准日志不同，GORM 日志器不包含调用者信息，避免日志过于冗长
 func InitGormWriter(writer io.Writer) {
 	// 创建配置完善的 zerolog GORM 日志器：

src/logx/writer.Nano.go

@@ -196,7 +196,7 @@ var (
 //   - 游戏服务器日志通常需要包含完整的调用链信息，便于追踪玩家操作
 //   - CallerWithSkipFrameCount(3) 确保跳过框架内部调用，准确定位游戏逻辑代码
 //   - 建议在生产环境中启用异步写入以提高游戏服务器性能
-//   - 需要先调用 logx.InitDefault() 或设置 loggingLocationName 以确保时区正确
+//   - 需要先调用 logx.Init() 或设置 loggingLocationName 以确保时区正确
 func InitNanoWriter(writer io.Writer) {
 	// 创建配置完善的 zerolog 微服务日志器：
 	// - ConsoleWriter: 使用控制台格式，便于阅读分布式系统日志