tyapi-server/docs/新日志系统使用指南.md

🚀 新日志系统使用指南

概述

本项目已重新设计日志系统，完全基于 Zap 官方最佳实践，提供高性能、结构化的日志记录功能。

✨ 核心特性

🎯 基于 Zap 官方推荐

• 使用 zap.Config 和官方配置结构
• 支持 zap.NewProductionConfig() 和 zap.NewDevelopmentConfig()
• 完整的编码器配置和输出配置

📁 灵活的日志输出

• 控制台输出: stdout, stderr
• 文件输出: 支持日志轮转和压缩
• 按日分包: 自动按日期创建目录
• 按级别分文件: 不同级别写入不同文件

🔧 智能配置

• 根据环境自动选择最佳配置
• 支持选项模式配置
• 完整的默认值设置

🏗️ 架构设计

应用代码 → Logger接口 → LoggerFactory → Zap核心 → 输出目标

核心组件

1. Logger 接口: 统一的日志接口
2. ZapLogger: 基于 Zap 的日志实现
3. LevelLogger: 级别分文件日志器
4. LoggerFactory: 日志器工厂，支持多种创建方式

📖 使用方法

1. 基础使用

import "tyapi-server/internal/shared/logger"

// 创建日志器
log, err := logger.NewLogger(logger.Config{
    Level:   "info",
    Format:  "json",
    Output:  "file",
    LogDir:  "logs",
    UseDaily: true,
})
if err != nil {
    panic(err)
}

// 记录日志
log.Info("应用启动成功", 
    logger.String("version", "1.0.0"),
    logger.String("environment", "production"),
)

2. 使用日志工厂

// 创建工厂
factory := logger.NewLoggerFactory(logger.Config{
    Level:       "info",
    Format:      "json",
    Output:      "file",
    Development: false, // 生产环境
})

// 创建生产环境日志器
prodLogger, err := factory.CreateProductionLogger()
if err != nil {
    panic(err)
}

// 创建开发环境日志器
devLogger, err := factory.CreateDevelopmentLogger()
if err != nil {
    panic(err)
}

// 根据环境自动选择
autoLogger, err := factory.CreateLoggerByEnvironment()
if err != nil {
    panic(err)
}

3. 选项模式配置

// 使用选项模式
logger, err := factory.CreateLoggerWithOptions(
    logger.WithLevel("debug"),
    logger.WithFormat("console"),
    logger.WithOutput("stdout"),
    logger.WithDevelopment(true),
    logger.WithColor(true),
)

4. 级别分文件日志器

// 创建级别分文件日志器
levelConfig := logger.LevelLoggerConfig{
    BaseConfig: logger.Config{
        Level:    "info",
        Format:   "json",
        Output:   "file",
        LogDir:   "logs",
        UseDaily: true,
    },
    EnableLevelSeparation: true,
    LevelConfigs: map[zapcore.Level]logger.LevelFileConfig{
        zapcore.InfoLevel: {
            MaxSize:    100,
            MaxBackups: 5,
            MaxAge:     30,
            Compress:   true,
        },
        zapcore.ErrorLevel: {
            MaxSize:    200,
            MaxBackups: 10,
            MaxAge:     90,
            Compress:   true,
        },
    },
}

levelLogger, err := logger.NewLevelLogger(levelConfig)
if err != nil {
    panic(err)
}

// 不同级别的日志会写入不同文件
levelLogger.Info("这是一条信息日志")  // 写入 logs/2024-01-01/info.log
levelLogger.Error("这是一条错误日志") // 写入 logs/2024-01-01/error.log

5. 结构化日志

// 使用 With 添加字段
userLogger := log.With(
    logger.String("user_id", "12345"),
    logger.String("action", "login"),
)

userLogger.Info("用户登录成功", 
    logger.String("ip", "192.168.1.1"),
    logger.String("user_agent", "Mozilla/5.0..."),
)

// 使用 WithContext 从上下文提取字段
ctx := context.WithValue(context.Background(), "request_id", "req_123")
ctx = context.WithValue(ctx, "user_id", "user_456")
ctx = context.WithValue(ctx, "trace_id", "trace_789")

contextLogger := log.WithContext(ctx)
contextLogger.Info("处理请求", 
    logger.String("endpoint", "/api/users"),
    logger.Int("status_code", 200),
)

