# zzlog

**Repository Path**: douyaye/zzlog

## Basic Information

- **Project Name**: zzlog
- **Description**: 一个很简单的日志框架,按天分割日志, 支持error和info 2种简单模式,日志同时输出文件和os.Stdout
- **Primary Language**: Go
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-02-11
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zzlog

一个基于 Go 标准库 `log` 的轻量级日志封装，开箱即用，适合小型项目与个人服务。

## 特性

- 支持 **Debug / Info / Error** 三个日志级别，按级别写入独立文件
- 基于 [lumberjack](https://github.com/natefinch/lumberjack) 做日志轮转（按文件大小，非按天）
- 可选同时输出到控制台（`os.Stdout`）
- 包级函数直接调用，无需手动初始化
- 支持手动触发日志轮转

## 安装

```bash
go get gitee.com/douyaye/zzlog
```

## 快速开始

```go
package main

import "gitee.com/douyaye/zzlog"

func main() {
    zzlog.SetLogDir("./logs")       // 日志目录，默认 ./zzlog
    zzlog.SetIsStdout(true)         // 是否同时输出到控制台，默认 true
    zzlog.SetLogLevel(zzlog.LevelInfo)

    zzlog.Debug("调试信息")          // LevelInfo 下不会输出
    zzlog.Info("业务日志")
    zzlog.Error("错误信息")

    zzlog.InfoF("用户 %s 登录", "alice")
    zzlog.ErrorF("请求失败: code=%d", 500)
}
```

导入包后会自动初始化，无需额外调用 `Init`。

## 日志级别

| 常量 | 值 | 说明 |
|------|----|------|
| `LevelDebug` | 0 | 输出 debug、info、error |
| `LevelInfo`  | 1 | 输出 info、error（**默认**） |
| `LevelError` | 2 | 仅输出 error |
| `LevelOff`   | 3 | 关闭所有日志 |

```go
zzlog.SetLogLevel(zzlog.LevelError) // 只保留 error 日志
```

## 日志文件

每个级别对应一个文件，默认目录为 `./zzlog`：

```
./zzlog/
├── debug.log
├── info.log
└── error.log
```

轮转由 lumberjack 管理，达到大小上限后自动切分并保留历史文件。

## 默认配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 日志目录 | `./zzlog` | |
| 日志级别 | `LevelInfo` | |
| 控制台输出 | `true` | |
| 单文件大小上限 | `50` MB | |
| 保留备份数 | `20` | |
| 保留天数 | `30` | |
| 压缩历史文件 | `false` | |

## API

### 写日志

| 函数 | 说明 |
|------|------|
| `Debug(args ...any)` | 调试日志 |
| `DebugF(format string, args ...any)` | 格式化调试日志 |
| `Info(args ...any)` | 信息日志 |
| `InfoF(format string, args ...any)` | 格式化信息日志 |
| `Error(args ...any)` | 错误日志 |
| `ErrorF(format string, args ...any)` | 格式化错误日志 |

### 配置

| 函数 | 说明 |
|------|------|
| `SetLogLevel(lv int)` | 设置日志级别 |
| `SetLogDir(dir string)` | 设置日志目录 |
| `SetIsStdout(b bool)` | 是否同时输出到控制台 |
| `SetMaxSize(size int)` | 单文件大小上限（MB） |
| `SetFlags(flag int)` | 设置 log 格式标志，默认 `log.LstdFlags \| log.Lshortfile \| log.Lmsgprefix` |
| `SetConfig(c *LogCfg)` | 一次性设置完整配置 |
| `Rotate()` | 手动触发日志轮转 |

### 批量配置示例

`LogCfg` 中仅 `MaxSize`、`MaxBackups`、`MaxAge`、`Compress` 可从包外设置；级别、目录、控制台输出请用对应 Setter：

```go
zzlog.SetLogLevel(zzlog.LevelDebug)
zzlog.SetLogDir("./logs")
zzlog.SetIsStdout(true)
zzlog.SetConfig(&zzlog.LogCfg{
    MaxSize:    100,
    MaxBackups: 10,
    MaxAge:     7,
    Compress:   true,
})
```

## 日志格式

默认包含时间戳、源码文件名与行号，以及级别前缀，例如：

```
info 2026/06/05 10:00:00 main.go:12: 业务日志
```

可通过 `SetFlags` 自定义格式，参见 [标准库 log 文档](https://pkg.go.dev/log#pkg-constants)。

## 注意事项

1. 日志目录不存在时会**自动创建**（`MkdirAll`）。
2. 轮转方式为**按文件大小**，不是按天切分。
3. 配置变更（如 `SetLogDir`）会重新绑定输出，建议在程序启动时完成配置。

## 更多示例

参见 [example/main.go](example/main.go)。

## License

参见 [LICENSE](LICENSE)。