1

src/logx/README.md

@@ -28,7 +28,9 @@ import "git.ooo.ink/root/go-kit/src/logx"
 
 func main() {
     // 快速初始化 - 最常用的方式
-    logx.Init("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
+    logx.Init("Asia/Shanghai", func(tag string) io.Writer {
+        return logx.DefaultWriter("logs/app."+tag+".log", true)
+    }, "info", "error", "debug")
 
     // 记录结构化日志
     logx.Info().
@@ -102,30 +104,41 @@ func main() {
 
 ### 核心初始化函数
 
-#### `Init(filePath, locationName string, useAsync bool, tags ...string)`
-快速初始化日志系统，使用默认配置。
+#### `Init(locationName string, getWriter func(tag string) io.Writer, tags ...string)`
+最灵活的初始化方式，完全控制写入器创建。
 
 **参数说明：**
-- `filePath`: 日志文件路径前缀（如 "logs/app"）
 - `locationName`: 时区名称（如 "Asia/Shanghai"）
-- `useAsync`: 是否启用异步写入
+- `getWriter`: 写入器获取函数，接收标签参数返回对应的 io.Writer
 - `tags`: 要初始化的日志类型标签
 
 **示例：**
 ```go
-logx.Init("logs/app", "Asia/Shanghai", true, "info", "error", "debug")
+logx.Init("Asia/Shanghai", func(tag string) io.Writer {
+    return logx.DefaultWriter("logs/app."+tag+".log", true)
+}, "info", "error", "debug")
 ```
 
-#### `InitWithWriter(filePath, locationName string, writerFactory func(string) io.Writer, tags ...string)`
-使用自定义写入器工厂初始化。
+#### `InitInfoWriter(writer io.Writer)`
+初始化 Info 级别的日志写入器。
 
-**示例：**
-```go
-logx.InitWithWriter("logs/app", "Asia/Shanghai", logx.DefaultWriter, "info", "error")
-```
+#### `InitErrorWriter(writer io.Writer)`
+初始化 Error 级别的日志写入器（自动包含堆栈信息）。
 
-#### `Init(locationName string, getWriter func(tag string) io.Writer, tags ...string)`
-最灵活的初始化方式，完全控制写入器创建。
+#### `InitDebugWriter(writer io.Writer)`
+初始化 Debug 级别的日志写入器。
+
+### 写入器工厂函数
+
+#### `DefaultWriter(fileName string, useAsync bool) io.Writer`
+创建默认配置的写入器。
+
+**默认配置：**
+- 文件滚动：单文件最大 1MB，保留 10 天，最多 10 个备份，不压缩
+- 异步写入：缓冲区大小 1000，默认轮询间隔
+
+#### `NewWriter(fileName string, c WriterConfig) io.Writer`
+根据配置创建新的写入器。
 
 ### 日志记录方法
 
@@ -155,16 +168,40 @@ logx.Error().
 #### `Debug() *zerolog.Event`
 记录调试级别日志。
 
-### 配置工具函数
+### 配置结构体
 
-#### `DefaultWriter(fileName string, useAsync bool) io.Writer`
-创建默认配置的写入器。
+#### `WriterConfig`
+写入器配置结构体。
 
-#### `NewWriter(fileName string, c WriterConfig) io.Writer`
-根据配置创建新的写入器。
+```go
+type WriterConfig struct {
+    Rolling WriterRollingConfig
+    Async   *WriterAsyncConfig
+}
+```
 
-#### `SetLocation(locationName string)`
-设置日志时区。
+#### `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 // 丢弃告警函数
+}
+```
 
 ## 📁 日志文件结构
 
@@ -199,7 +236,8 @@ CST 2024-01-15 10:30:26 ERROR main.go:20 API 调用失败 error="权限验证失
 ### 启用异步写入提升性能
 ```go
 // 启用异步写入，适用于高并发场景
-logx.Init("logs/app", "Asia/Shanghai", true, "info", "error")
+writer := logx.DefaultWriter("logs/app.log", true)
+logx.InitInfoWriter(writer)
 ```
 
 ### 合理配置滚动参数
@@ -229,20 +267,26 @@ config := logx.WriterConfig{
 ### 生产环境配置
 ```go
 // 生产环境推荐配置：只记录关键信息，启用异步写入
-logx.Init("logs/prod", "Asia/Shanghai", true, "info", "error")
+writer := logx.DefaultWriter("logs/prod.log", true)
+logx.InitInfoWriter(writer)
+logx.InitErrorWriter(writer)
 ```
 
 ### 开发环境配置
 ```go
 // 开发环境：记录详细日志，使用同步写入便于调试
-logx.Init("logs/dev", "Asia/Shanghai", false, "info", "error", "debug")
+writer := logx.DefaultWriter("logs/dev.log", false)
+logx.InitInfoWriter(writer)
+logx.InitErrorWriter(writer)
+logx.InitDebugWriter(writer)
 ```
 
 ### 微服务场景配置
 ```go
 // 为不同服务使用不同的日志文件
 serviceName := "user-service"
-logx.Init("logs/"+serviceName, "Asia/Shanghai", true, "info", "error")
+writer := logx.DefaultWriter("logs/"+serviceName+".log", true)
+logx.InitInfoWriter(writer)
 ```
 
 ## 🔒 安全注意事项
@@ -272,7 +316,8 @@ A: 调整 `MaxMegabytes` 参数，启用压缩，或减少日志记录频率。
 
 可以临时启用控制台输出进行调试：
 ```go
-// 不初始化文件写入器，使用标准输出进行调试
+// 使用标准输出进行调试
+logx.InitInfoWriter(os.Stdout)
 logx.Info().Msg("调试信息")
 ```