add JRZQ09J8、FLXGDEA8、FLXGDEA9、JRZQ1D09

add external_services log
2025-08-25 15:44:06 +08:00
parent 365a2a8886
commit 267ff92998
80 changed files with 5555 additions and 1254 deletions
--- a/docs/新日志系统使用指南.md
+++ b/docs/新日志系统使用指南.md
@@ -0,0 +1,340 @@
+# 🚀 新日志系统使用指南
+
+## 概述
+
+本项目已重新设计日志系统，完全基于 **Zap 官方最佳实践**，提供高性能、结构化的日志记录功能。
+
+## ✨ 核心特性
+
+### 🎯 **基于 Zap 官方推荐**
+- 使用 `zap.Config` 和官方配置结构
+- 支持 `zap.NewProductionConfig()` 和 `zap.NewDevelopmentConfig()`
+- 完整的编码器配置和输出配置
+
+### 📁 **灵活的日志输出**
+- **控制台输出**: `stdout`, `stderr`
+- **文件输出**: 支持日志轮转和压缩
+- **按日分包**: 自动按日期创建目录
+- **按级别分文件**: 不同级别写入不同文件
+
+### 🔧 **智能配置**
+- 根据环境自动选择最佳配置
+- 支持选项模式配置
+- 完整的默认值设置
+
+## 🏗️ 架构设计
+
+```
+应用代码 → Logger接口 → LoggerFactory → Zap核心 → 输出目标
+```
+
+### **核心组件**
+
+1. **`Logger` 接口**: 统一的日志接口
+2. **`ZapLogger`**: 基于 Zap 的日志实现
+3. **`LevelLogger`**: 级别分文件日志器
+4. **`LoggerFactory`**: 日志器工厂，支持多种创建方式
+
+## 📖 使用方法
+
+### **1. 基础使用**
+
+```go
+import "tyapi-server/internal/shared/logger"
+
+// 创建日志器
+log, err := logger.NewLogger(logger.Config{
+    Level:   "info",
+    Format:  "json",
+    Output:  "file",
+    LogDir:  "logs",
+    UseDaily: true,
+})
+if err != nil {
+    panic(err)
+}
+
+// 记录日志
+log.Info("应用启动成功", 
+    logger.String("version", "1.0.0"),
+    logger.String("environment", "production"),
+)
+```
+
+### **2. 使用日志工厂**
+
+```go
+// 创建工厂
+factory := logger.NewLoggerFactory(logger.Config{
+    Level:       "info",
+    Format:      "json",
+    Output:      "file",
+    Development: false, // 生产环境
+})
+
+// 创建生产环境日志器
+prodLogger, err := factory.CreateProductionLogger()
+if err != nil {
+    panic(err)
+}
+
+// 创建开发环境日志器
+devLogger, err := factory.CreateDevelopmentLogger()
+if err != nil {
+    panic(err)
+}
+
+// 根据环境自动选择
+autoLogger, err := factory.CreateLoggerByEnvironment()
+if err != nil {
+    panic(err)
+}
+```
+
+### **3. 选项模式配置**
+
+```go
+// 使用选项模式
+logger, err := factory.CreateLoggerWithOptions(
+    logger.WithLevel("debug"),
+    logger.WithFormat("console"),
+    logger.WithOutput("stdout"),
+    logger.WithDevelopment(true),
+    logger.WithColor(true),
+)
+```
+
+### **4. 级别分文件日志器**
+
+```go
+// 创建级别分文件日志器
+levelConfig := logger.LevelLoggerConfig{
+    BaseConfig: logger.Config{
+        Level:    "info",
+        Format:   "json",
+        Output:   "file",
+        LogDir:   "logs",
+        UseDaily: true,
+    },
+    EnableLevelSeparation: true,
+    LevelConfigs: map[zapcore.Level]logger.LevelFileConfig{
+        zapcore.InfoLevel: {
+            MaxSize:    100,
+            MaxBackups: 5,
+            MaxAge:     30,
+            Compress:   true,
+        },
+        zapcore.ErrorLevel: {
+            MaxSize:    200,
+            MaxBackups: 10,
+            MaxAge:     90,
+            Compress:   true,
+        },
+    },
+}
+
+levelLogger, err := logger.NewLevelLogger(levelConfig)
+if err != nil {
+    panic(err)
+}
+
+// 不同级别的日志会写入不同文件
+levelLogger.Info("这是一条信息日志")  // 写入 logs/2024-01-01/info.log
+levelLogger.Error("这是一条错误日志") // 写入 logs/2024-01-01/error.log
+```
+
+### **5. 结构化日志**
+
+```go
+// 使用 With 添加字段
+userLogger := log.With(
+    logger.String("user_id", "12345"),
+    logger.String("action", "login"),
+)
+
+userLogger.Info("用户登录成功", 
+    logger.String("ip", "192.168.1.1"),
+    logger.String("user_agent", "Mozilla/5.0..."),
+)
+
+// 使用 WithContext 从上下文提取字段
+ctx := context.WithValue(context.Background(), "request_id", "req_123")
+ctx = context.WithValue(ctx, "user_id", "user_456")
+ctx = context.WithValue(ctx, "trace_id", "trace_789")
+
+contextLogger := log.WithContext(ctx)
+contextLogger.Info("处理请求", 
+    logger.String("endpoint", "/api/users"),
+    logger.Int("status_code", 200),
+)
+```
+
+### **6. 命名日志器**
+
+```go
+// 创建命名日志器
+dbLogger := log.Named("database")
+dbLogger.Info("数据库连接成功", 
+    logger.String("host", "localhost"),
+    logger.String("database", "tyapi"),
+)
+
+apiLogger := log.Named("api")
+apiLogger.Info("API 请求处理", 
+    logger.String("method", "GET"),
+    logger.String("path", "/api/v1/users"),
+)
+```
+
+## ⚙️ 配置说明
+
+### **基础配置**
+
+```yaml
+logger:
+    # 基础配置
+    level: "info"                    # 日志级别
+    format: "json"                   # 输出格式
+    output: "file"                   # 输出方式
+    log_dir: "logs"                  # 日志目录
+    use_daily: true                  # 是否按日分包
+    use_color: false                 # 是否使用彩色输出
+    
+    # 文件配置
+    max_size: 100                    # 单个文件最大大小(MB)
+    max_backups: 5                   # 最大备份文件数
+    max_age: 30                      # 最大保留天数
+    compress: true                    # 是否压缩
+    
+    # 高级功能
+    enable_level_separation: true    # 是否启用按级别分文件
+    development: true                # 是否为开发环境
+```
+
+### **级别配置**
+
+```yaml
+logger:
+    level_configs:
+        debug:
+            max_size: 50             # 50MB
+            max_backups: 3
+            max_age: 7               # 7天
+            compress: true
+        info:
+            max_size: 100            # 100MB
+            max_backups: 5
+            max_age: 30              # 30天
+            compress: true
+        error:
+            max_size: 200            # 200MB
+            max_backups: 10
+            max_age: 90              # 90天
+            compress: true
+```
+
+## 🔍 日志级别
+
+### **级别说明**
+- **`debug`**: 调试信息，开发环境使用
+- **`info`**: 一般信息，记录应用状态
+- **`warn`**: 警告信息，需要注意但不影响运行
+- **`error`**: 错误信息，操作失败但可恢复
+- **`fatal`**: 致命错误，应用无法继续运行
+- **`panic`**: 恐慌错误，程序崩溃
+
+### **级别选择建议**
+- **开发环境**: `debug` 或 `info`
+- **测试环境**: `info` 或 `warn`
+- **生产环境**: `warn` 或 `error`
+
+## 📊 日志格式
+
+### **JSON 格式（推荐）**
+```json
+{
+    "level": "info",
+    "timestamp": "2024-01-01T12:00:00.000Z",
+    "logger": "main",
+    "caller": "main.go:25",
+    "message": "应用启动成功",
+    "version": "1.0.0",
+    "environment": "production"
+}
+```
+
+### **Console 格式（开发环境）**
+```
+2024-01-01T12:00:00.000Z    INFO    main/main.go:25    应用启动成功    {"version": "1.0.0", "environment": "production"}
+```
+
+## 🚀 性能优化
+
+### **Zap 官方推荐**
+- 使用结构化字段而不是字符串拼接
+- 避免在日志记录时进行复杂计算
+- 合理设置日志级别，避免过度记录
+
+### **最佳实践**
+```go
+// ✅ 推荐：使用结构化字段
+log.Info("用户操作", 
+    logger.String("user_id", userID),
+    logger.String("action", action),
+    logger.String("resource", resource),
+)
+
+// ❌ 不推荐：字符串拼接
+log.Info(fmt.Sprintf("用户 %s 执行了 %s 操作，资源: %s", userID, action, resource))
+```
+
+## 🔧 故障排除
+
+### **常见问题**
+
+1. **日志文件未创建**
+   - 检查目录权限
+   - 确认配置中的 `log_dir` 路径
+
+2. **日志级别不生效**
+   - 检查配置中的 `level` 值
+   - 确认日志器创建时使用了正确的配置
+
+3. **按级别分文件不工作**
+   - 确认 `enable_level_separation: true`
+   - 检查 `level_configs` 配置
+
+4. **按日分包不工作**
+   - 确认 `use_daily: true`
+   - 检查日期格式是否正确
+
+### **调试技巧**
+
+```go
+// 启用调试模式
+log.SetLevel(zapcore.DebugLevel)
+
+// 检查日志器配置
+if zapLogger, ok := log.(*logger.ZapLogger); ok {
+    config := zapLogger.GetConfig()
+    fmt.Printf("日志器配置: %+v\n", config)
+}
+```
+
+## 📚 更多资源
+
+- [Zap 官方文档](https://pkg.go.dev/go.uber.org/zap)
+- [Zap 最佳实践](https://github.com/uber-go/zap/blob/master/FAQ.md)
+- [结构化日志指南](https://github.com/uber-go/zap/blob/master/FAQ.md#q-how-do-i-choose-between-the-json-and-console-encoders)
+
+## 🎉 总结
+
+新的日志系统完全基于 Zap 官方最佳实践，提供了：
+
+1. **高性能**: Zap 是 Go 生态中性能最好的日志库
+2. **结构化**: 支持结构化字段，便于日志分析
+3. **灵活性**: 支持多种输出方式和配置选项
+4. **生产就绪**: 支持日志轮转、压缩、清理等生产环境需求
+5. **官方推荐**: 完全按照 Zap 官方文档实现，确保最佳实践
+
+使用新的日志系统，您将获得更好的性能、更清晰的日志结构和更强大的功能！