203 lines
4.1 KiB
Markdown
203 lines
4.1 KiB
Markdown
# Logger 日志工具包
|
||
|
||
## 概述
|
||
|
||
统一的日志工具包，基于 [zap](https://github.com/uber-go/zap) 日志框架。所有微服务共享此包，但每个服务独立初始化自己的logger实例。
|
||
|
||
## 特性
|
||
|
||
- ✅ 每个服务独立的logger实例
|
||
- ✅ 统一的日志格式和配置方式
|
||
- ✅ 支持开发和生产环境不同配置
|
||
- ✅ 自动添加服务名标识
|
||
- ✅ 结构化日志（JSON格式，生产环境）
|
||
- ✅ 彩色控制台输出（开发环境）
|
||
- ✅ 支持日志文件输出（生产环境）
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
cd /Users/haihuizhu/infinite_matrix/top-fans/backend
|
||
go get go.uber.org/zap
|
||
go mod tidy
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 在服务中初始化
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"os"
|
||
"github.com/topfans/backend/pkg/logger"
|
||
)
|
||
|
||
func main() {
|
||
// 初始化日志（必须在最前面）
|
||
env := os.Getenv("ENV")
|
||
if env == "" {
|
||
env = "development"
|
||
}
|
||
|
||
if err := logger.Init(logger.Config{
|
||
ServiceName: "user-service", // 服务名称
|
||
Environment: env, // development 或 production
|
||
LogLevel: os.Getenv("LOG_LEVEL"), // debug, info, warn, error
|
||
LogPath: "", // 可选，默认为 "logs"
|
||
}); err != nil {
|
||
panic(fmt.Sprintf("Failed to initialize logger: %v", err))
|
||
}
|
||
defer logger.Sync() // 程序退出前刷新日志缓冲区
|
||
|
||
logger.Sugar.Info("Service started")
|
||
}
|
||
```
|
||
|
||
### 2. 使用Sugar API（简单易用）
|
||
|
||
```go
|
||
import "github.com/topfans/backend/pkg/logger"
|
||
|
||
// Info级别
|
||
logger.Sugar.Infof("User registered: mobile=%s, user_id=%d", mobile, userID)
|
||
|
||
// Error级别
|
||
logger.Sugar.Errorf("Failed to create user: %v", err)
|
||
|
||
// Debug级别
|
||
logger.Sugar.Debugf("Processing request: mobile=%s", mobile)
|
||
|
||
// Warn级别
|
||
logger.Sugar.Warnf("Token expired: user_id=%d", userID)
|
||
```
|
||
|
||
### 3. 使用结构化日志（推荐，性能更好）
|
||
|
||
```go
|
||
import (
|
||
"github.com/topfans/backend/pkg/logger"
|
||
"go.uber.org/zap"
|
||
)
|
||
|
||
// Info级别
|
||
logger.Logger.Info("User registered",
|
||
zap.String("mobile", mobile),
|
||
zap.Int64("user_id", userID),
|
||
zap.Int64("star_id", starID),
|
||
)
|
||
|
||
// Error级别
|
||
logger.Logger.Error("Failed to create user",
|
||
zap.String("mobile", mobile),
|
||
zap.Error(err),
|
||
)
|
||
|
||
// Debug级别
|
||
logger.Logger.Debug("Processing request",
|
||
zap.String("mobile", mobile),
|
||
)
|
||
```
|
||
|
||
## 环境变量配置
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
export ENV=development
|
||
export LOG_LEVEL=debug
|
||
```
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
export ENV=production
|
||
export LOG_LEVEL=info
|
||
export LOG_PATH=/var/log/user-service # 可选
|
||
```
|
||
|
||
## 日志格式
|
||
|
||
### 开发环境（控制台）
|
||
|
||
```
|
||
2024-01-01T10:00:00.000+0800 INFO service=user-service User registered {"mobile": "13800138000", "user_id": 123}
|
||
```
|
||
|
||
### 生产环境（JSON格式）
|
||
|
||
```json
|
||
{
|
||
"level": "info",
|
||
"ts": 1704067200.000,
|
||
"caller": "auth_service.go:45",
|
||
"msg": "User registered",
|
||
"service": "user-service",
|
||
"mobile": "13800138000",
|
||
"user_id": 123
|
||
}
|
||
```
|
||
|
||
## 日志文件
|
||
|
||
生产环境下，日志会同时输出到：
|
||
- `stdout` - 标准输出
|
||
- `logs/{service-name}.log` - 正常日志文件
|
||
- `logs/{service-name}-error.log` - 错误日志文件
|
||
|
||
日志目录会在初始化时自动创建。
|
||
|
||
## 最佳实践
|
||
|
||
1. **在main函数最开始初始化logger**
|
||
2. **使用结构化日志**（`Logger.Info`）而不是Sugar API（生产环境）
|
||
3. **不要记录敏感信息**（密码、完整Token等）
|
||
4. **记录关键操作**（注册、登录、Token刷新等）
|
||
5. **错误必须记录**，包含上下文信息
|
||
|
||
## API 文档
|
||
|
||
### Config
|
||
|
||
日志配置结构：
|
||
|
||
```go
|
||
type Config struct {
|
||
ServiceName string // 服务名称（必需）
|
||
Environment string // 环境：development 或 production
|
||
LogLevel string // 日志级别：debug, info, warn, error
|
||
LogPath string // 日志文件路径（可选）
|
||
}
|
||
```
|
||
|
||
### Init
|
||
|
||
初始化logger：
|
||
|
||
```go
|
||
func Init(config Config) error
|
||
```
|
||
|
||
### Sync
|
||
|
||
刷新日志缓冲区（程序退出前调用）：
|
||
|
||
```go
|
||
func Sync()
|
||
```
|
||
|
||
### GetLogger / GetSugar
|
||
|
||
获取logger实例（用于依赖注入）：
|
||
|
||
```go
|
||
func GetLogger() *zap.Logger
|
||
func GetSugar() *zap.SugaredLogger
|
||
```
|
||
|
||
## 示例
|
||
|
||
完整示例请参考：`services/userService/main.go`
|
||
|