265 lines
7.5 KiB
Markdown
265 lines
7.5 KiB
Markdown
# 通用外部服务日志系统
|
||
|
||
## 概述
|
||
|
||
这是一个为外部服务（如 westdex、zhicha、yushan 等）提供统一日志记录功能的通用系统。所有外部服务共享相同的日志基础架构，但保持各自独立的日志文件目录。
|
||
|
||
## 设计目标
|
||
|
||
1. **代码复用**: 避免重复的日志实现代码
|
||
2. **统一格式**: 所有外部服务使用相同的日志格式
|
||
3. **独立存储**: 每个服务的日志存储在独立目录中
|
||
4. **灵活配置**: 支持每个服务独立的日志配置
|
||
5. **易于扩展**: 新增外部服务时只需简单配置
|
||
|
||
## 架构特点
|
||
|
||
### 1. 共享核心
|
||
- 统一的日志接口
|
||
- 相同的日志格式
|
||
- 一致的配置结构
|
||
- 共用的文件轮转策略
|
||
|
||
### 2. 服务分离
|
||
- 每个服务有独立的日志目录
|
||
- 通过 `service` 字段区分来源
|
||
- 可独立配置每个服务的日志参数
|
||
- 支持按级别分离日志文件
|
||
|
||
### 3. 配置灵活
|
||
- 支持从配置文件读取
|
||
- 支持自定义配置创建
|
||
- 支持简单模式（无日志）
|
||
- 支持日志级别分离
|
||
|
||
## 已集成的服务
|
||
|
||
### 1. WestDex (西部数据)
|
||
- 服务名称: `westdex`
|
||
- 日志目录: `logs/external_services/westdex/`
|
||
- 主要功能: 企业信息查询
|
||
|
||
### 2. Zhicha (智查金控)
|
||
- 服务名称: `zhicha`
|
||
- 日志目录: `logs/external_services/zhicha/`
|
||
- 主要功能: 企业信息查询、AES加密
|
||
|
||
### 3. Yushan (羽山)
|
||
- 服务名称: `yushan`
|
||
- 日志目录: `logs/external_services/yushan/`
|
||
- 主要功能: 企业信息查询、AES加密
|
||
|
||
## 日志格式
|
||
|
||
所有服务的日志都包含以下标准字段：
|
||
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"timestamp": "2024-01-01T12:00:00Z",
|
||
"msg": "服务名 API请求",
|
||
"service": "服务名",
|
||
"request_id": "服务名_唯一ID",
|
||
"api_code": "API代码",
|
||
"url": "请求URL",
|
||
"params": "请求参数",
|
||
"status_code": "响应状态码",
|
||
"response": "响应内容",
|
||
"duration": "请求耗时",
|
||
"error": "错误信息"
|
||
}
|
||
```
|
||
|
||
## 配置结构
|
||
|
||
```yaml
|
||
# 外部服务日志根目录
|
||
external_services_log_dir: "./logs/external_services"
|
||
|
||
# 各服务配置
|
||
westdex:
|
||
logging:
|
||
enabled: true
|
||
log_dir: "./logs/external_services"
|
||
service_name: "westdex"
|
||
use_daily: true # 启用按天分隔
|
||
enable_level_separation: true # 启用级别分离
|
||
level_configs:
|
||
info: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
error: { max_size: 200, max_backups: 10, max_age: 90, compress: true }
|
||
warn: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
|
||
zhicha:
|
||
logging:
|
||
enabled: true
|
||
log_dir: "./logs/external_services"
|
||
service_name: "zhicha"
|
||
use_daily: true # 启用按天分隔
|
||
enable_level_separation: true # 启用级别分离
|
||
level_configs:
|
||
info: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
error: { max_size: 200, max_backups: 10, max_age: 90, compress: true }
|
||
warn: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
|
||
yushan:
|
||
logging:
|
||
enabled: true
|
||
log_dir: "./logs/external_services"
|
||
service_name: "yushan"
|
||
use_daily: true # 启用按天分隔
|
||
enable_level_separation: true # 启用级别分离
|
||
level_configs:
|
||
info: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
error: { max_size: 200, max_backups: 10, max_age: 90, compress: true }
|
||
warn: { max_size: 100, max_backups: 3, max_age: 28, compress: true }
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 从配置创建服务
|
||
```go
|
||
// 推荐方式：从配置文件创建
|
||
westdexService, err := westdex.NewWestDexServiceWithConfig(cfg)
|
||
zhichaService, err := zhicha.NewZhichaServiceWithConfig(cfg)
|
||
yushanService, err := yushan.NewYushanServiceWithConfig(cfg)
|
||
```
|
||
|
||
### 2. 自定义日志配置
|
||
```go
|
||
loggingConfig := external_logger.ExternalServiceLoggingConfig{
|
||
Enabled: true,
|
||
LogDir: "./logs/external_services",
|
||
ServiceName: "custom_service",
|
||
EnableLevelSeparation: true,
|
||
// ... 其他配置
|
||
}
|
||
|
||
service := NewCustomServiceWithLogging(url, key, secret, loggingConfig)
|
||
```
|
||
|
||
### 3. 简单模式（无日志）
|
||
```go
|
||
// 创建无日志的服务实例
|
||
service := NewServiceSimple(url, key, secret)
|
||
```
|
||
|
||
## 日志级别
|
||
|
||
### 1. INFO 级别
|
||
- API 请求日志
|
||
- API 响应日志
|
||
- 一般信息日志
|
||
|
||
### 2. WARN 级别
|
||
- 警告信息
|
||
- 非致命错误
|
||
|
||
### 3. ERROR 级别
|
||
- API 调用错误
|
||
- 系统异常
|
||
- 业务逻辑错误
|
||
|
||
## 文件轮转策略
|
||
|
||
### 1. 按大小+时间混合分隔
|
||
|
||
系统支持两种日志分隔策略：
|
||
|
||
#### 按天分隔（推荐）
|
||
- **UseDaily**: 设置为 `true` 时启用
|
||
- 每天创建新的日期目录：`logs/westdex/2024-01-01/`
|
||
- 在日期目录下按级别分隔：`westdex_info.log`、`westdex_error.log`、`westdex_warn.log`
|
||
- 自动清理过期的日期目录
|
||
|
||
#### 传统方式
|
||
- **UseDaily**: 设置为 `false` 时使用
|
||
- 直接在服务目录下按级别分隔：`logs/westdex/westdex_info.log`
|
||
|
||
### 2. 文件轮转配置
|
||
|
||
每个日志级别都支持以下轮转配置：
|
||
|
||
- **MaxSize**: 单个文件最大大小（MB）
|
||
- **MaxBackups**: 最大备份文件数
|
||
- **MaxAge**: 最大保留天数
|
||
- **Compress**: 是否压缩旧文件
|
||
|
||
### 3. 目录结构示例
|
||
|
||
```
|
||
logs/
|
||
├── westdex/
|
||
│ ├── 2024-01-01/
|
||
│ │ ├── westdex_info.log
|
||
│ │ ├── westdex_error.log
|
||
│ │ └── westdex_warn.log
|
||
│ ├── 2024-01-02/
|
||
│ │ ├── westdex_info.log
|
||
│ │ ├── westdex_error.log
|
||
│ │ └── westdex_warn.log
|
||
│ └── westdex_info.log (回退文件)
|
||
├── zhicha/
|
||
│ ├── 2024-01-01/
|
||
│ │ ├── zhicha_info.log
|
||
│ │ ├── zhicha_error.log
|
||
│ │ └── zhicha_warn.log
|
||
│ └── zhicha_info.log (回退文件)
|
||
└── yushan/
|
||
├── 2024-01-01/
|
||
│ ├── yushan_info.log
|
||
│ ├── yushan_error.log
|
||
│ └── yushan_warn.log
|
||
└── yushan_info.log (回退文件)
|
||
```
|
||
|
||
## 扩展新服务
|
||
|
||
要添加新的外部服务，只需：
|
||
|
||
1. 在服务中使用 `external_logger.ExternalServiceLogger`
|
||
2. 设置合适的 `ServiceName`
|
||
3. 使用统一的日志接口
|
||
4. 在配置文件中添加相应的日志配置
|
||
|
||
```go
|
||
// 新服务示例
|
||
func NewCustomService(config CustomConfig) *CustomService {
|
||
loggingConfig := external_logger.ExternalServiceLoggingConfig{
|
||
ServiceName: "custom_service",
|
||
LogDir: config.LogDir,
|
||
// ... 其他配置
|
||
}
|
||
|
||
logger, _ := external_logger.NewExternalServiceLogger(loggingConfig)
|
||
|
||
return &CustomService{
|
||
config: config,
|
||
logger: logger,
|
||
}
|
||
}
|
||
```
|
||
|
||
## 优势总结
|
||
|
||
1. **维护简便**: 只需维护一套日志代码
|
||
2. **格式统一**: 所有服务使用相同的日志格式
|
||
3. **配置灵活**: 支持每个服务独立的配置
|
||
4. **易于扩展**: 新增服务只需简单配置
|
||
5. **性能优化**: 共享的日志基础设施
|
||
6. **监控友好**: 统一的日志格式便于监控和分析
|
||
7. **智能分隔**: 支持按大小+时间混合分隔策略
|
||
8. **自动清理**: 自动清理过期的日志目录，节省磁盘空间
|
||
9. **故障回退**: 如果按天分隔失败，自动回退到传统方式
|
||
|
||
## 注意事项
|
||
|
||
1. 确保日志目录有足够的磁盘空间
|
||
2. 定期清理过期的日志文件
|
||
3. 监控日志文件大小，避免磁盘空间不足
|
||
4. 在生产环境中建议启用日志压缩
|
||
5. 根据业务需求调整日志保留策略
|
||
6. 启用按天分隔时，确保系统时间准确
|
||
7. 监控自动清理任务的执行情况
|
||
8. 建议在生产环境中设置合理的 `MaxAge` 值，避免日志文件过多
|
||
|