TypeScript 错误处理：Result 模式、类型化错误与错误边界实战

预期错误（业务失败）：表单校验、用户不存在、库存不足 → Result
意外错误（系统故障）：数据库连接失败、Bug、磁盘满 → 异常
原则：能用 Result 表达的「业务分支」用 Result，
      无法预期的「系统崩溃」用异常

异常 = 「不可能/不该发生」的事（崩溃）
Result = 「可能发生」的业务分支（状态）
好的 API：业务分支显式返回，真正异常才 throw

// 判别联合定义 Result
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

// 构造辅助
export const ok = <T, E = never>(value: T): Result<T, E> => ({ ok: true, value })
export const err = <E, T = never>(error: E): Result<T, E> => ({ ok: false, error })

// 解包（收窄）
function unwrap<T, E>(r: Result<T, E>): T {
  if (r.ok) return r.value
  throw new Error(String(r.error))   // 解包失败视为 Bug
}

type UserError = 'NOT_FOUND' | 'UNAUTHORIZED'

function findUser(id: string): Result<User, UserError> {
  const user = db.get(id)
  return user ? ok(user) : err('NOT_FOUND')
}

const r = findUser('u1')
if (r.ok) {
  r.value.name    // ✅ 收窄后访问 value
} else {
  r.error         // ✅ 只能访问 error（'NOT_FOUND' | 'UNAUTHORIZED'）
}

// 让 Result 可组合
declare function map<T, E, U>(r: Result<T, E>, f: (v: T) => U): Result<U, E>
declare function flatMap<T, E, U>(
  r: Result<T, E>, f: (v: T) => Result<U, E>): Result<U, E>

const final = flatMap(
  map(findUser('u1'), u => u.name.toUpperCase()),
  name => ({ ok: true, value: `Hello ${name}` })
)
// 或者用 fp-ts / neverthrow 库（内置这些操作）

neverthrow：Result/Either 的工业实现（ok/err + 链式操作）
fp-ts    ：函数式全套（Either/Option/TaskEither）
手写     ：简单场景手写判别联合即可

type ApiError =
  | { kind: 'validation'; field: string; message: string }
  | { kind: 'auth'; reason: 'expired' | 'invalid' }
  | { kind: 'rate-limit'; retryAfter: number }
  | { kind: 'server'; code: number }

function callApi(): Result<Data, ApiError> {
  // ... 不同失败返回不同错误分支
  return err({ kind: 'validation', field: 'email', message: '格式错误' })
}

function handleError(e: ApiError): string {
  switch (e.kind) {
    case 'validation': return `${e.field}: ${e.message}`
    case 'auth':       return e.reason === 'expired' ? '登录过期' : '凭证无效'
    case 'rate-limit': return `请 ${e.retryAfter}s 后重试`
    case 'server':     return `服务异常(${e.code})`
  }
}

1. 每种错误带「自己的数据」（field/reason/retryAfter）
2. switch 穷尽 → 新增错误类型强制补处理
3. 调用点能精确分支处理（提示/重试/上报）
4. 取代「错误码 int + 猜测」

Option<T> = Some(value) | None     —— 表示「可能没有」，不是失败
Result<T,E> = Ok(value) | Err(E)   —— 表示「可能失败」，带错误

例：findUser 用户可能不存在：
  「查询失败」→ Result（校验/连接错误）
  「查不到」  → Option（正常业务，无错误信息）

type Option<T> = { tag: 'some'; value: T } | { tag: 'none' }
// 或直接用 null/undefined 语义 + 严格 null 检查

type Option<T> = { tag: 'some'; value: T } | { tag: 'none' }

function first<T>(arr: T[]): Option<T> {
  return arr.length ? { tag: 'some', value: arr[0] } : { tag: 'none' }
}

const maybe = first(['a'])
if (maybe.tag === 'some') maybe.value   // ✅ 收窄

