add JRZQ09J8、FLXGDEA8、FLXGDEA9、JRZQ1D09
add external_services log
This commit is contained in:
453
docs/Zap官方最佳实践日志系统指南.md
Normal file
453
docs/Zap官方最佳实践日志系统指南.md
Normal file
@@ -0,0 +1,453 @@
|
||||
# 🚀 Zap 官方最佳实践日志系统指南
|
||||
|
||||
## 概述
|
||||
|
||||
本日志系统完全基于 [Zap 官方最佳实践](https://betterstack.com/community/guides/logging/go/zap/) 设计，使用 `zap.NewProduction()` 和 `zap.NewDevelopment()` 预设，提供高性能、结构化的日志记录。
|
||||
|
||||
## ✨ 核心特性
|
||||
|
||||
### 1. **基于 Zap 官方预设**
|
||||
- 使用 `zap.NewProduction()` 生产环境预设
|
||||
- 使用 `zap.NewDevelopment()` 开发环境预设
|
||||
- 自动添加调用者信息、堆栈跟踪等
|
||||
|
||||
### 2. **全局日志器支持**
|
||||
- 支持 `zap.ReplaceGlobals()` 全局替换
|
||||
- 提供 `logger.L()` 和 `logger.GetGlobalLogger()` 访问
|
||||
- 符合 Zap 官方推荐的使用方式
|
||||
|
||||
### 3. **强类型字段支持**
|
||||
- 使用 `zap.String()`, `zap.Int()`, `zap.Error()` 等强类型字段
|
||||
- 避免运行时类型错误
|
||||
- 提供最佳性能
|
||||
|
||||
### 4. **上下文日志记录**
|
||||
- 自动从上下文提取 `request_id`, `user_id`, `trace_id`
|
||||
- 支持 `WithContext()` 方法
|
||||
- 便于分布式系统追踪
|
||||
|
||||
## 🏗️ 架构设计
|
||||
|
||||
### 核心接口
|
||||
|
||||
```go
|
||||
type Logger interface {
|
||||
// 基础日志方法
|
||||
Debug(msg string, fields ...zapcore.Field)
|
||||
Info(msg string, fields ...zapcore.Field)
|
||||
Warn(msg string, fields ...zapcore.Field)
|
||||
Error(msg string, fields ...zapcore.Field)
|
||||
Fatal(msg string, fields ...zapcore.Field)
|
||||
Panic(msg string, fields ...zapcore.Field)
|
||||
|
||||
// 结构化日志方法
|
||||
With(fields ...zapcore.Field) Logger
|
||||
WithContext(ctx context.Context) Logger
|
||||
Named(name string) Logger
|
||||
|
||||
// 同步和清理
|
||||
Sync() error
|
||||
Core() zapcore.Core
|
||||
|
||||
// 获取原生 Zap Logger
|
||||
GetZapLogger() *zap.Logger
|
||||
}
|
||||
```
|
||||
|
||||
### 实现类型
|
||||
|
||||
1. **ZapLogger**: 标准日志器，基于 Zap 官方预设
|
||||
2. **LevelLogger**: 级别分文件日志器，支持按级别分离
|
||||
3. **全局日志器**: 通过 `zap.ReplaceGlobals()` 提供全局访问
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 1. 基础使用
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"go.uber.org/zap"
|
||||
"tyapi-server/internal/shared/logger"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 初始化全局日志器
|
||||
config := logger.Config{
|
||||
Development: true,
|
||||
Output: "stdout",
|
||||
Format: "console",
|
||||
}
|
||||
|
||||
if err := logger.InitGlobalLogger(config); err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// 使用全局日志器
|
||||
logger.L().Info("应用启动成功")
|
||||
|
||||
// 或者获取全局日志器
|
||||
globalLogger := logger.GetGlobalLogger()
|
||||
globalLogger.Info("使用全局日志器")
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 依赖注入使用
|
||||
|
||||
```go
|
||||
type ProductService struct {
|
||||
logger logger.Logger
|
||||
}
|
||||
|
||||
func NewProductService(logger logger.Logger) *ProductService {
|
||||
return &ProductService{logger: logger}
|
||||
}
|
||||
|
||||
func (s *ProductService) CreateProduct(ctx context.Context, product *Product) error {
|
||||
// 记录操作日志
|
||||
s.logger.Info("创建产品",
|
||||
zap.String("product_id", product.ID),
|
||||
zap.String("product_name", product.Name),
|
||||
zap.String("user_id", product.CreatedBy),
|
||||
)
|
||||
|
||||
// 业务逻辑...
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 上下文日志记录
|
||||
|
||||
```go
|
||||
func (s *ProductService) GetProduct(ctx context.Context, id string) (*Product, error) {
|
||||
// 自动从上下文提取字段
|
||||
logger := s.logger.WithContext(ctx)
|
||||
|
||||
logger.Info("获取产品信息",
|
||||
zap.String("product_id", id),
|
||||
zap.String("operation", "get_product"),
|
||||
)
|
||||
|
||||
// 业务逻辑...
|
||||
return product, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 结构化字段
|
||||
|
||||
```go
|
||||
// 使用强类型字段
|
||||
s.logger.Info("用户登录",
|
||||
zap.String("username", "john_doe"),
|
||||
zap.Int("user_id", 12345),
|
||||
zap.String("ip_address", "192.168.1.100"),
|
||||
zap.String("user_agent", r.UserAgent()),
|
||||
zap.Time("login_time", time.Now()),
|
||||
)
|
||||
|
||||
// 记录错误
|
||||
if err != nil {
|
||||
s.logger.Error("数据库操作失败",
|
||||
zap.Error(err),
|
||||
zap.String("operation", "create_user"),
|
||||
zap.String("table", "users"),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 级别分文件日志
|
||||
|
||||
```go
|
||||
// 配置启用级别分文件
|
||||
config := logger.Config{
|
||||
EnableLevelSeparation: true,
|
||||
Output: "file",
|
||||
LogDir: "logs",
|
||||
UseDaily: true,
|
||||
LevelConfigs: map[string]interface{}{
|
||||
"debug": map[string]interface{}{
|
||||
"max_size": 50,
|
||||
"max_backups": 3,
|
||||
"max_age": 7,
|
||||
},
|
||||
"error": map[string]interface{}{
|
||||
"max_size": 200,
|
||||
"max_backups": 10,
|
||||
"max_age": 90,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// 创建级别分文件日志器
|
||||
levelLogger, err := logger.NewLevelLogger(logger.LevelLoggerConfig{
|
||||
BaseConfig: config,
|
||||
EnableLevelSeparation: true,
|
||||
LevelConfigs: convertLevelConfigs(config.LevelConfigs),
|
||||
})
|
||||
```
|
||||
|
||||
## 📁 日志文件结构
|
||||
|
||||
### 按级别分文件
|
||||
|
||||
```
|
||||
logs/
|
||||
├── 2024-01-01/
|
||||
│ ├── debug.log # 调试日志
|
||||
│ ├── info.log # 信息日志
|
||||
│ ├── warn.log # 警告日志
|
||||
│ ├── error.log # 错误日志
|
||||
│ ├── fatal.log # 致命错误日志
|
||||
│ └── panic.log # 恐慌错误日志
|
||||
└── app.log # 主日志文件
|
||||
```
|
||||
|
||||
### 按日期分包
|
||||
|
||||
```
|
||||
logs/
|
||||
├── 2024-01-01/
|
||||
│ ├── app.log
|
||||
│ └── error.log
|
||||
├── 2024-01-02/
|
||||
│ ├── app.log
|
||||
│ └── error.log
|
||||
└── app.log # 当前日期
|
||||
```
|
||||
|
||||
## ⚙️ 配置选项
|
||||
|
||||
### 基础配置
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
# 环境配置
|
||||
development: true # 是否为开发环境
|
||||
|
||||
# 输出配置
|
||||
output: "file" # 输出方式: stdout, stderr, file
|
||||
format: "json" # 输出格式: json, console
|
||||
log_dir: "logs" # 日志目录
|
||||
|
||||
# 文件配置
|
||||
max_size: 100 # 单个文件最大大小(MB)
|
||||
max_backups: 5 # 最大备份文件数
|
||||
max_age: 30 # 最大保留天数
|
||||
compress: true # 是否压缩
|
||||
|
||||
# 高级功能
|
||||
use_daily: true # 是否按日分包
|
||||
enable_level_separation: true # 是否启用按级别分文件
|
||||
use_color: false # 是否使用彩色输出
|
||||
```
|
||||
|
||||
### 级别配置
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
level_configs:
|
||||
debug:
|
||||
max_size: 50 # 50MB
|
||||
max_backups: 3 # 3个备份
|
||||
max_age: 7 # 7天
|
||||
compress: true
|
||||
info:
|
||||
max_size: 100 # 100MB
|
||||
max_backups: 5 # 5个备份
|
||||
max_age: 30 # 30天
|
||||
compress: true
|
||||
error:
|
||||
max_size: 200 # 200MB
|
||||
max_backups: 10 # 10个备份
|
||||
max_age: 90 # 90天
|
||||
compress: true
|
||||
```
|
||||
|
||||
## 🔧 最佳实践
|
||||
|
||||
### 1. **使用强类型字段**
|
||||
|
||||
```go
|
||||
// ✅ 推荐：使用强类型字段
|
||||
logger.Info("用户操作",
|
||||
zap.String("user_id", userID),
|
||||
zap.String("action", "login"),
|
||||
zap.Time("timestamp", time.Now()),
|
||||
)
|
||||
|
||||
// ❌ 避免：使用 Any 字段
|
||||
logger.Info("用户操作",
|
||||
zap.Any("user_id", userID),
|
||||
zap.Any("action", "login"),
|
||||
zap.Any("timestamp", time.Now()),
|
||||
)
|
||||
```
|
||||
|
||||
### 2. **合理使用日志级别**
|
||||
|
||||
```go
|
||||
// Debug: 详细的调试信息
|
||||
logger.Debug("SQL查询", zap.String("query", sql))
|
||||
|
||||
// Info: 重要的业务事件
|
||||
logger.Info("用户注册成功", zap.String("user_id", userID))
|
||||
|
||||
// Warn: 警告信息，不影响功能
|
||||
logger.Warn("数据库连接池使用率过高", zap.Int("usage", 85))
|
||||
|
||||
// Error: 错误信息，功能受影响
|
||||
logger.Error("数据库连接失败", zap.Error(err))
|
||||
|
||||
// Fatal: 致命错误，应用无法继续
|
||||
logger.Fatal("配置文件加载失败", zap.Error(err))
|
||||
```
|
||||
|
||||
### 3. **上下文信息提取**
|
||||
|
||||
```go
|
||||
// 在中间件中设置上下文
|
||||
func LoggingMiddleware(logger logger.Logger) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
// 生成请求ID
|
||||
requestID := uuid.New().String()
|
||||
|
||||
// 设置上下文
|
||||
ctx := context.WithValue(c.Request.Context(), "request_id", requestID)
|
||||
ctx = context.WithValue(ctx, "user_id", getUserID(c))
|
||||
ctx = context.WithValue(ctx, "trace_id", getTraceID(c))
|
||||
|
||||
c.Request = c.Request.WithContext(ctx)
|
||||
|
||||
// 记录请求日志
|
||||
logger.WithContext(ctx).Info("收到请求",
|
||||
zap.String("method", c.Request.Method),
|
||||
zap.String("path", c.Request.URL.Path),
|
||||
zap.String("client_ip", c.ClientIP()),
|
||||
)
|
||||
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. **性能优化**
|
||||
|
||||
```go
|
||||
// ✅ 推荐：延迟计算
|
||||
if logger.Core().Enabled(zapcore.DebugLevel) {
|
||||
logger.Debug("调试信息", zap.String("data", expensiveOperation()))
|
||||
}
|
||||
|
||||
// ❌ 避免：总是计算
|
||||
logger.Debug("调试信息", zap.String("data", expensiveOperation()))
|
||||
```
|
||||
|
||||
## 🚨 错误处理
|
||||
|
||||
### 1. **Panic 恢复**
|
||||
|
||||
```go
|
||||
// 使用 panic 恢复中间件
|
||||
func PanicRecoveryMiddleware(logger *zap.Logger) gin.HandlerFunc {
|
||||
return gin.RecoveryWithWriter(&panicLogger{logger: logger})
|
||||
}
|
||||
|
||||
type panicLogger struct {
|
||||
logger *zap.Logger
|
||||
}
|
||||
|
||||
func (pl *panicLogger) Write(p []byte) (n int, err error) {
|
||||
pl.logger.Error("系统发生严重错误",
|
||||
zap.String("error_type", "panic"),
|
||||
zap.String("stack_trace", string(p)),
|
||||
zap.String("timestamp", time.Now().Format("2006-01-02 15:04:05")),
|
||||
)
|
||||
return len(p), nil
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **错误日志记录**
|
||||
|
||||
```go
|
||||
// 记录错误详情
|
||||
if err != nil {
|
||||
logger.Error("操作失败",
|
||||
zap.Error(err),
|
||||
zap.String("operation", "create_user"),
|
||||
zap.String("user_id", userID),
|
||||
zap.String("stack_trace", string(debug.Stack())),
|
||||
)
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 性能基准
|
||||
|
||||
基于 [Zap 官方基准测试](https://betterstack.com/community/guides/logging/go/zap/)：
|
||||
|
||||
| 包 | 时间 | 相对于 Zap | 内存分配 |
|
||||
|----|------|------------|----------|
|
||||
| zap | 193 ns/op | +0% | 0 allocs/op |
|
||||
| zap (sugared) | 227 ns/op | +18% | 1 allocs/op |
|
||||
| zerolog | 81 ns/op | -58% | 0 allocs/op |
|
||||
| slog | 322 ns/op | +67% | 0 allocs/op |
|
||||
|
||||
## 🔍 调试和故障排除
|
||||
|
||||
### 1. **检查日志级别**
|
||||
|
||||
```go
|
||||
// 检查日志级别是否启用
|
||||
if logger.Core().Enabled(zapcore.DebugLevel) {
|
||||
logger.Debug("调试信息")
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **同步日志**
|
||||
|
||||
```go
|
||||
// 确保日志写入完成
|
||||
defer logger.Sync()
|
||||
|
||||
// 或者在应用关闭时
|
||||
func cleanup() {
|
||||
logger.Sync()
|
||||
}
|
||||
```
|
||||
|
||||
### 3. **验证配置**
|
||||
|
||||
```go
|
||||
// 验证日志器配置
|
||||
config := logger.Config{
|
||||
Development: true,
|
||||
Output: "stdout",
|
||||
Format: "console",
|
||||
}
|
||||
|
||||
logger, err := logger.NewLogger(config)
|
||||
if err != nil {
|
||||
log.Fatalf("创建日志器失败: %v", err)
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 总结
|
||||
|
||||
本日志系统完全基于 Zap 官方最佳实践设计，具有以下优势：
|
||||
|
||||
1. **高性能**: 基于 Zap 的高性能实现
|
||||
2. **官方推荐**: 使用 `zap.NewProduction()` 和 `zap.NewDevelopment()` 预设
|
||||
3. **强类型**: 支持强类型字段，避免运行时错误
|
||||
4. **结构化**: 支持结构化日志记录
|
||||
5. **上下文**: 自动提取上下文信息
|
||||
6. **灵活配置**: 支持文件输出、级别分离、按日分包等
|
||||
7. **全局访问**: 支持全局日志器访问
|
||||
|
||||
通过合理使用，您将获得高性能、结构化的日志系统，满足生产环境的各种需求！
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
- [Zap 官方文档](https://pkg.go.dev/go.uber.org/zap)
|
||||
- [Zap 最佳实践指南](https://betterstack.com/community/guides/logging/go/zap/)
|
||||
- [Zap GitHub 仓库](https://github.com/uber-go/zap)
|
||||
340
docs/新日志系统使用指南.md
Normal file
340
docs/新日志系统使用指南.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 🚀 新日志系统使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
本项目已重新设计日志系统，完全基于 **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 官方文档实现，确保最佳实践
|
||||
|
||||
使用新的日志系统，您将获得更好的性能、更清晰的日志结构和更强大的功能！
|
||||
321
docs/日志系统配置示例.md
Normal file
321
docs/日志系统配置示例.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 📝 日志系统配置示例
|
||||
|
||||
## 概述
|
||||
|
||||
新的日志系统完全基于配置文件，所有配置都在 `config.yaml` 中设置，容器代码保持简洁。
|
||||
|
||||
## 🎯 完整配置示例
|
||||
|
||||
```yaml
|
||||
# 🚀 日志系统配置 - 基于 Zap 官方推荐
|
||||
logger:
|
||||
# 基础配置
|
||||
level: "info" # 日志级别: debug, info, warn, error, fatal, panic
|
||||
format: "json" # 输出格式: json, console
|
||||
output: "file" # 输出方式: stdout, stderr, file
|
||||
log_dir: "logs" # 日志目录
|
||||
use_daily: true # 是否按日分包
|
||||
use_color: false # 是否使用彩色输出（仅console格式有效）
|
||||
|
||||
# 文件配置
|
||||
max_size: 100 # 单个文件最大大小(MB)
|
||||
max_backups: 5 # 最大备份文件数
|
||||
max_age: 30 # 最大保留天数
|
||||
compress: true # 是否压缩
|
||||
|
||||
# 高级功能
|
||||
enable_level_separation: true # 是否启用按级别分文件
|
||||
enable_request_logging: true # 是否启用请求日志
|
||||
enable_performance_log: true # 是否启用性能日志
|
||||
|
||||
# 各级别配置（按级别分文件时使用）
|
||||
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
|
||||
warn:
|
||||
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
|
||||
fatal:
|
||||
max_size: 100 # 100MB
|
||||
max_backups: 10
|
||||
max_age: 365 # 1年
|
||||
compress: true
|
||||
panic:
|
||||
max_size: 100 # 100MB
|
||||
max_backups: 10
|
||||
max_age: 365 # 1年
|
||||
compress: true
|
||||
```
|
||||
|
||||
## 🔧 环境特定配置
|
||||
|
||||
### 开发环境配置
|
||||
|
||||
```yaml
|
||||
# 开发环境 - 详细日志，控制台输出
|
||||
logger:
|
||||
level: "debug"
|
||||
format: "console"
|
||||
output: "stdout"
|
||||
use_daily: false
|
||||
use_color: true
|
||||
enable_level_separation: false
|
||||
development: true
|
||||
```
|
||||
|
||||
### 生产环境配置
|
||||
|
||||
```yaml
|
||||
# 生产环境 - 精简日志，文件输出
|
||||
logger:
|
||||
level: "warn"
|
||||
format: "json"
|
||||
output: "file"
|
||||
log_dir: "/app/logs"
|
||||
use_daily: true
|
||||
use_color: false
|
||||
enable_level_separation: true
|
||||
development: false
|
||||
|
||||
# 生产环境文件配置
|
||||
max_size: 200
|
||||
max_backups: 10
|
||||
max_age: 90
|
||||
compress: true
|
||||
|
||||
# 生产环境级别配置
|
||||
level_configs:
|
||||
warn:
|
||||
max_size: 200
|
||||
max_backups: 10
|
||||
max_age: 90
|
||||
compress: true
|
||||
error:
|
||||
max_size: 500
|
||||
max_backups: 20
|
||||
max_age: 180
|
||||
compress: true
|
||||
fatal:
|
||||
max_size: 100
|
||||
max_backups: 10
|
||||
max_age: 365
|
||||
compress: true
|
||||
```
|
||||
|
||||
## 📊 配置字段说明
|
||||
|
||||
### 基础配置字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `level` | string | 日志级别 | "info" |
|
||||
| `format` | string | 输出格式 | "json" |
|
||||
| `output` | string | 输出方式 | "stdout" |
|
||||
| `log_dir` | string | 日志目录 | "logs" |
|
||||
| `use_daily` | bool | 是否按日分包 | false |
|
||||
| `use_color` | bool | 是否使用彩色输出 | false |
|
||||
|
||||
### 文件配置字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `max_size` | int | 单个文件最大大小(MB) | 100 |
|
||||
| `max_backups` | int | 最大备份文件数 | 5 |
|
||||
| `max_age` | int | 最大保留天数 | 30 |
|
||||
| `compress` | bool | 是否压缩 | true |
|
||||
|
||||
### 高级功能字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `enable_level_separation` | bool | 是否启用按级别分文件 | false |
|
||||
| `enable_request_logging` | bool | 是否启用请求日志 | false |
|
||||
| `enable_performance_log` | bool | 是否启用性能日志 | false |
|
||||
|
||||
### 级别配置字段
|
||||
|
||||
| 字段 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `max_size` | int | 单个文件最大大小(MB) | 无 |
|
||||
| `max_backups` | int | 最大备份文件数 | 无 |
|
||||
| `max_age` | int | 最大保留天数 | 无 |
|
||||
| `compress` | bool | 是否压缩 | 无 |
|
||||
|
||||
## 🚀 配置最佳实践
|
||||
|
||||
### 1. 按环境配置
|
||||
|
||||
```yaml
|
||||
# 开发环境
|
||||
logger:
|
||||
level: "debug"
|
||||
format: "console"
|
||||
output: "stdout"
|
||||
use_color: true
|
||||
enable_level_separation: false
|
||||
|
||||
# 测试环境
|
||||
logger:
|
||||
level: "info"
|
||||
format: "json"
|
||||
output: "file"
|
||||
use_daily: true
|
||||
enable_level_separation: true
|
||||
|
||||
# 生产环境
|
||||
logger:
|
||||
level: "warn"
|
||||
format: "json"
|
||||
output: "file"
|
||||
use_daily: true
|
||||
enable_level_separation: true
|
||||
max_size: 200
|
||||
max_backups: 10
|
||||
max_age: 90
|
||||
```
|
||||
|
||||
### 2. 按级别配置
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
enable_level_separation: true
|
||||
level_configs:
|
||||
# 调试日志 - 小文件，短期保留
|
||||
debug:
|
||||
max_size: 50
|
||||
max_backups: 3
|
||||
max_age: 7
|
||||
compress: true
|
||||
|
||||
# 信息日志 - 中等文件，中期保留
|
||||
info:
|
||||
max_size: 100
|
||||
max_backups: 5
|
||||
max_age: 30
|
||||
compress: true
|
||||
|
||||
# 警告日志 - 中等文件，中期保留
|
||||
warn:
|
||||
max_size: 100
|
||||
max_backups: 5
|
||||
max_age: 30
|
||||
compress: true
|
||||
|
||||
# 错误日志 - 大文件，长期保留
|
||||
error:
|
||||
max_size: 200
|
||||
max_backups: 10
|
||||
max_age: 90
|
||||
compress: true
|
||||
|
||||
# 致命错误 - 中等文件，长期保留
|
||||
fatal:
|
||||
max_size: 100
|
||||
max_backups: 10
|
||||
max_age: 365
|
||||
compress: true
|
||||
```
|
||||
|
||||
### 3. 性能优化配置
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
# 生产环境性能优化
|
||||
level: "warn" # 只记录警告及以上级别
|
||||
format: "json" # JSON格式便于日志分析
|
||||
output: "file" # 文件输出避免控制台性能影响
|
||||
use_daily: true # 按日分包便于管理
|
||||
enable_level_separation: true # 按级别分文件便于分析
|
||||
|
||||
# 文件轮转优化
|
||||
max_size: 200 # 较大的文件大小减少轮转频率
|
||||
max_backups: 10 # 适中的备份数量
|
||||
max_age: 90 # 90天保留期平衡存储和分析需求
|
||||
compress: true # 启用压缩节省存储空间
|
||||
```
|
||||
|
||||
## 🔍 配置验证
|
||||
|
||||
### 1. 必需字段
|
||||
|
||||
以下字段是必需的，如果未设置将使用默认值：
|
||||
|
||||
- `level`: 日志级别
|
||||
- `format`: 输出格式
|
||||
- `output`: 输出方式
|
||||
|
||||
### 2. 可选字段
|
||||
|
||||
以下字段是可选的，如果未设置将使用系统默认值：
|
||||
|
||||
- `log_dir`: 日志目录
|
||||
- `use_daily`: 是否按日分包
|
||||
- `use_color`: 是否使用彩色输出
|
||||
- `max_size`: 文件大小限制
|
||||
- `max_backups`: 备份文件数量
|
||||
- `max_age`: 文件保留天数
|
||||
- `compress`: 是否压缩
|
||||
|
||||
### 3. 条件字段
|
||||
|
||||
以下字段在特定条件下是必需的：
|
||||
|
||||
- 当 `output: "file"` 时，建议设置 `log_dir`
|
||||
- 当 `enable_level_separation: true` 时，建议设置 `level_configs`
|
||||
- 当 `format: "console"` 时，`use_color` 才有效
|
||||
|
||||
## 📝 配置迁移指南
|
||||
|
||||
### 从旧配置迁移
|
||||
|
||||
如果您之前使用的是旧版本的日志配置，可以按照以下方式迁移：
|
||||
|
||||
#### 旧配置
|
||||
```yaml
|
||||
# 旧版本配置
|
||||
logging:
|
||||
level: "info"
|
||||
file: "logs/app.log"
|
||||
max_size: 100
|
||||
max_backups: 3
|
||||
```
|
||||
|
||||
#### 新配置
|
||||
```yaml
|
||||
# 新版本配置
|
||||
logger:
|
||||
level: "info"
|
||||
output: "file"
|
||||
log_dir: "logs"
|
||||
max_size: 100
|
||||
max_backups: 3
|
||||
format: "json"
|
||||
use_daily: false
|
||||
```
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
新的日志系统配置完全基于 `config.yaml` 文件，具有以下特点：
|
||||
|
||||
1. **配置集中**: 所有日志配置都在一个地方管理
|
||||
2. **环境友好**: 支持不同环境的配置
|
||||
3. **灵活性强**: 支持按级别分文件、按日分包等高级功能
|
||||
4. **性能优化**: 基于 Zap 官方最佳实践
|
||||
5. **易于维护**: 配置结构清晰，易于理解和修改
|
||||
|
||||
通过合理的配置，您可以获得高性能、结构化的日志系统，满足开发、测试和生产环境的各种需求！
|
||||
383
docs/西部数据日志系统使用指南.md
Normal file
383
docs/西部数据日志系统使用指南.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# 🚀 西部数据日志系统使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
西部数据服务现在集成了完整的日志记录系统，支持请求、响应、错误和性能四种类型的日志记录，每种类型都有独立的日志文件。
|
||||
|
||||
## 📝 日志记录范围
|
||||
|
||||
### ✅ **会记录日志的操作**
|
||||
- `CallAPI()` - 调用西部数据API
|
||||
- `G05HZ01CallAPI()` - 调用G05HZ01 API
|
||||
|
||||
### ❌ **不会记录日志的操作**
|
||||
- `Encrypt()` - 内部加密方法
|
||||
- `Md5Encrypt()` - 内部MD5加密方法
|
||||
|
||||
**说明**: 加密解密是内部工具方法，调用频率高且不涉及外部API，因此不记录日志以提高性能。日志系统专注于记录外部API调用的完整生命周期。
|
||||
|
||||
## ✨ 核心特性
|
||||
|
||||
### 1. **四种日志类型**
|
||||
- **请求日志**: 记录所有API请求的详细信息
|
||||
- **响应日志**: 记录所有API响应的详细信息
|
||||
- **错误日志**: 记录所有错误和异常情况
|
||||
- **性能日志**: 记录请求耗时和性能指标
|
||||
|
||||
### 2. **日志文件分离**
|
||||
```
|
||||
logs/
|
||||
├── westdex/
|
||||
│ ├── 2024-01-01/
|
||||
│ │ ├── request.log # 请求日志
|
||||
│ │ ├── response.log # 响应日志
|
||||
│ │ ├── error.log # 错误日志
|
||||
│ │ └── performance.log # 性能日志
|
||||
│ └── 2024-01-02/
|
||||
│ ├── request.log
|
||||
│ ├── response.log
|
||||
│ ├── error.log
|
||||
│ └── performance.log
|
||||
```
|
||||
|
||||
### 3. **请求追踪**
|
||||
- 每个请求都有唯一的请求ID
|
||||
- 请求和响应日志通过请求ID关联
|
||||
- 支持完整的请求链路追踪
|
||||
|
||||
### 4. **性能监控**
|
||||
- 记录每个API调用的耗时
|
||||
- 区分成功和失败的请求
|
||||
- 提供性能分析数据
|
||||
|
||||
## 🏗️ 配置说明
|
||||
|
||||
### 配置文件设置
|
||||
|
||||
在 `config.yaml` 中添加西部数据日志配置：
|
||||
|
||||
```yaml
|
||||
westdex:
|
||||
url: "https://apimaster.westdex.com.cn/api/invoke"
|
||||
key: "your-key"
|
||||
secret_id: "your-secret-id"
|
||||
secret_second_id: "your-secret-second-id"
|
||||
|
||||
# 西部数据日志配置
|
||||
logging:
|
||||
enabled: true # 启用日志记录
|
||||
log_dir: "logs/westdex" # 日志目录
|
||||
use_daily: true # 按日分包
|
||||
enable_level_separation: true # 启用级别分离
|
||||
|
||||
# 各级别配置
|
||||
level_configs:
|
||||
request:
|
||||
max_size: 100 # 100MB
|
||||
max_backups: 5 # 5个备份
|
||||
max_age: 30 # 30天
|
||||
compress: true # 启用压缩
|
||||
response:
|
||||
max_size: 100
|
||||
max_backups: 5
|
||||
max_age: 30
|
||||
compress: true
|
||||
error:
|
||||
max_size: 200 # 错误日志文件更大
|
||||
max_backups: 10 # 更多备份
|
||||
max_age: 90 # 保留更久
|
||||
compress: true
|
||||
performance:
|
||||
max_size: 100
|
||||
max_backups: 5
|
||||
max_age: 30
|
||||
compress: true
|
||||
```
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 1. 使用配置创建服务
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"tyapi-server/internal/config"
|
||||
"tyapi-server/internal/infrastructure/external/westdex"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 加载配置
|
||||
cfg := &config.Config{
|
||||
// ... 配置内容
|
||||
}
|
||||
|
||||
// 使用配置创建西部数据服务
|
||||
service, err := westdex.NewWestDexServiceWithConfig(cfg)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// 使用服务
|
||||
resp, err := service.CallAPI("G05HZ01", map[string]interface{}{
|
||||
"param1": "value1",
|
||||
"param2": "value2",
|
||||
})
|
||||
|
||||
if err != nil {
|
||||
// 错误会自动记录到错误日志
|
||||
log.Printf("API调用失败: %v", err)
|
||||
return
|
||||
}
|
||||
|
||||
// 成功响应会自动记录到响应日志
|
||||
log.Printf("API调用成功: %s", string(resp))
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用自定义日志配置
|
||||
|
||||
```go
|
||||
// 创建自定义日志配置
|
||||
loggingConfig := westdex.WestDexLoggingConfig{
|
||||
Enabled: true,
|
||||
LogDir: "logs/custom_westdex",
|
||||
UseDaily: true,
|
||||
EnableLevelSeparation: true,
|
||||
LevelConfigs: map[string]westdex.WestDexLevelFileConfig{
|
||||
"request": {
|
||||
MaxSize: 50,
|
||||
MaxBackups: 3,
|
||||
MaxAge: 7,
|
||||
Compress: true,
|
||||
},
|
||||
"error": {
|
||||
MaxSize: 100,
|
||||
MaxBackups: 5,
|
||||
MaxAge: 30,
|
||||
Compress: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// 使用自定义配置创建服务
|
||||
service, err := westdex.NewWestDexServiceWithLogging(
|
||||
"https://api.example.com",
|
||||
"your-key",
|
||||
"your-secret-id",
|
||||
"your-secret-second-id",
|
||||
loggingConfig,
|
||||
)
|
||||
```
|
||||
|
||||
## 📊 日志示例
|
||||
|
||||
### 请求日志示例
|
||||
|
||||
```json
|
||||
{
|
||||
"level": "info",
|
||||
"msg": "西部数据API请求",
|
||||
"request_id": "westdex_a1b2c3d4",
|
||||
"api_code": "G05HZ01",
|
||||
"url": "https://apimaster.westdex.com.cn/api/invoke/449159/G05HZ01?timestamp=1704096000000",
|
||||
"request_data": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
},
|
||||
"timestamp": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应日志示例
|
||||
|
||||
```json
|
||||
{
|
||||
"level": "info",
|
||||
"msg": "西部数据API响应",
|
||||
"request_id": "westdex_a1b2c3d4",
|
||||
"api_code": "G05HZ01",
|
||||
"status_code": 200,
|
||||
"response_data": "{\"code\":\"0000\",\"data\":\"...\",\"message\":\"success\"}",
|
||||
"duration": "150ms",
|
||||
"timestamp": "2024-01-01T12:00:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误日志示例
|
||||
|
||||
```json
|
||||
{
|
||||
"level": "error",
|
||||
"msg": "西部数据API错误",
|
||||
"request_id": "westdex_a1b2c3d4",
|
||||
"api_code": "G05HZ01",
|
||||
"error": "数据源异常: 查询失败",
|
||||
"request_data": {
|
||||
"param1": "value1",
|
||||
"param2": "value2"
|
||||
},
|
||||
"timestamp": "2024-01-01T12:00:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 性能日志示例
|
||||
|
||||
```json
|
||||
{
|
||||
"level": "info",
|
||||
"msg": "西部数据API性能",
|
||||
"request_id": "westdex_a1b2c3d4",
|
||||
"api_code": "G05HZ01",
|
||||
"duration": "150ms",
|
||||
"success": true,
|
||||
"timestamp": "2024-01-01T12:00:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔍 日志字段说明
|
||||
|
||||
### 通用字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `request_id` | string | 请求唯一标识符 |
|
||||
| `api_code` | string | API代码 |
|
||||
| `timestamp` | string | 时间戳（ISO8601格式） |
|
||||
|
||||
### 请求日志字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `url` | string | 完整的请求URL |
|
||||
| `request_data` | object | 请求数据 |
|
||||
|
||||
### 响应日志字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `status_code` | int | HTTP状态码 |
|
||||
| `response_data` | string | 响应数据（JSON字符串） |
|
||||
| `duration` | duration | 请求耗时 |
|
||||
|
||||
### 错误日志字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `error` | error | 错误信息 |
|
||||
| `request_data` | object | 原始请求数据 |
|
||||
|
||||
### 性能日志字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `duration` | duration | 请求耗时 |
|
||||
| `success` | bool | 是否成功 |
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 1. **日志配置优化**
|
||||
|
||||
```yaml
|
||||
# 生产环境配置
|
||||
logging:
|
||||
enabled: true
|
||||
log_dir: "/var/log/westdex"
|
||||
use_daily: true
|
||||
enable_level_separation: true
|
||||
level_configs:
|
||||
request:
|
||||
max_size: 200 # 更大的文件大小
|
||||
max_backups: 10 # 更多备份
|
||||
max_age: 90 # 保留更久
|
||||
error:
|
||||
max_size: 500 # 错误日志文件更大
|
||||
max_backups: 20 # 更多备份
|
||||
max_age: 180 # 保留更久
|
||||
```
|
||||
|
||||
### 2. **日志分析**
|
||||
|
||||
```bash
|
||||
# 查看请求日志
|
||||
tail -f logs/westdex/2024-01-01/request.log
|
||||
|
||||
# 查看错误日志
|
||||
tail -f logs/westdex/2024-01-01/error.log
|
||||
|
||||
# 查看性能日志
|
||||
tail -f logs/westdex/2024-01-01/performance.log
|
||||
|
||||
# 统计API调用次数
|
||||
grep -c "G05HZ01" logs/westdex/2024-01-01/request.log
|
||||
|
||||
# 统计错误率
|
||||
grep -c "error" logs/westdex/2024-01-01/error.log
|
||||
```
|
||||
|
||||
### 3. **性能监控**
|
||||
|
||||
```bash
|
||||
# 查看平均响应时间
|
||||
grep "duration" logs/westdex/2024-01-01/performance.log | \
|
||||
awk -F'"duration":"' '{print $2}' | \
|
||||
awk -F'"' '{print $1}' | \
|
||||
awk -F'ms' '{sum+=$1; count++} END {print "平均响应时间: " sum/count "ms"}'
|
||||
|
||||
# 查看成功率
|
||||
total=$(grep -c "success" logs/westdex/2024-01-01/performance.log)
|
||||
success=$(grep -c '"success":true' logs/westdex/2024-01-01/performance.log)
|
||||
echo "成功率: $((success * 100 / total))%"
|
||||
```
|
||||
|
||||
## 🚨 注意事项
|
||||
|
||||
### 1. **日志文件管理**
|
||||
- 定期清理旧日志文件
|
||||
- 监控磁盘空间使用
|
||||
- 配置合适的日志轮转策略
|
||||
|
||||
### 2. **敏感信息处理**
|
||||
- 日志中可能包含敏感数据
|
||||
- 确保日志文件访问权限
|
||||
- 考虑日志脱敏需求
|
||||
|
||||
### 3. **性能影响**
|
||||
- 日志记录会增加少量性能开销
|
||||
- 异步日志记录可减少性能影响
|
||||
- 合理配置日志级别
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
### 1. **日志文件未创建**
|
||||
- 检查日志目录权限
|
||||
- 确认日志配置已启用
|
||||
- 验证文件路径配置
|
||||
|
||||
### 2. **日志记录不完整**
|
||||
- 检查日志器是否正确初始化
|
||||
- 确认请求ID生成逻辑
|
||||
- 验证错误处理流程
|
||||
|
||||
### 3. **性能问题**
|
||||
- 检查日志文件大小和数量
|
||||
- 确认日志轮转配置
|
||||
- 监控磁盘I/O性能
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
西部数据日志系统提供了完整的API调用追踪能力：
|
||||
|
||||
1. **请求追踪**: 通过唯一请求ID关联请求和响应
|
||||
2. **错误监控**: 记录所有错误和异常情况
|
||||
3. **性能分析**: 提供详细的性能指标
|
||||
4. **文件管理**: 支持按日期分包和级别分离
|
||||
5. **配置灵活**: 支持自定义日志配置
|
||||
|
||||
通过合理使用这个日志系统，您可以：
|
||||
- 快速定位API调用问题
|
||||
- 监控系统性能和稳定性
|
||||
- 分析API使用模式和趋势
|
||||
- 提高问题排查效率
|
||||
|
||||
现在您的西部数据服务已经具备了完整的日志记录能力！🚀
|
||||
Reference in New Issue
Block a user