zap_logger/README.md

# zap_logger 日志组件库使用文档

## 项目概述

`zap_logger` 是一个基于 [Zap](https://github.com/uber-go/zap) 的日志组件库，提供灵活的多输出目标支持、可定制的日志格式和级别控制，以及与 Loki 日志系统的集成能力。该库旨在简化 Go 应用程序的日志配置流程，满足不同环境下的日志收集需求。

## 核心功能

- **多输出目标**：同时支持控制台输出、文件输出和 Loki 日志系统
- **灵活配置**：通过 YAML 配置文件或代码选项动态调整日志行为
- **日志轮转**：文件日志自动轮转，支持大小限制、备份数量和压缩
- **日志编码**：支持 JSON 和 Console 两种编码格式，可按输出目标单独配置
- **级别控制**：支持细粒度的日志级别设置（Debug, Info, Warn, Error 等）
- **默认配置**：内置合理默认值，零配置快速启动

## 安装方法

```go
go get code.mrx.ltd/pkg/zap_logger
```

## 快速开始

### 默认配置

无需任何配置文件，直接初始化即可使用默认配置（控制台输出，Info级别，Console编码）：

```go
package main

import (
  "code.mrx.ltd/pkg/zap_logger"
  "go.uber.org/zap"
)

func main() {
  // 使用默认配置初始化
  if err := zap_logger.NewZapLogger(""); err != nil {
    panic(err)
  }

  // 使用全局日志器
  log.Info("这是一条info级别的日志")
  log.Error("这是一条error级别的日志")
}
```

### 自定义配置文件

创建 YAML 配置文件（如 `logger.yaml`）：

```yaml
logger:
  encoder: "json"       # 全局编码器 (json/console)
  level: "info"         # 全局日志级别
  stack_level: panic    # 全局堆栈打印级别，触发panic及以上级别日志时打印堆栈跟踪

file:
  enable: true          # 启用文件输出,默认关闭
  filename: "app.log"   # 日志文件名,不填写则自动生成
  max_size: 10          # 单个文件最大尺寸(MB)
  max_age: 7            # 日志保留天数
  max_backups: 5        # 最大备份数量
  local_time: true      # 使用本地时间命名备份文件
  compress: true        # 压缩备份文件

console:
  enable: true          # 启用控制台输出,默认开启
  color: true           # 启用彩色输出

loki:
  enable: true          # 启用Loki输出,默认关闭
  host: "localhost"     # Loki服务地址
  port: 3100            # Loki服务端口
  source: "app"         # 日志来源标识
  service: "api"        # 服务名称
  job: "backend"        # 任务名称
  environment: "prod"   # 环境标识
```

通过配置文件初始化：

```go
if err := zap_logger.NewZapLogger("logger.yaml"); err != nil {
  panic(err)
}
```

## 配置说明

### 全局配置 (logger)

| 字段名         | 类型   | 说明       | 可选值                 | 默认值       |
|-------------|--------|----------|------------------------|-----------|
| encoder     | string | 全局日志编码器  | "json", "console"      | "console" |
| level       | string | 全局日志级别   | "debug", "info", "warn", "error", "dpanic", "panic", "fatal" | "info"    |
| stack_level | string | 全局堆栈打印级别 | "warn", "error", "dpanic", "panic", "fatal" | "panic"   |

### 文件输出配置 (file)

| 字段名        | 类型   | 说明                          | 默认值                          |
|---------------|--------|-------------------------------|---------------------------------|
| enable        | bool   | 是否启用文件输出              | false                           |
| encoder       | string | 文件日志编码器（覆盖全局）    | 继承 logger.encoder             |
| level         | string | 文件日志级别（覆盖全局）      | 继承 logger.level               |
| filename      | string | 日志文件路径                  | "app-{hostname}-{date}.log"     |
| max_size      | int    | 单个文件最大尺寸(MB)          | 10                              |
| max_age       | int    | 日志保留天数                  | 7                               |
| max_backups   | int    | 最大备份数量                  | 5                               |
| local_time    | bool   | 备份文件使用本地时间命名      | true                            |
| compress      | bool   | 是否压缩备份文件              | false                           |

### 控制台输出配置 (console)

| 字段名   | 类型   | 说明                          | 默认值               |
|----------|--------|-------------------------------|-------------------|
| enable   | bool   | 是否启用控制台输出            | true              |
| encoder  | string | 控制台日志编码器（覆盖全局）  | 继承 logger.encoder |
| level    | string | 控制台日志级别（覆盖全局）    | 继承 logger.level   |
| color    | bool   | 是否启用彩色输出              | false             |

### Loki输出配置 (loki)

| 字段名        | 类型   | 说明                          | 默认值                          |
|---------------|--------|-------------------------------|---------------------------------|
| enable        | bool   | 是否启用Loki输出              | false                           |
| encoder       | string | Loki日志编码器（覆盖全局）    | 继承 logger.encoder             |
| level         | string | Loki日志级别（覆盖全局）      | 继承 logger.level               |
| host          | string | Loki服务主机地址              | "localhost"                     |
| port          | int    | Loki服务端口                  | 3100                            |
| source        | string | 日志来源标识                  | ""                              |
| service       | string | 服务名称标签                  | ""                              |
| job           | string | 任务名称标签                  | ""                              |
| environment   | string | 环境标识标签                  | ""                              |

## 代码配置选项

除了配置文件外，还可以通过代码选项动态调整配置：

```go
import (
  "code.mrx.ltd/pkg/zap_logger"
)

func main() {
  // 使用代码选项自定义配置
  err := zap_logger.NewZapLogger("",
    zap_logger.WithEncoder(zap_logger.JsonEncoder),  // 设置全局编码器为JSON
    zap_logger.WithLevel("debug"),                  // 设置全局级别为Debug
    zap_logger.WithEnableFile(true),                // 启用文件输出
    zap_logger.WithFilename("app.log"),             // 设置日志文件名
    zap_logger.WithLokiEnable(true),                // 启用Loki输出
    zap_logger.WithLokiHost("loki.example.com"),    // 设置Loki主机
  )
  if err != nil {
    panic(err)
  }
}
```

完整选项列表：

| 函数名                     | 说明                          | 参数类型/示例                  |
|----------------------------|-------------------------------|--------------------------------|
| WithEncoder                | 设置全局编码器                | JsonEncoder/ConsoleEncoder     |
| WithLevel                  | 设置全局日志级别              | "debug", "info", "warn"等      |
| WithEnableFile             | 启用/禁用文件输出             | true/false                     |
| WithFilename               | 设置日志文件名                | "app.log"                      |
| WithFileMaxSize            | 设置文件最大尺寸(MB)          | 20                             |
| WithFileMaxAge             | 设置日志保留天数              | 15                             |
| WithFileMaxBackups         | 设置最大备份数量              | 10                             |
| WithFileLocaltime          | 备份文件使用本地时间          | true/false                     |
| WithFileCompress           | 启用/禁用备份压缩             | true/false                     |
| WithConsoleEnable          | 启用/禁用控制台输出           | true/false                     |
| WithConsoleEnableColor     | 启用/禁用控制台彩色输出       | true/false                     |
| WithLokiEnable             | 启用/禁用Loki输出             | true/false                     |
| WithLokiHost               | 设置Loki服务主机              | "loki.example.com"             |
| WithLokiPort               | 设置Loki服务端口              | 3100                           |
| WithLokiSource             | 设置日志来源标识              | "payment-service"              |
| WithLokiService            | 设置服务名称标签              | "api"                          |
| WithLokiJob                | 设置任务名称标签              | "backend"                      |
| WithLokiEnvironment        | 设置环境标识标签              | "production"                   |

## 高级使用示例

### 多输出组合

同时启用文件和Loki输出，禁用控制台：

```yaml
logger:
  encoder: "json"
  level: "info"

file:
  enable: true
  filename: "app.log"

console:
  enable: false

loki:
  enable: true
  host: "loki.internal"
  port: 3100
  service: "user-service"
  environment: "prod"
```

## 注意事项

1. 配置优先级：代码选项 > 配置文件 > 默认配置
2. 日志级别：如果全局级别高于输出特定级别，以全局级别为准
3. Loki依赖：使用Loki输出时需确保Loki服务可访问
4. 错误处理：NewZapLogger返回的错误需妥善处理，避免日志初始化失败

## 框架集成插件

### Gin 中间件集成

`zap_logger` 提供了 Gin 框架的日志中间件，可自动记录 HTTP 请求信息：

```go
import (
  "code.mrx.ltd/pkg/zap_logger"
  "code.mrx.ltd/pkg/zap_logger/plugins"
  "github.com/gin-gonic/gin"
)

func main() {
  // 初始化日志
  if err := zap_logger.NewZapLogger("logger.yaml"); err != nil {
    panic(err)
  }

  r := gin.Default()
  // 添加Gin日志中间件
  r.Use(plugins.GinZap())

  // 自定义日志格式示例
  customFormat := func(param plugins.LogParam) string {
    return fmt.Sprintf("[%s] %s %s %d %s",
      param.Time, param.Method, param.Path, param.StatusCode, param.Latency)
  }
  r.Use(plugins.GinZapWithFormat(customFormat))

  r.Run()
}
```

中间件默认记录：时间、状态码、响应耗时、客户端IP、请求方法、路径和用户代理信息。

### GORM 日志插件

集成 GORM ORM 框架的日志插件，可记录 SQL 执行情况：

```go
import (
  "code.mrx.ltd/pkg/zap_logger"
  "code.mrx.ltd/pkg/zap_logger/plugins"
  "gorm.io/driver/mysql"
  "gorm.io/gorm"
)

func main() {
  // 初始化日志
  if err := zap_logger.NewZapLogger("logger.yaml"); err != nil {
    panic(err)
  }

  // 配置GORM使用zap_logger
  db, err := gorm.Open(mysql.Open("dsn"), &gorm.Config{
    Logger: plugins.DefaultGormLogger, // 使用默认配置
  })

  // 自定义GORM日志配置
  customLogger := plugins.NewGormLogger(plugins.logger.Config{
    SlowThreshold:             3 * time.Second, // 慢查询阈值
    LogLevel:                  plugins.logger.Warn, // 日志级别
    IgnoreRecordNotFoundError: true, // 忽略记录不存在错误
  })

  db, err = gorm.Open(mysql.Open("dsn"), &gorm.Config{
    Logger: customLogger,
  })
}
```

GORM 插件默认记录：SQL 语句、执行时间、影响行数，支持慢查询告警和错误日志分级。