error-handling-patterns

Error Handling Patterns Skill — 错误处理跨语言

何时使用

• 设计公共库 / SDK 的错误 API
• 调试"日志写了但堆栈没了"/ "错误吞了没人知道"
• 跨服务调用错误传递（HTTP / gRPC）
• 决定何时 throw / 何时返回 error / 何时 panic
• 重试 / 熔断 / 降级策略

一、错误的两个维度

维度	取值
方向	上游传来 / 自家产生 / 下游返回
可恢复性	可重试（瞬时） / 不可重试（永久） / 灾难（停服）

              | 可重试        | 不可重试       | 灾难
--------------|---------------|----------------|----------
用户输入错    | -             | 400/422 显示   | -
认证失败      | -             | 401 引导登录   | -
权限不足      | -             | 403 提示       | -
不存在        | -             | 404 提示       | -
冲突          | (有时可)      | 409 让用户改   | -
限流          | 重试退避      | -              | -
依赖超时      | 重试 1-2 次   | 降级           | -
依赖 5xx      | 重试退避      | 降级           | -
DB 死锁       | 立即重试      | -              | -
DB 连不上     | 重试退避      | -              | 启动失败 panic
代码 bug      | -             | 500 + 告警     | -
OOM           | -             | -              | crash + restart

二、四大流派

1. Exception（Java / C# / Python / Ruby / JS）

try {
  const user = await db.findUser(id)
  if (!user) throw new NotFoundError('user', id)
  return user
} catch (e) {
  if (e instanceof NotFoundError) return null
  throw e   // rethrow 未知错误
}

优点：调用栈自动展开 / 不污染正常路径 缺点：函数签名隐藏失败可能 / 容易吞噬 / 性能（构造 stack）

2. Error Value（Go）

user, err := db.FindUser(id)
if err != nil {
    if errors.Is(err, sql.ErrNoRows) { return nil, nil }
    return nil, fmt.Errorf("db.FindUser: %w", err)   // wrap
}
return user, nil

优点：错误是显式返回值 / 不会忘记处理 缺点：样板代码多 / 容易 if err != nil { return err } 丢失上下文

3. Result/Either（Rust / Haskell / Scala / 现代 TS）

fn find_user(id: u64) -> Result<User, FindError> {
    db.find_user(id).map_err(FindError::DbError)
}

match find_user(123) {
    Ok(user) => println!("{}", user.name),
    Err(FindError::DbError(e)) => log::error!("db: {}", e),
    Err(FindError::NotFound) => println!("not found"),
}

// TS / fp-ts / neverthrow
import { Result, ok, err } from 'neverthrow'

function findUser(id: number): Result<User, FindError> {
  return db.findUser(id).match(
    user => user ? ok(user) : err({ kind: 'not_found' }),
    e => err({ kind: 'db_error', cause: e })
  )
}