[English]

RainbowLog v1 正式发布！从 v0.0.12 一路走到 v1.0.1，这次大版本更新带来了更清晰的包结构、更简洁的 API、以及多项性能优化和 bug 修复。本文将梳理 v0.0.12 至 v1.0.1 之间的重要改进，并说明新旧版本的使用方式差异。

版本演进

版本	主要内容
v0.0.12	基线版本
v0.0.13	Windows 控制台 ANSI 支持
v0.0.14	大规模重构 + Bug 修复 + 性能优化 + 测试覆盖
v1.0.0	代码库重组：核心移至 log/ 包，全局日志器移至 global/ 包
v1.0.1	全局日志器包从 global/ 重命名为 logger/

---

各版本改进详情

v0.0.13 — Windows 控制台彩色日志

新增 record_packer_console_windows.go，使 Windows 终端也能显示彩色日志输出。对于在 Windows 环境下开发的用户，再也不用忍受单调的黑白日志了。

v0.0.14 — 全面打磨

这是 v1 之前变更最密集的版本，包含 22 个提交，主要改进如下：

Bug 修复：

• 修复短写入（short write）错误处理
• ObjectData 方法增加对 []byte 输入的 nil 检查
• 修复编码 duration slice 时首元素重复问题
• 修复 SubLogger 浅拷贝问题 — writerEncoders 改为深拷贝，子 Logger 修改不再影响父 Logger
• 加载配置文件失败时附加详细错误信息

性能优化：

• 预构建 text encoder，避免每次 createRecord 时分配
• 全局 logger 改为延迟初始化（lazy init）+ sync.Mutex 双重检查，移除 init() 函数
• caller 路径截断逻辑前置优化

新功能：

• 新增 TimeFormatUnixNano（UNIXNANO）纳秒时间格式
• 新增 TimestampFunc 变量，可自定义时间源（便于测试）

重构：

• 重构 BufferedLevelWriter，正确实现 LevelWriter 接口
• text encoder 中修正错误使用 JSONMarshalFunc 的问题，替换为 TextMarshalFunc
• 简化 multiLevelWriter.WriteLevel 实现
• NewTextEncoder 从 var 改为 func
• 移除 LogRecord 中未使用的 mutex

测试： 新增 encoder 接口、hex、float/int slices、strings 等测试用例。

构建： Go 版本从 1.23 升级到 1.26，新增 golang.org/x/sync 依赖。

v1.0.0 — 包结构重组（破坏性变更）

这是最大的一次结构性调整：将根目录下的核心文件全部移入 log/ 子包，全局日志器从 log/global_logger.go 移至新包 global/global_logger.go。

旧路径 (v0.x)	新路径 (v1.0.0)
encoder.go	log/encoder.go
logger.go	log/logger.go
option.go	log/option.go
record.go	log/record.go
writer.go	log/writer.go
log/global_logger.go	global/global_logger.go

v1.0.1 — 全局日志器包重命名（破坏性变更）

全局日志器包从 global/ 重命名为 logger/，更加直观。

---

新旧版本 API 使用方式对比

1. 全局 Logger — 导入路径与调用方式

v0.x（旧方式）：

import "github.com/rambollwong/rainbowlog/log"

func main() {
    log.UseDefault()
    log.Logger.Info().Msg("Hello world!").Done()
    //   ^^^^^^ 必须通过 Logger 字段
}

v1.x（新方式）：

import "github.com/rambollwong/rainbowlog/logger"

func main() {
    logger.UseDefault()
    logger.Info().Msg("Hello world!").Done()
    //      ^^ 包级函数，无需 .Logger
}

⚠️ 变化：

• 导入路径：rainbowlog/log → rainbowlog/logger
• 调用方式：log.Logger.Info() → logger.Info()（包级便捷函数）
• 初始化：从 init() 自动调用变为首次使用时 lazyInit()

2. 自定义 Logger — 类型前缀变化

v0.x（旧方式）：

import "github.com/rambollwong/rainbowlog"

logger := rainbowlog.New(
    rainbowlog.WithDefault(),
    rainbowlog.AppendsEncoderWriters(rainbowlog.JsonEnc, os.Stderr),
)

v1.x（新方式）：

import "github.com/rambollwong/rainbowlog/log"

logger := log.New(
    log.WithDefault(),
    log.AppendsEncoderWriters(log.JsonEnc, os.Stderr),
)

⚠️ 所有类型和函数前缀从 rainbowlog.XXX 变为 log.XXX。

3. 完整类型引用对照表

概念	v0.x 前缀	v1.x 前缀
Logger 类型	*rainbowlog.Logger	*log.Logger
创建函数	rainbowlog.New(...)	log.New(...)
Option 类型	rainbowlog.Option	log.Option
Record 类型	rainbowlog.Record	log.Record
Hook 类型	rainbowlog.Hook / rainbowlog.HookFunc	log.Hook / log.HookFunc
LevelWriter	rainbowlog.LevelWriter	log.LevelWriter
编码器	rainbowlog.JsonEnc / rainbowlog.TextEnc	log.JsonEnc / log.TextEnc
时间格式常量	rainbowlog.TimeFormatUnix	log.TimeFormatUnix
ConsolePacker	rainbowlog.ConsolePacker	log.ConsolePacker
全局函数	rainbowlog.GlobalCallerMarshalFunc	log.GlobalCallerMarshalFunc

4. 默认配置文件名称变更

版本	默认配置文件名
v0.x	rainbowlog.yaml
v1.x	log.yaml

5. 新增功能速览

纳秒时间格式（v0.0.14 新增）：

log.WithTimeFormat(log.TimeFormatUnixNano) // 输出纳秒级 Unix 时间戳

自定义时间源（v0.0.14 新增）：

log.TimestampFunc = func() time.Time {
    return time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
}

SubLogger 深拷贝（v0.0.14 修复）：子 Logger 的 writerEncoders 现在是独立副本，修改子 Logger 不再影响父 Logger。

---

升级指南

从 v0.x 升级到 v1.x，需要做以下修改：

1. 全局 Logger 导入路径："rainbowlog/log" → "rainbowlog/logger"
2. 全局 Logger 调用：log.Logger.XXX() → logger.XXX()（直接调用包函数）
3. 自定义 Logger 导入：改为 "rainbowlog/log"，类型前缀从 rainbowlog. 变为 log.
4. 配置文件：默认文件名从 rainbowlog.yaml 变为 log.yaml
5. Go 版本：需要 Go 1.26+

---

Github 仓库

https://github.com/rambollwong/rainbowlog

如果觉得还不错，希望能给个 ⭐，你的支持是我前进的最大动力。

---

💰 赞助支持

如果喜欢这个项目，可以请作者喝杯柠檬水 ☕️。你的支持是我持续更新的动力！

• 微信支付：

• 支付宝：