tyapi-server/internal/shared/external_logger/example_usage.md

# 通用外部服务日志系统使用示例

## 概述

这个通用的外部服务日志系统允许 westdex 和 zhicha 服务共享相同的日志基础架构，但保持各自独立的日志文件目录。

## 目录结构

使用共享日志系统后，日志目录结构如下：

```
logs/
├── external_services/           # 外部服务日志根目录
│   ├── westdex/                # westdex 服务日志
│   │   ├── westdex_info.log
│   │   ├── westdex_error.log
│   │   ├── westdex_warn.log
│   │   ├── westdex_request.log    # 新增：请求日志文件
│   │   └── westdex_response.log   # 新增：响应日志文件
│   ├── zhicha/                 # zhicha 服务日志
│   │   ├── zhicha_info.log
│   │   ├── zhicha_error.log
│   │   ├── zhicha_warn.log
│   │   ├── zhicha_request.log    # 新增：请求日志文件
│   │   └── zhicha_response.log   # 新增：响应日志文件
│   └── yushan/                 # yushan 服务日志
│       ├── yushan_info.log
│       ├── yushan_error.log
│       ├── yushan_warn.log
│       ├── yushan_request.log    # 新增：请求日志文件
│       └── yushan_response.log   # 新增：响应日志文件
```

## 配置示例

### 1. 在 config.yaml 中配置

```yaml
# 外部服务日志根目录
external_services_log_dir: "./logs/external_services"

# westdex 配置
westdex:
  url: "https://api.westdex.com"
  key: "your_key"
  secret_id: "your_secret_id"
  secret_second_id: "your_secret_second_id"
  logging:
    enabled: true
    log_dir: "./logs/external_services"  # 使用共享根目录
    enable_level_separation: true
    level_configs:
      info:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      error:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      warn:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
    # 新增：请求和响应日志的独立配置
    request_log_config:
      max_size: 100
      max_backups: 5
      max_age: 30
      compress: true
    response_log_config:
      max_size: 100
      max_backups: 5
      max_age: 30
      compress: true

# zhicha 配置
zhicha:
  url: "https://www.zhichajinkong.com/dataMiddle/api/handle"
  app_id: "your_app_id"
  app_secret: "your_app_secret"
  pro_id: "your_pro_id"
  logging:
    enabled: true
    log_dir: "./logs/external_services"  # 使用共享根目录
    enable_level_separation: true
    level_configs:
      info:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      error:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      warn:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true

# yushan 配置
yushan:
  url: "https://api.yushan.com"
  api_key: "your_api_key"
  acct_id: "your_acct_id"
  logging:
    enabled: true
    log_dir: "./logs/external_services"  # 使用共享根目录
    enable_level_separation: true
    level_configs:
      info:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      error:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
      warn:
        max_size: 100
        max_backups: 3
        max_age: 28
        compress: true
```

## 使用方法

### 1. 创建 WestDex 服务
```go
import "tyapi-server/internal/infrastructure/external/westdex"

// 从配置创建（推荐）
westdexService, err := westdex.NewWestDexServiceWithConfig(cfg)
if err != nil {
    log.Fatal(err)
}

// 使用自定义日志配置
loggingConfig := external_logger.ExternalServiceLoggingConfig{
    Enabled: true,
    LogDir: "./logs/external_services",
    ServiceName: "westdex", // 会自动设置
    EnableLevelSeparation: true,
    // ... 其他配置
}

westdexService, err := westdex.NewWestDexServiceWithLogging(
    "url", "key", "secretID", "secretSecondID", 
    loggingConfig,
)
```

### 2. 创建 Zhicha 服务
```go
import "tyapi-server/internal/infrastructure/external/zhicha"

// 从配置创建（推荐）
zhichaService, err := zhicha.NewZhichaServiceWithConfig(cfg)
if err != nil {
    log.Fatal(err)
}

// 使用自定义日志配置
loggingConfig := external_logger.ExternalServiceLoggingConfig{
    Enabled: true,
    LogDir: "./logs/external_services",
    ServiceName: "zhicha", // 会自动设置
    EnableLevelSeparation: true,
    // ... 其他配置
}

zhichaService, err := zhicha.NewZhichaServiceWithLogging(
    "url", "appID", "appSecret", "proID",
    loggingConfig,
)
```

### 3. 创建 Yushan 服务
```go
import "tyapi-server/internal/infrastructure/external/yushan"

// 从配置创建（推荐）
yushanService, err := yushan.NewYushanServiceWithConfig(cfg)
if err != nil {
    log.Fatal(err)
}

// 使用自定义日志配置
loggingConfig := external_logger.ExternalServiceLoggingConfig{
    Enabled: true,
    LogDir: "./logs/external_services",
    ServiceName: "yushan", // 会自动设置
    EnableLevelSeparation: true,
    // ... 其他配置
}

yushanService, err := yushan.NewYushanServiceWithLogging(
    "url", "apiKey", "acctID",
    loggingConfig,
)
```

## 日志内容示例

### WestDex 日志内容
```json
{
  "level": "INFO",
  "timestamp": "2024-01-01T12:00:00Z",
  "msg": "westdex API请求",
  "service": "westdex",
  "request_id": "westdex_12345678",
  "api_code": "G05HZ01",
  "url": "https://api.westdex.com/G05HZ01",
  "params": {...}
}
```

### Zhicha 日志内容
```json
{
  "level": "INFO", 
  "timestamp": "2024-01-01T12:00:00Z",
  "msg": "zhicha API请求",
  "service": "zhicha",
  "request_id": "zhicha_87654321",
  "api_code": "handle",
  "url": "https://www.zhichajinkong.com/dataMiddle/api/handle",
  "params": {...}
}
```

### Yushan 日志内容
```json
{
  "level": "INFO",
  "timestamp": "2024-01-01T12:00:00Z", 
  "msg": "yushan API请求",
  "service": "yushan",
  "request_id": "yushan_12345678",
  "api_code": "G05HZ01",
  "url": "https://api.yushan.com",
  "params": {...}
}
```

## 优势

### 1. 代码复用
- 相同的日志基础架构
- 统一的日志格式
- 相同的配置结构

### 2. 维护简便
- 只需维护一套日志代码
- 统一的日志级别管理
- 统一的文件轮转策略

### 3. 清晰分离
- 每个服务有独立的日志目录
- 通过 `service` 字段区分来源
- 可独立配置每个服务的日志参数

### 4. 扩展性
- 易于添加新的外部服务
- 统一的日志接口
- 灵活的配置选项

## 添加新的外部服务

要添加新的外部服务（如 TianYanCha），只需：

1. 在服务中使用 `external_logger.ExternalServiceLogger`
2. 设置合适的 `ServiceName`
3. 使用统一的日志接口

```go
// 新服务示例
func NewTianYanChaService(config TianYanChaConfig) *TianYanChaService {
    loggingConfig := external_logger.ExternalServiceLoggingConfig{
        ServiceName: "tianyancha",
        LogDir: config.LogDir,
        // ... 其他配置
    }
    
    logger, _ := external_logger.NewExternalServiceLogger(loggingConfig)
    
    return &TianYanChaService{
        config: config,
        logger: logger,
    }
}
```

这样新服务的日志会自动保存到 `logs/external_services/tianyancha/` 目录。