6. 命名日志器

// 创建命名日志器
dbLogger := log.Named("database")
dbLogger.Info("数据库连接成功", 
    logger.String("host", "localhost"),
    logger.String("database", "tyapi"),
)

apiLogger := log.Named("api")
apiLogger.Info("API 请求处理", 
    logger.String("method", "GET"),
    logger.String("path", "/api/v1/users"),
)

⚙️ 配置说明

基础配置

logger:
    # 基础配置
    level: "info"                    # 日志级别
    format: "json"                   # 输出格式
    output: "file"                   # 输出方式
    log_dir: "logs"                  # 日志目录
    use_daily: true                  # 是否按日分包
    use_color: false                 # 是否使用彩色输出
    
    # 文件配置
    max_size: 100                    # 单个文件最大大小(MB)
    max_backups: 5                   # 最大备份文件数
    max_age: 30                      # 最大保留天数
    compress: true                    # 是否压缩
    
    # 高级功能
    enable_level_separation: true    # 是否启用按级别分文件
    development: true                # 是否为开发环境

级别配置

logger:
    level_configs:
        debug:
            max_size: 50             # 50MB
            max_backups: 3
            max_age: 7               # 7天
            compress: true
        info:
            max_size: 100            # 100MB
            max_backups: 5
            max_age: 30              # 30天
            compress: true
        error:
            max_size: 200            # 200MB
            max_backups: 10
            max_age: 90              # 90天
            compress: true

🔍 日志级别

级别说明

• debug: 调试信息，开发环境使用
• info: 一般信息，记录应用状态
• warn: 警告信息，需要注意但不影响运行
• error: 错误信息，操作失败但可恢复
• fatal: 致命错误，应用无法继续运行
• panic: 恐慌错误，程序崩溃

级别选择建议

• 开发环境: debug 或 info
• 测试环境: info 或 warn
• 生产环境: warn 或 error

📊 日志格式

JSON 格式（推荐）

{
    "level": "info",
    "timestamp": "2024-01-01T12:00:00.000Z",
    "logger": "main",
    "caller": "main.go:25",
    "message": "应用启动成功",
    "version": "1.0.0",
    "environment": "production"
}

Console 格式（开发环境）

2024-01-01T12:00:00.000Z    INFO    main/main.go:25    应用启动成功    {"version": "1.0.0", "environment": "production"}

🚀 性能优化

Zap 官方推荐

• 使用结构化字段而不是字符串拼接
• 避免在日志记录时进行复杂计算
• 合理设置日志级别，避免过度记录

最佳实践

// ✅ 推荐：使用结构化字段
log.Info("用户操作", 
    logger.String("user_id", userID),
    logger.String("action", action),
    logger.String("resource", resource),
)

// ❌ 不推荐：字符串拼接
log.Info(fmt.Sprintf("用户 %s 执行了 %s 操作，资源: %s", userID, action, resource))

🔧 故障排除

常见问题

1. 日志文件未创建

   • 检查目录权限
   • 确认配置中的 log_dir 路径

2. 日志级别不生效

   • 检查配置中的 level 值
   • 确认日志器创建时使用了正确的配置

3. 按级别分文件不工作

   • 确认 enable_level_separation: true
   • 检查 level_configs 配置

4. 按日分包不工作

   • 确认 use_daily: true
   • 检查日期格式是否正确

调试技巧

// 启用调试模式
log.SetLevel(zapcore.DebugLevel)

// 检查日志器配置
if zapLogger, ok := log.(*logger.ZapLogger); ok {
    config := zapLogger.GetConfig()
    fmt.Printf("日志器配置: %+v\n", config)
}

📚 更多资源

• Zap 官方文档
• Zap 最佳实践
• 结构化日志指南

🎉 总结

新的日志系统完全基于 Zap 官方最佳实践，提供了：

1. 高性能: Zap 是 Go 生态中性能最好的日志库
2. 结构化: 支持结构化字段，便于日志分析
3. 灵活性: 支持多种输出方式和配置选项
4. 生产就绪: 支持日志轮转、压缩、清理等生产环境需求
5. 官方推荐: 完全按照 Zap 官方文档实现，确保最佳实践

使用新的日志系统，您将获得更好的性能、更清晰的日志结构和更强大的功能！