tyapi-server/docs/西部数据日志系统使用指南.md

# 🚀 西部数据日志系统使用指南

## 概述

西部数据服务现在集成了完整的日志记录系统，支持请求、响应、错误和性能四种类型的日志记录，每种类型都有独立的日志文件。

## 📝 日志记录范围

### ✅ **会记录日志的操作**
- `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使用模式和趋势
- 提高问题排查效率

现在您的西部数据服务已经具备了完整的日志记录能力！🚀