140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# MIGRATION (V1)
|
||
|
||
本文档说明从旧版本/旧用法迁移到当前 `starlog` 的推荐路径。
|
||
|
||
## 先说结论
|
||
|
||
- 当前版本是 **V1 兼容迁移阶段**。
|
||
- **旧 API 仍可继续使用，不需要立即重写。**
|
||
- 推荐逐步迁移到 `Config` 快照方式和新能力（结构化、多 sink、脱敏、测试 hook）。
|
||
|
||
## 兼容性承诺（V1）
|
||
|
||
1. 不移除旧 API。
|
||
2. 旧调用方式保持可运行。
|
||
3. 新能力以“增量引入”为主，不要求一次性改造。
|
||
|
||
## 推荐迁移顺序
|
||
|
||
### 第 0 步：先不改业务逻辑
|
||
|
||
如果你当前线上稳定，可以先升级依赖并保持原写法。
|
||
|
||
### 第 1 步：把“多项配置”改为一次性更新
|
||
|
||
旧写法（仍可用）：
|
||
|
||
```go
|
||
log.SetShowColor(false)
|
||
log.SetShowLevel(true)
|
||
log.SetShowFlag(false)
|
||
log.SetLevel(starlog.LvInfo)
|
||
```
|
||
|
||
推荐写法（V1 新增）：
|
||
|
||
```go
|
||
log.UpdateConfig(func(cfg *starlog.Config) {
|
||
cfg.ShowColor = false
|
||
cfg.ShowLevel = true
|
||
cfg.ShowFlag = false
|
||
cfg.Level = starlog.LvInfo
|
||
})
|
||
```
|
||
|
||
收益：
|
||
|
||
- 多项配置原子生效，减少并发中间态。
|
||
- 配置修改更集中，便于审计和 review。
|
||
|
||
### 第 2 步：逐步引入结构化字段与 Context
|
||
|
||
```go
|
||
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 步：生命周期收口（推荐）
|
||
|
||
旧写法（仍可用）：
|
||
|
||
```go
|
||
defer starlog.CloseStd()
|
||
```
|
||
|
||
推荐写法：
|
||
|
||
```go
|
||
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 方案。
|
||
|