TS 的 null/undefined + strictNullChecks 已能表达大部分可空
Option 的价值在「显式、可组合」（map/flatMap）
简单场景用 nullable 即可，复杂链式用 Option

async function fetchUser(id: string): Promise<Result<User, ApiError>> {
  try {
    const data = await http.get(`/users/${id}`)
    return ok(data)
  } catch {
    return err({ kind: 'server', code: 500 })
  }
}

const r = await fetchUser('u1')
if (r.ok) r.value.name

// 反例：async 函数内 throw → 变成 rejected promise，容易漏 catch
async function risky() { throw new Error('x') }
// 调用处若没 await+try，错误被吞或变 unhandled rejection

// 正例：边界 catch 一次，内部用 Result 传递

// 坏：并发 await 串行
const a = await fetchA(); const b = await fetchB()   // 串行
// 好：先并行
const [a, b] = await Promise.all([fetchA(), fetchB()])
// 但 Promise.all 一个 reject 全 reject → 用 allSettled 保错误可见
const results = await Promise.allSettled([fetchA(), fetchB()])

export class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly status: number,
    public readonly details?: unknown,
  ) {
    super(message)
    this.name = 'AppError'
  }
}

// 使用
throw new AppError('用户不存在', 'USER_NOT_FOUND', 404, { id })

// 判断
if (e instanceof AppError) {
  e.code   // 类型安全访问 code/status/details
}

错误码三要素：code（稳定标识）+ status（HTTP）+ details（上下文）
设计原则：
  1. code 稳定（前端 if 判断用，不随文案变）
  2. 层级：模块前缀（USER_ / PAY_ / AUTH_）
  3. 详情结构化（details 携带字段，而非拼进 message）

function callApiSafe(): Result<Data, ApiError> {
  try {
    return ok(api())
  } catch (e) {
    if (e instanceof AppError && e.code === 'RATE_LIMIT') {
      return err({ kind: 'rate-limit', retryAfter: e.details?.retryAfter ?? 60 })
    }
    return err({ kind: 'server', code: 500 })
  }
}

import { Component, type ReactNode } from 'react'

type State = { hasError: boolean; message: string }

class ErrorBoundary extends Component<{ children: ReactNode }, State> {
  state: State = { hasError: false, message: '' }

  static getDerivedStateFromError(e: Error): State {
    return { hasError: true, message: e.message }
  }

  componentDidCatch(e: Error, info: { componentStack?: string }) {
    // 上报可观测性
    reportError(e, info.componentStack)
  }

  render() {
    if (this.state.hasError) return <Fallback message={this.state.message} />
    return this.props.children
  }
}

粒度：应用级（兜底）+ 路由级（每页）+ 组件级（局部）
原则：
  1. 关键页面有边界（崩溃不至于全站白屏）
  2. 局部可降级（单个组件挂了，其余继续）
  3. 边界内提供「重试」入口

Error Boundary 捕获「渲染期」错误
不捕获：事件处理器、异步回调、SSR
这些场景用 try/catch 或 Result（事件处理里显式捕获）

function handleError(e: AppError, ctx: { requestId: string; userId: string }) {
  logger.error({
    event: 'app.error',
    code: e.code,
    status: e.status,
    requestId: ctx.requestId,
    userId: ctx.userId,
    stack: e.stack,
  })
}

业务错误（USER_NOT_FOUND）：info/warn，正常分支
系统错误（DB 连接失败）   ：error，需告警
未知错误                 ：error + 全量上报（不要静默）

按 code 聚合：看到「RATE_LIMIT 占比上升」→ 提前干预
错误签名：堆栈首几行哈希 → 同类错误归组
SLO：错误率超标 → 告警

1. 公共 API 返回值用 Result（业务分支可见）
2. 内部基础设施（DB/网络）用异常 → 边界转 Result
3. 错误码表统一维护
4. 不静默 catch：至少要 log
5. 错误信息用户可见 vs 内部可见分离