starlog/docs/MIGRATION.md

MIGRATION (V1)

本文档说明从旧版本/旧用法迁移到当前 starlog 的推荐路径。

先说结论

• 当前版本是 V1 兼容迁移阶段。
• 旧 API 仍可继续使用，不需要立即重写。
• 推荐逐步迁移到 Config 快照方式和新能力（结构化、多 sink、脱敏、测试 hook）。

兼容性承诺（V1）

1. 不移除旧 API。
2. 旧调用方式保持可运行。
3. 新能力以“增量引入”为主，不要求一次性改造。

推荐迁移顺序

第 0 步：先不改业务逻辑

如果你当前线上稳定，可以先升级依赖并保持原写法。

第 1 步：把“多项配置”改为一次性更新

旧写法（仍可用）：

log.SetShowColor(false)
log.SetShowLevel(true)
log.SetShowFlag(false)
log.SetLevel(starlog.LvInfo)

推荐写法（V1 新增）：

log.UpdateConfig(func(cfg *starlog.Config) {
	cfg.ShowColor = false
	cfg.ShowLevel = true
	cfg.ShowFlag = false
	cfg.Level = starlog.LvInfo
})

收益：

• 多项配置原子生效，减少并发中间态。
• 配置修改更集中，便于审计和 review。

第 2 步：逐步引入结构化字段与 Context

log.WithField("trace_id", traceID).Info("request done")
log.WithContext(ctx).Error("call downstream failed")

第 3 步：输出链路升级

• 单路写入升级到 SetSinks(...) / MultiSink
• 需要分级分文件时使用 RouteHandler
• 归档建议走 RotatePolicy 主路径，并叠加 RotateManageOptions

第 4 步：安全与测试

• 脱敏：SetRedactor / AddRedactRule
• 测试断言：Observer / TestHook

第 5 步：生命周期收口（推荐）

旧写法（仍可用）：

defer starlog.CloseStd()

推荐写法：

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
defer starlog.Shutdown(ctx)

说明：

• Shutdown(ctx) 会等待异步 handler drain，并统一关闭资源。
• Close() 仍可用，但不等待异步 handler 队列。

常见旧写法到推荐写法

1. 配置项逐条 setter
   推荐：UpdateConfig 批量改

2. 只打印字符串
   推荐：关键路径增加 WithField(s) 与 WithError

3. 仅 writer 输出
   推荐：MultiSink + RouteHandler 做按级别拆分

4. 原生 log.Logger 接入
   推荐：AsStdlibLoggerWithOptions（prefix/flags/level-mapper）

5. 手工配置大量 setter
   推荐：NewProductionConfig/NewDevelopmentConfig + ApplyProductionConfig/ApplyDevelopmentConfig

6. 旧 StartArchive 轮转启动
   推荐：StartRotatePolicy / StartManagedRotatePolicy，模板场景可直接用 StartRotateByTime/BySize/ByTimeSize

旧 API 仍可用（重要）

以下旧/兼容路径当前仍可用：

• 旧 setter/getter 全部可用
• 历史错拼兼容名仍可用（如 EnbaleWrite、IsWriteStoed、HookBeforArchive）
• Archive 旧模型仍可用（建议新代码优先 RotatePolicy）
• 旧生命周期入口仍可用（如 CloseStd、Close），但建议新代码优先 Shutdown(ctx) / CloseLogFile

升级后验证建议

1. 跑单元测试：go test ./...
2. 跑并发检测：go test -race ./...
3. 跑规则检查：sentrux check .
4. 重点验证：
   • 级别过滤是否符合预期
   • 归档文件数量/保留策略
   • 异步丢弃计数和写入错误计数

何时需要进一步迁移

如果你符合以下场景，建议优先推进推荐写法：

• 多 goroutine 同时改日志配置
• 需要跨模块统一日志字段规范
• 需要审计日志（脱敏、分级路由、归档治理）

---

如果你希望，我可以基于你当前项目的实际日志初始化代码，给出一份“一次改完可落地”的迁移 patch 方案。