# z1log

**Repository Path**: z1gotool/z1log

## Basic Information

- **Project Name**: z1log
- **Description**: 轻量的日志，基于标准log库，实现日志分级输出到各种的文件，而且支持按每年，每月，每日，每小时，每分钟，每周拆分日志文件。
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-03-29
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# z1log

轻量日志库，基于 Go 标准 `log` 库，零外部依赖。支持日志分级、文件输出、按时间自动拆分、按级别拆分，开箱即用。

## 功能特性

- **4 个日志级别**：DEBUG / INFO / WARNING / ERROR
- **3 种输出模式**：仅控制台 / 仅文件 / 控制台 + 文件
- **6 种时间拆分**：按年 / 月 / 周 / 日 / 时 / 分
- **按级别拆分**：每个级别写入独立文件（`_debug_` / `_info_` / `_warning_` / `_error_`）
- **自动轮转**：后台 goroutine 每分钟检测日期变化，自动切换到新文件
- **并发安全**：基于 `atomic.Pointer` 的全局 logger 原子切换 + 每级别独立 `sync.Mutex`
- **优雅降级**：文件打开失败时自动回退到 stdout，不崩溃
- **Go 1.20+**，零外部依赖

## 安装

```bash
go get gitee.com/z1gotool/z1log
```

## 快速开始

```go
package main

import "gitee.com/z1gotool/z1log"

func main() {
    // 不设置也可以用，默认输出到控制台
    z1log.Debug("This is a debug message")
    z1log.Infof("This is a info message, time: %v", "2026-07-09")
    z1log.Warning("This is a warning message")
    z1log.Error("This is an error message")
}
```

## 配置日志

```go
// 函数签名（保持向后兼容）
// SetLog(level, fileName, splitTime, splitLevel, outputType)
z1log.SetLog(
    z1log.DEBUG,            // 输出日志级别，小于此级别的不输出
    "logs/app.log",         // 文件输出路径和名称，为空表示不输出文件
    z1log.EveryDay,         // 按天拆分文件
    true,                   // 是否按日志级别拆分文件
    z1log.OUTPUT_TYPE_BOTH, // 输出模式：控制台 + 文件
)
```

### 输出模式

| 常量 | 说明 |
|------|------|
| `OUTPUT_TYPE_STDOUT` | 仅输出到控制台 |
| `OUTPUT_TYPE_FILE` | 仅输出到文件 |
| `OUTPUT_TYPE_BOTH` | 同时输出到控制台和文件 |

### 时间拆分

| 常量 | 示例文件名 |
|------|-----------|
| `EveryYear` | `app_2026.log` |
| `EveryMonth` | `app_2026-07.log` |
| `EveryDay` | `app_2026-07-09.log` |
| `EveryWeek` | `app_2026_28week.log` |
| `EveryHour` | `app_2026-07-09_15.log` |
| `EveryMinute` | `app_2026-07-09_15_04.log` |

### 按级别拆分

设置 `splitLevel=true` 后，每个级别写入独立文件：

| 级别 | 文件名示例 |
|------|-----------|
| DEBUG | `app_debug_2026-07-09.log` |
| INFO | `app_info_2026-07-09.log` |
| WARNING | `app_warning_2026-07-09.log` |
| ERROR | `app_error_2026-07-09.log` |

设置 `splitLevel=false` 时，所有级别写入同一个文件：`app_2026-07-09.log`

## API

### 日志函数

| 函数 | 说明 |
|------|------|
| `Debug(args ...any)` | DEBUG 级别输出 |
| `Info(args ...any)` | INFO 级别输出 |
| `Warning(args ...any)` | WARNING 级别输出 |
| `Error(args ...any)` | ERROR 级别输出 |
| `Debugf(format string, args ...any)` | DEBUG 级别格式化输出 |
| `Infof(format string, args ...any)` | INFO 级别格式化输出 |
| `Warningf(format string, args ...any)` | WARNING 级别格式化输出 |
| `Errorf(format string, args ...any)` | ERROR 级别格式化输出 |

### 配置函数

| 函数 | 说明 |
|------|------|
| `SetLog(level, fileName, splitTime, splitLevel, outputType)` | 配置全局日志器 |
| `NewLogger(level, fileName, splitTime, splitLevel)` | 创建独立 Logger 实例 |

### 常量

```go
// 日志级别
DEBUG   = 1
INFO    = 2
WARNING = 3
ERROR   = 4
ALL     = 735

// 时间拆分
EveryYear   = 1
EveryMonth  = 2
EveryDay    = 3
EveryWeek   = 4
EveryHour   = 5
EveryMinute = 6

// 输出模式
OUTPUT_TYPE_STDOUT = 1
OUTPUT_TYPE_FILE   = 2
OUTPUT_TYPE_BOTH   = 3
```

## 使用示例

### 仅控制台输出

```go
z1log.SetLog(z1log.DEBUG, "", z1log.EveryDay, false, z1log.OUTPUT_TYPE_STDOUT)
```

### 文件 + 控制台，按天拆分，按级别分文件

```go
z1log.SetLog(z1log.DEBUG, "logs/app.log", z1log.EveryDay, true, z1log.OUTPUT_TYPE_BOTH)
```

### 独立 Logger 实例

```go
logger := z1log.NewLogger(z1log.INFO, "logs/app.log", z1log.EveryHour, false)
defer logger.Close()
logger.Println(z1log.INFO, "custom logger message")
```

## 测试

```bash
go test -v ./...
```

32 个测试覆盖：级别过滤、格式化输出、文件输出、按级别拆分、并发安全、Close 幂等、旋转检测、错误降级。

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request