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,383 @@
+# 🚀 西部数据日志系统使用指南
+
+## 概述
+
+西部数据服务现在集成了完整的日志记录系统，支持请求、响应、错误和性能四种类型的日志记录，每种类型都有独立的日志文件。
+
+## 📝 日志记录范围
+
+### ✅ **会记录日志的操作**
+- `CallAPI()` - 调用西部数据API
+- `G05HZ01CallAPI()` - 调用G05HZ01 API
+
+### ❌ **不会记录日志的操作**
+- `Encrypt()` - 内部加密方法
+- `Md5Encrypt()` - 内部MD5加密方法
+
+**说明**: 加密解密是内部工具方法，调用频率高且不涉及外部API，因此不记录日志以提高性能。日志系统专注于记录外部API调用的完整生命周期。
+
+## ✨ 核心特性
+
+### 1. **四种日志类型**
+- **请求日志**: 记录所有API请求的详细信息
+- **响应日志**: 记录所有API响应的详细信息  
+- **错误日志**: 记录所有错误和异常情况
+- **性能日志**: 记录请求耗时和性能指标
+
+### 2. **日志文件分离**
+```
+logs/
+├── westdex/
+│   ├── 2024-01-01/
+│   │   ├── request.log      # 请求日志
+│   │   ├── response.log     # 响应日志
+│   │   ├── error.log        # 错误日志
+│   │   └── performance.log  # 性能日志
+│   └── 2024-01-02/
+│       ├── request.log
+│       ├── response.log
+│       ├── error.log
+│       └── performance.log
+```
+
+### 3. **请求追踪**
+- 每个请求都有唯一的请求ID
+- 请求和响应日志通过请求ID关联
+- 支持完整的请求链路追踪
+
+### 4. **性能监控**
+- 记录每个API调用的耗时
+- 区分成功和失败的请求
+- 提供性能分析数据
+
+## 🏗️ 配置说明
+
+### 配置文件设置
+
+在 `config.yaml` 中添加西部数据日志配置：
+
+```yaml
+westdex:
+    url: "https://apimaster.westdex.com.cn/api/invoke"
+    key: "your-key"
+    secret_id: "your-secret-id"
+    secret_second_id: "your-secret-second-id"
+    
+    # 西部数据日志配置
+    logging:
+        enabled: true                    # 启用日志记录
+        log_dir: "logs/westdex"         # 日志目录
+        use_daily: true                 # 按日分包
+        enable_level_separation: true   # 启用级别分离
+        
+        # 各级别配置
+        level_configs:
+            request:
+                max_size: 100           # 100MB
+                max_backups: 5          # 5个备份
+                max_age: 30             # 30天
+                compress: true          # 启用压缩
+            response:
+                max_size: 100
+                max_backups: 5
+                max_age: 30
+                compress: true
+            error:
+                max_size: 200           # 错误日志文件更大
+                max_backups: 10         # 更多备份
+                max_age: 90             # 保留更久
+                compress: true
+            performance:
+                max_size: 100
+                max_backups: 5
+                max_age: 30
+                compress: true
+```
+
+## 🚀 使用方法
+
+### 1. 使用配置创建服务
+
+```go
+package main
+
+import (
+    "tyapi-server/internal/config"
+    "tyapi-server/internal/infrastructure/external/westdex"
+)
+
+func main() {
+    // 加载配置
+    cfg := &config.Config{
+        // ... 配置内容
+    }
+    
+    // 使用配置创建西部数据服务
+    service, err := westdex.NewWestDexServiceWithConfig(cfg)
+    if err != nil {
+        panic(err)
+    }
+    
+    // 使用服务
+    resp, err := service.CallAPI("G05HZ01", map[string]interface{}{
+        "param1": "value1",
+        "param2": "value2",
+    })
+    
+    if err != nil {
+        // 错误会自动记录到错误日志
+        log.Printf("API调用失败: %v", err)
+        return
+    }
+    
+    // 成功响应会自动记录到响应日志
+    log.Printf("API调用成功: %s", string(resp))
+}
+```
+
+### 2. 使用自定义日志配置
+
+```go
+// 创建自定义日志配置
+loggingConfig := westdex.WestDexLoggingConfig{
+    Enabled:              true,
+    LogDir:               "logs/custom_westdex",
+    UseDaily:             true,
+    EnableLevelSeparation: true,
+    LevelConfigs: map[string]westdex.WestDexLevelFileConfig{
+        "request": {
+            MaxSize:    50,
+            MaxBackups: 3,
+            MaxAge:     7,
+            Compress:   true,
+        },
+        "error": {
+            MaxSize:    100,
+            MaxBackups: 5,
+            MaxAge:     30,
+            Compress:   true,
+        },
+    },
+}
+
+// 使用自定义配置创建服务
+service, err := westdex.NewWestDexServiceWithLogging(
+    "https://api.example.com",
+    "your-key",
+    "your-secret-id",
+    "your-secret-second-id",
+    loggingConfig,
+)
+```
+
+## 📊 日志示例
+
+### 请求日志示例
+
+```json
+{
+  "level": "info",
+  "msg": "西部数据API请求",
+  "request_id": "westdex_a1b2c3d4",
+  "api_code": "G05HZ01",
+  "url": "https://apimaster.westdex.com.cn/api/invoke/449159/G05HZ01?timestamp=1704096000000",
+  "request_data": {
+    "param1": "value1",
+    "param2": "value2"
+  },
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+### 响应日志示例
+
+```json
+{
+  "level": "info",
+  "msg": "西部数据API响应",
+  "request_id": "westdex_a1b2c3d4",
+  "api_code": "G05HZ01",
+  "status_code": 200,
+  "response_data": "{\"code\":\"0000\",\"data\":\"...\",\"message\":\"success\"}",
+  "duration": "150ms",
+  "timestamp": "2024-01-01T12:00:01Z"
+}
+```
+
+### 错误日志示例
+
+```json
+{
+  "level": "error",
+  "msg": "西部数据API错误",
+  "request_id": "westdex_a1b2c3d4",
+  "api_code": "G05HZ01",
+  "error": "数据源异常: 查询失败",
+  "request_data": {
+    "param1": "value1",
+    "param2": "value2"
+  },
+  "timestamp": "2024-01-01T12:00:01Z"
+}
+```
+
+### 性能日志示例
+
+```json
+{
+  "level": "info",
+  "msg": "西部数据API性能",
+  "request_id": "westdex_a1b2c3d4",
+  "api_code": "G05HZ01",
+  "duration": "150ms",
+  "success": true,
+  "timestamp": "2024-01-01T12:00:01Z"
+}
+```
+
+## 🔍 日志字段说明
+
+### 通用字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `request_id` | string | 请求唯一标识符 |
+| `api_code` | string | API代码 |
+| `timestamp` | string | 时间戳（ISO8601格式） |
+
+### 请求日志字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | 完整的请求URL |
+| `request_data` | object | 请求数据 |
+
+### 响应日志字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status_code` | int | HTTP状态码 |
+| `response_data` | string | 响应数据（JSON字符串） |
+| `duration` | duration | 请求耗时 |
+
+### 错误日志字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | error | 错误信息 |
+| `request_data` | object | 原始请求数据 |
+
+### 性能日志字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `duration` | duration | 请求耗时 |
+| `success` | bool | 是否成功 |
+
+## 🎯 最佳实践
+
+### 1. **日志配置优化**
+
+```yaml
+# 生产环境配置
+logging:
+    enabled: true
+    log_dir: "/var/log/westdex"
+    use_daily: true
+    enable_level_separation: true
+    level_configs:
+        request:
+            max_size: 200      # 更大的文件大小
+            max_backups: 10    # 更多备份
+            max_age: 90        # 保留更久
+        error:
+            max_size: 500      # 错误日志文件更大
+            max_backups: 20    # 更多备份
+            max_age: 180       # 保留更久
+```
+
+### 2. **日志分析**
+
+```bash
+# 查看请求日志
+tail -f logs/westdex/2024-01-01/request.log
+
+# 查看错误日志
+tail -f logs/westdex/2024-01-01/error.log
+
+# 查看性能日志
+tail -f logs/westdex/2024-01-01/performance.log
+
+# 统计API调用次数
+grep -c "G05HZ01" logs/westdex/2024-01-01/request.log
+
+# 统计错误率
+grep -c "error" logs/westdex/2024-01-01/error.log
+```
+
+### 3. **性能监控**
+
+```bash
+# 查看平均响应时间
+grep "duration" logs/westdex/2024-01-01/performance.log | \
+awk -F'"duration":"' '{print $2}' | \
+awk -F'"' '{print $1}' | \
+awk -F'ms' '{sum+=$1; count++} END {print "平均响应时间: " sum/count "ms"}'
+
+# 查看成功率
+total=$(grep -c "success" logs/westdex/2024-01-01/performance.log)
+success=$(grep -c '"success":true' logs/westdex/2024-01-01/performance.log)
+echo "成功率: $((success * 100 / total))%"
+```
+
+## 🚨 注意事项
+
+### 1. **日志文件管理**
+- 定期清理旧日志文件
+- 监控磁盘空间使用
+- 配置合适的日志轮转策略
+
+### 2. **敏感信息处理**
+- 日志中可能包含敏感数据
+- 确保日志文件访问权限
+- 考虑日志脱敏需求
+
+### 3. **性能影响**
+- 日志记录会增加少量性能开销
+- 异步日志记录可减少性能影响
+- 合理配置日志级别
+
+## 🔧 故障排除
+
+### 1. **日志文件未创建**
+- 检查日志目录权限
+- 确认日志配置已启用
+- 验证文件路径配置
+
+### 2. **日志记录不完整**
+- 检查日志器是否正确初始化
+- 确认请求ID生成逻辑
+- 验证错误处理流程
+
+### 3. **性能问题**
+- 检查日志文件大小和数量
+- 确认日志轮转配置
+- 监控磁盘I/O性能
+
+## 🎉 总结
+
+西部数据日志系统提供了完整的API调用追踪能力：
+
+1. **请求追踪**: 通过唯一请求ID关联请求和响应
+2. **错误监控**: 记录所有错误和异常情况
+3. **性能分析**: 提供详细的性能指标
+4. **文件管理**: 支持按日期分包和级别分离
+5. **配置灵活**: 支持自定义日志配置
+
+通过合理使用这个日志系统，您可以：
+- 快速定位API调用问题
+- 监控系统性能和稳定性
+- 分析API使用模式和趋势
+- 提高问题排查效率
+
+现在您的西部数据服务已经具备了完整的日志记录能力！🚀