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. 基础使用**

```go
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. 使用日志工厂**

```go
// 创建工厂
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. 选项模式配置**

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

### **4. 级别分文件日志器**

```go
// 创建级别分文件日志器
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. 结构化日志**

```go
// 使用 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. 命名日志器**

```go
// 创建命名日志器
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"),
)
```

## ⚙️ 配置说明

### **基础配置**

```yaml
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                # 是否为开发环境
```

### **级别配置**

```yaml
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 格式（推荐）**
```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 官方推荐**
- 使用结构化字段而不是字符串拼接
- 避免在日志记录时进行复杂计算
- 合理设置日志级别，避免过度记录

### **最佳实践**
```go
// ✅ 推荐：使用结构化字段
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`
   - 检查日期格式是否正确

### **调试技巧**

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

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

## 📚 更多资源

- [Zap 官方文档](https://pkg.go.dev/go.uber.org/zap)
- [Zap 最佳实践](https://github.com/uber-go/zap/blob/master/FAQ.md)
- [结构化日志指南](https://github.com/uber-go/zap/blob/master/FAQ.md#q-how-do-i-choose-between-the-json-and-console-encoders)

## 🎉 总结

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

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

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