日志方法增加异步与同步的方法

docs/logger.md

@@ -12,6 +12,7 @@
 - 支持日志前缀
 - 支持禁用时间戳
 - 支持带字段的日志记录
+- **支持异步/同步日志模式（默认同步）**
 - 使用配置工具统一管理配置
 
 ## 使用方法
@@ -92,6 +93,40 @@ logger.Infof(fields, "User logged in")
 logger.Errorf(fields, "Failed to process request")
 ```
 
+### 5. 异步/同步模式
+
+#### 同步模式（默认）
+
+```go
+// 配置中不设置async或设置为false，使用同步模式
+// 同步模式：日志直接写入，会阻塞调用方直到写入完成
+logger.Info("This is a synchronous log")
+```
+
+#### 异步模式
+
+```go
+// 配置中设置async为true，使用异步模式
+// 异步模式：日志写入通过channel异步处理，不阻塞调用方
+// 配置文件示例：
+// {
+//   "logger": {
+//     "async": true,
+//     "bufferSize": 1000
+//   }
+// }
+
+// 使用异步模式时，程序退出前需要调用Close()确保所有日志写入完成
+defer logger.Close()
+
+logger.Info("This is an asynchronous log")
+```
+
+**注意：**
+- `Fatal` 和 `Panic` 方法始终使用同步模式，确保日志写入后再退出/panic
+- 异步模式下，程序退出前应调用 `Close()` 方法，确保所有日志写入完成
+- 如果channel已满，会自动降级为同步写入，避免丢失日志
+
 ## API 参考
 
 ### NewLogger(cfg *config.LoggerConfig) (*Logger, error)
@@ -143,6 +178,15 @@ logger.Errorf(fields, "Failed to process request")
 
 记录错误日志（带字段）。
 
+### (l *Logger) Close() error
+
+优雅关闭logger（仅异步模式需要）。
+
+**说明：**
+- 等待所有日志写入完成后再返回
+- 同步模式下调用此方法会立即返回，无需等待
+- 程序退出前应调用此方法，确保所有日志写入完成
+
 ## 配置说明
 
 日志配置通过 `config.LoggerConfig` 提供：
@@ -154,6 +198,8 @@ logger.Errorf(fields, "Failed to process request")
 | FilePath | string | 日志文件路径（当output为file或both时必需） | - |
 | Prefix | string | 日志前缀 | - |
 | DisableTimestamp | bool | 禁用时间戳 | false |
+| Async | bool | 是否使用异步模式 | false（同步） |
+| BufferSize | int | 异步模式下的缓冲区大小 | 1000 |
 
 ## 配置示例
 
@@ -196,6 +242,25 @@ logger.Errorf(fields, "Failed to process request")
 }
 ```
 
+### 异步模式配置
+
+```json
+{
+  "logger": {
+    "level": "info",
+    "output": "file",
+    "filePath": "./logs/app.log",
+    "prefix": "app",
+    "async": true,
+    "bufferSize": 1000
+  }
+}
+```
+
+**说明：**
+- `async`: 设置为 `true` 启用异步模式，`false` 或不设置则使用同步模式（默认）
+- `bufferSize`: 异步模式下的channel缓冲区大小，默认1000。当缓冲区满时，新的日志会阻塞直到有空间，或降级为同步写入
+
 ## 日志级别说明
 
 - **debug**: 调试信息，最详细的日志级别
@@ -222,6 +287,13 @@ logger.Errorf(fields, "Failed to process request")
 4. **性能考虑**：
    - 使用标准库log包，性能较好
    - 文件输出使用追加模式，不会覆盖已有日志
+   - 异步模式适合高并发场景，减少日志写入对业务代码的阻塞
+   - 同步模式适合需要确保日志立即写入的场景（如调试）
+
+5. **异步模式注意事项**：
+   - 异步模式下，程序退出前必须调用 `Close()` 方法，确保所有日志写入完成
+   - 如果channel缓冲区已满，会自动降级为同步写入，避免丢失日志
+   - `Fatal` 和 `Panic` 方法始终使用同步模式，确保日志写入后再退出/panic
 
 ## 完整示例
 
@@ -257,6 +329,9 @@ func main() {
     }, "User logged in successfully")
     
     logger.Error("An error occurred: %v", err)
+    
+    // 如果使用异步模式，程序退出前需要关闭logger
+    // defer logger.Close()
 }
 ```