# 错误流程模式

错误流程、一次处理原则和日志决策的详细模式。

## 缩进错误流程

在继续正常代码之前先处理错误。这通过使读者能够快速找到正常路径来提高可读性。

```go
// 好：错误处理优先，正常代码无缩进
if err != nil {
    // 错误处理
    return // 或 continue 等
}
// 正常代码
```

```go
// 不好：正常代码隐藏在 else 子句中
if err != nil {
    // 错误处理
} else {
    // 正常代码因缩进看起来不自然
}
```

### 避免对长期使用的变量使用 if 初始化语句

如果变量在多行中使用，将声明移出：

```go
// 好：声明与错误检查分开
x, err := f()
if err != nil {
    return err
}
// 大量使用 x 的代码
// 跨越多行
```

```go
// 不好：变量作用域限制在 else 块中，难以阅读
if x, err := f(); err != nil {
    return err
} else {
    // 大量使用 x 的代码
    // 跨越多行
}
```

---

## 错误只处理一次

当调用者收到错误时，应该**只处理一次**。选择一种响应方式：

1. **返回错误**（包装或原文）让调用者处理
2. **记录日志并优雅降级**（不返回错误）
3. **匹配并处理**特定错误情况，返回其他错误

**如果返回了错误，就不要自己记录日志** — 让调用者处理。对同一错误既记录日志又返回是最常见的"一次处理"违规，导致重复噪音，因为调用栈上层的调用者也会处理该错误。

```go
// 不好：既记录日志又返回 — 导致日志噪音
u, err := getUser(id)
if err != nil {
    log.Printf("Could not get user %q: %v", id, err)
    return err  // 调用者也会记录这个！
}

// 好：包装并返回 — 让调用者决定如何处理
u, err := getUser(id)
if err != nil {
    return fmt.Errorf("get user %q: %w", id, err)
}

// 好：记录日志并优雅降级（不返回错误）
if err := emitMetrics(); err != nil {
    // 写入指标失败不应影响应用程序
    log.Printf("Could not emit metrics: %v", err)
}
// 继续执行...

// 好：匹配特定错误，返回其他错误
tz, err := getUserTimeZone(id)
if err != nil {
    if errors.Is(err, ErrUserNotFound) {
        // 用户不存在，使用 UTC
        tz = time.UTC
    } else {
        return fmt.Errorf("get user %q: %w", id, err)
    }
}
```

---

## 记录日志 vs 返回错误

> 错误只处理一次 — 记录日志或返回，不要两者都做。

### 决策流程

```
遇到错误？
├─ 调用者可以采取行动？→ 返回错误（通过 %w 附带上下文）
├─ 在调用链顶部？→ 记录日志并处理（返回 HTTP 状态码、退出等）
└─ 都不是？→ 以适当级别记录日志并继续
```

### 不要既记录日志又返回

```go
// 不好：错误既被记录又被返回 — 在日志中出现两次
func process(ctx context.Context, id string) error {
    result, err := fetch(ctx, id)
    if err != nil {
        log.Printf("failed to fetch %s: %v", id, err)
        return fmt.Errorf("fetching %s: %w", id, err)
    }
    return handle(result)
}

// 好：带上下文返回 — 让调用者决定是否记录日志
func process(ctx context.Context, id string) error {
    result, err := fetch(ctx, id)
    if err != nil {
        return fmt.Errorf("fetching %s: %w", id, err)
    }
    return handle(result)
}
```

### 结构化日志

在生产代码中，优先使用结构化日志（Go 1.21+ 的 `slog`，或 `log/slog` 兼容库）而非 `log.Printf`：

```go
// 好：结构化字段可被机器解析
slog.Error("fetch failed", "id", id, "err", err)

// 避免：非结构化的字符串插值
log.Printf("fetch failed for %s: %v", id, err)
```

### 日志级别

| 级别 | 使用场景 |
|------|---------|
| Error | 需要关注的可操作故障 |
| Warn  | 不需要立即处理的降级行为 |
| Info  | 关键生命周期事件（启动、关闭、配置加载） |
| Debug | 开发期间有用的诊断细节 |