# 微服务日志架构设计

## 一、设计原则

### 1.1 核心原则

1. **服务独立性**：每个微服务应该有自己独立的日志实例
2. **统一配置**：所有服务使用相同的日志配置和格式
3. **共享工具**：在共享包中提供统一的日志初始化逻辑
4. **分散部署**：每个服务可以独立配置日志级别和输出方式

### 1.2 架构选择

**推荐方案**：**每个服务独立，共享logger包**

- ✅ 每个服务有独立的logger实例
- ✅ 所有服务共享 `pkg/logger` 包的初始化逻辑
- ✅ 统一的日志格式和配置方式
- ✅ 服务可以独立配置日志级别

---

## 二、架构设计

### 2.1 目录结构

```
backend/
├── pkg/
│   └── logger/
│       └── logger.go          # 共享的日志工具包（统一配置）
├── services/
│   ├── userService/
│   │   ├── main.go            # 初始化自己的logger实例
│   │   └── service/
│   │       └── auth_service.go # 使用logger记录日志
│   ├── assetService/
│   │   ├── main.go            # 初始化自己的logger实例
│   │   └── service/
│   │       └── asset_service.go
│   ├── socialService/
│   │   ├── main.go            # 初始化自己的logger实例
│   │   └── service/
│   │       └── social_service.go
│   └── ...
└── gateway/                    # API Gateway
    └── main.go                # 初始化自己的logger实例
```

### 2.2 日志包设计

**文件**：`pkg/logger/logger.go`

**设计要点**：
- 提供统一的初始化函数 `Init()`
- 每个服务调用 `Init()` 创建自己的logger实例
- 支持服务级别的配置（服务名、环境等）
- 统一的日志格式（JSON格式，包含服务名）

**实现方式**：

```go
package logger

import (
	"os"

	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
)

var (
	// Logger 全局logger实例（每个服务独立）
	Logger *zap.Logger
	// Sugar 全局Sugar实例
	Sugar *zap.SugaredLogger
)

// Config 日志配置
type Config struct {
	ServiceName string // 服务名称（如：user-service, asset-service）
	Environment string // 环境：development 或 production
	LogLevel    string // 日志级别：debug, info, warn, error
	LogPath     string // 日志文件路径（可选，默认为当前目录下的logs/）
}

// Init 初始化日志（每个服务独立调用）
func Init(config Config) error {
	var zapConfig zap.Config

	// 设置服务名作为默认字段
	serviceNameField := zap.String("service", config.ServiceName)

	// 环境判断
	if config.Environment == "development" {
		// 开发环境：彩色控制台输出
		zapConfig = zap.NewDevelopmentConfig()
		zapConfig.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
	} else {
		// 生产环境：JSON格式，文件输出
		zapConfig = zap.NewProductionConfig()
		
		// 设置日志文件路径
		logPath := config.LogPath
		if logPath == "" {
			logPath = "logs"
		}
		
		// 创建日志目录
		if err := os.MkdirAll(logPath, 0755); err != nil {
			return err
		}
		
		zapConfig.OutputPaths = []string{
			"stdout",
			logPath + "/" + config.ServiceName + ".log",
		}
		zapConfig.ErrorOutputPaths = []string{
			"stderr",
			logPath + "/" + config.ServiceName + "-error.log",
		}
	}

	// 设置日志级别
	logLevel := config.LogLevel
	if logLevel == "" {
		logLevel = os.Getenv("LOG_LEVEL")
		if logLevel == "" {
			logLevel = "info"
		}
	}
	
	var level zapcore.Level
	if err := level.UnmarshalText([]byte(logLevel)); err == nil {
		zapConfig.Level = zap.NewAtomicLevelAt(level)
	}

	// 构建logger
	var err error
	Logger, err = zapConfig.Build(
		zap.AddCaller(),
		zap.AddStacktrace(zapcore.ErrorLevel),
		zap.Fields(serviceNameField), // 添加服务名字段
	)
	if err != nil {
		return err
	}

	// 创建Sugar实例
	Sugar = Logger.Sugar()

	return nil
}

// Sync 刷新日志缓冲区
func Sync() {
	if Logger != nil {
		_ = Logger.Sync()
	}
}

// GetLogger 获取logger实例
func GetLogger() *zap.Logger {
	return Logger
}

// GetSugar 获取Sugar实例
func GetSugar() *zap.SugaredLogger {
	return Sugar
}
```

---

## 三、各服务使用方式

### 3.1 User Service（用户与认证服务）

**文件**：`services/userService/main.go`

```go
package main

import (
	"flag"
	"os"

	"github.com/topfans/backend/pkg/database"
	"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,
		LogLevel:    os.Getenv("LOG_LEVEL"),
	}); err != nil {
		panic(err)
	}
	defer logger.Sync()

	logger.Sugar.Info("Starting User Service...")

	// 其他初始化代码...
}
```

**文件**：`services/userService/service/auth_service.go`

```go
package service

import (
	"github.com/topfans/backend/pkg/logger"
	"go.uber.org/zap"
)

func (s *AuthService) Register(req *pb.RegisterRequest) (*pb.RegisterResponse, error) {
	logger.Logger.Info("Register request received",
		zap.String("mobile", req.Mobile),
		zap.Int64("star_id", req.StarId),
	)
	
	// 业务逻辑...
}
```

### 3.2 Asset Service（资产服务）

