384 lines
9.5 KiB
Markdown
384 lines
9.5 KiB
Markdown
# 🚀 西部数据日志系统使用指南
|
||
|
||
## 概述
|
||
|
||
西部数据服务现在集成了完整的日志记录系统，支持请求、响应、错误和性能四种类型的日志记录，每种类型都有独立的日志文件。
|
||
|
||
## 📝 日志记录范围
|
||
|
||
### ✅ **会记录日志的操作**
|
||
- `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使用模式和趋势
|
||
- 提高问题排查效率
|
||
|
||
现在您的西部数据服务已经具备了完整的日志记录能力！🚀
|