# 🚀 新日志系统使用指南 ## 概述 本项目已重新设计日志系统，完全基于 **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 官方文档实现，确保最佳实践 使用新的日志系统，您将获得更好的性能、更清晰的日志结构和更强大的功能！