**文件**：`services/assetService/main.go`

```go
package main

import (
	"github.com/topfans/backend/pkg/logger"
)

func main() {
	// 初始化日志（独立的logger实例）
	if err := logger.Init(logger.Config{
		ServiceName: "asset-service",
		Environment: os.Getenv("ENV"),
		LogLevel:    os.Getenv("LOG_LEVEL"),
	}); err != nil {
		panic(err)
	}
	defer logger.Sync()

	logger.Sugar.Info("Starting Asset Service...")
	// ...
}
```

### 3.3 API Gateway

**文件**：`gateway/main.go`

```go
package main

import (
	"github.com/topfans/backend/pkg/logger"
)

func main() {
	// 初始化日志（独立的logger实例）
	if err := logger.Init(logger.Config{
		ServiceName: "api-gateway",
		Environment: os.Getenv("ENV"),
		LogLevel:    os.Getenv("LOG_LEVEL"),
	}); err != nil {
		panic(err)
	}
	defer logger.Sync()

	logger.Sugar.Info("Starting API Gateway...")
	// ...
}
```

---

## 四、日志格式示例

### 4.1 开发环境（控制台）

```
2024-01-01T10:00:00.000+0800	INFO	service=user-service	Register request received	{"mobile": "13800138000", "star_id": 123}
```

### 4.2 生产环境（JSON格式）

```json
{
  "level": "info",
  "ts": 1704067200.000,
  "caller": "auth_service.go:45",
  "msg": "Register request received",
  "service": "user-service",
  "mobile": "13800138000",
  "star_id": 123
}
```

**优势**：
- 每个日志都包含 `service` 字段，便于区分是哪个服务的日志
- JSON格式便于日志收集系统（如ELK、Loki）解析
- 统一的格式便于统一管理和查询

---

## 五、日志收集（可选，生产环境）

### 5.1 集中式日志收集架构

```
各个服务（独立logger）
    ↓
日志文件（本地存储）
    ↓
日志收集Agent（Filebeat/Fluentd）
    ↓
日志聚合系统（ELK Stack / Grafana Loki）
    ↓
可视化查询（Kibana / Grafana）
```

### 5.2 实现方式

1. **本地文件存储**：每个服务将日志写入本地文件
2. **日志收集Agent**：使用Filebeat或Fluentd收集日志
3. **日志聚合**：发送到Elasticsearch或Loki
4. **可视化查询**：通过Kibana或Grafana查询

**优势**：
- 各服务独立，不依赖外部系统
- 即使日志收集系统故障，本地仍有日志
- 统一的查询界面，可以跨服务查询

---

## 六、环境变量配置

### 6.1 各服务独立配置

每个服务可以通过环境变量独立配置：

```bash
# User Service
ENV=production
LOG_LEVEL=info
LOG_PATH=/var/log/user-service

# Asset Service
ENV=production
LOG_LEVEL=debug
LOG_PATH=/var/log/asset-service

# API Gateway
ENV=production
LOG_LEVEL=warn
LOG_PATH=/var/log/gateway
```

### 6.2 Docker Compose示例

```yaml
services:
  user-service:
    environment:
      - ENV=production
      - LOG_LEVEL=info
      - LOG_PATH=/var/log
    volumes:
      - ./logs/user-service:/var/log

  asset-service:
    environment:
      - ENV=production
      - LOG_LEVEL=info
      - LOG_PATH=/var/log
    volumes:
      - ./logs/asset-service:/var/log
```

---

## 七、最佳实践

### 7.1 日志级别建议

| 服务类型 | 推荐级别 | 说明 |
|---------|---------|------|
| API Gateway | `warn` | 只记录警告和错误 |
| User Service | `info` | 记录关键操作 |
| Asset Service | `info` | 记录关键操作 |
| Task Service | `debug` | 任务调度需要详细日志 |

### 7.2 日志记录原则

1. **每个服务独立初始化**：确保服务独立性
2. **统一的日志格式**：便于统一管理和查询
3. **包含服务名**：每条日志都标识所属服务
4. **结构化日志**：使用字段而不是字符串拼接
5. **敏感信息不记录**：密码、完整Token等

### 7.3 性能考虑

- 生产环境使用结构化日志（`Logger.Info`）而不是Sugar API
- 合理设置日志级别，避免过多日志影响性能
- 使用日志轮转，避免日志文件过大

---

## 八、总结

### 推荐方案

✅ **每个服务独立，共享logger包**

**优势**：
1. **服务独立性**：每个服务可以独立部署和配置
2. **统一格式**：所有服务使用相同的日志格式
3. **易于管理**：共享的logger包便于维护和升级
4. **灵活配置**：每个服务可以独立配置日志级别
5. **便于扩展**：后续可以轻松添加日志收集功能

**不推荐**：统一管理所有服务的日志实例

**原因**：
- 破坏了服务的独立性
- 难以在不同服务中使用不同的日志配置
- 服务间耦合度增加

---

## 九、实施步骤

1. **第一步**：创建共享的 `pkg/logger/logger.go`
2. **第二步**：在每个服务的 `main.go` 中初始化logger
3. **第三步**：在Service层中使用日志记录
4. **第四步**：（可选）配置日志收集系统

---

## 十、相关文档

- `services/userService/zap日志框架集成指南.md` - 详细的zap集成指南
- `docs/微服务架构设计.md` - 微服务架构总体设计