tyapi-server/internal/shared/external_logger

通用外部服务日志系统

概述

这是一个为外部服务（如 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加密

日志格式

所有服务的日志都包含以下标准字段：

{
  "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": "错误信息"
}

配置结构

# 外部服务日志根目录
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 }
    # 新增：请求和响应日志的独立配置
    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:
  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 }
    # 新增：请求和响应日志的独立配置
    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 }

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. 从配置创建服务

// 推荐方式：从配置文件创建
westdexService, err := westdex.NewWestDexServiceWithConfig(cfg)
zhichaService, err := zhicha.NewZhichaServiceWithConfig(cfg)
yushanService, err := yushan.NewYushanServiceWithConfig(cfg)

2. 自定义日志配置

loggingConfig := external_logger.ExternalServiceLoggingConfig{
    Enabled: true,
    LogDir: "./logs/external_services",
    ServiceName: "custom_service",
    EnableLevelSeparation: true,
    // ... 其他配置
}

service := NewCustomServiceWithLogging(url, key, secret, loggingConfig)

3. 简单模式（无日志）

// 创建无日志的服务实例
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. 在配置文件中添加相应的日志配置

// 新服务示例
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 值，避免日志文件过多