# 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 方案。