结构化错误

import { createError } from 'evlog'

throw createError({
  code: 'PAYMENT_DECLINED',
  message: '支付失败',
  status: 402,
  why: '发卡行拒绝（余额不足）',
  fix: '尝试其他支付方式或联系你的银行',
  link: 'https://docs.example.com/payments/declined',
})

{
  "statusCode": 402,
  "message": "支付失败",
  "data": {
    "code": "PAYMENT_DECLINED",
    "why": "发卡行拒绝（余额不足）",
    "fix": "尝试其他支付方式或联系你的银行",
    "link": "https://docs.example.com/payments/declined"
  }
}

import { createError } from 'evlog'

throw createError({
  message: '用户未找到',
  status: 404,
})

{
  "statusCode": 404,
  "message": "用户未找到"
}

import { createError } from 'evlog'

throw createError({
  code: 'PAYMENT_DECLINED',
  message: '支付失败',
  status: 402,
  why: '卡片被发卡行拒绝',
  fix: '请尝试其他支付方式',
  link: 'https://docs.example.com/payments/declined',
})

{
  "statusCode": 402,
  "message": "支付失败",
  "data": {
    "code": "PAYMENT_DECLINED",
    "why": "卡片被发卡行拒绝",
    "fix": "请尝试其他支付方式",
    "link": "https://docs.example.com/payments/declined"
  }
}

import { createError } from 'evlog'

throw createError({
  code: 'PAYMENT_DECLINED',
  message: 'Card declined',
  status: 402,
  why: '发卡行拒绝了该扣款',
  fix: '请客户使用另一张卡',
  link: 'https://docs.example.com/payments/declined',
})

ERROR [checkout] POST /api/checkout 402 in 123ms
  ├─ error: 卡被拒绝
  │     at server/api/checkout.post.ts:42
  │   ❯ 42 ┃ throw createError({ code: 'PAYMENT_DECLINED', ... })
  │     Why: 发卡行拒绝了该扣款
  │     Fix: 请客户使用另一张卡
  │     More: https://docs.example.com/payments/declined
  │     stack (3 frames hidden in node_modules)
  ├─ user: id=1 plan=pro
  └─ cart: items=3 total=9999

import { parseError } from 'evlog'

try {
  await $fetch('/api/checkout', { method: 'POST', body: cart })
} catch (err) {
  const error = parseError(err)

  console.log(error.message)  // "Payment failed"
  console.log(error.status)   // 402
  console.log(error.code)     // "PAYMENT_DECLINED"
  console.log(error.why)      // "Card declined"
  console.log(error.fix)      // "Try another card"
}

import { parseError } from 'evlog'

const toast = useToast()

try {
  await $fetch('/api/checkout', { method: 'POST', body: cart })
} catch (err) {
  const error = parseError(err)

  toast.add({
    title: error.message,
    description: error.why,
    color: 'error',
    actions: error.link
      ? [{ label: '了解更多', onClick: () => window.open(error.link) }]
      : undefined,
  })
}

// 客户端错误 - 用户可以修复
throw createError({
  message: '无效的电子邮件格式',
  status: 400,
  fix: '请输入有效的电子邮件地址',
})

// 需要身份验证
throw createError({
  message: '请登录后继续',
  status: 401,
  fix: '登录您的账户',
  link: '/login',
})

// 资源未找到
throw createError({
  message: '未找到订单',
  status: 404,
})

// 服务器错误 - 不是用户的错
throw createError({
  message: '出现了问题',
  status: 500,
  why: '数据库连接超时',
  // 不提供 'fix' - 用户无法修复服务器错误
})

// 无帮助的修复方案
throw createError({
  message: '上传失败',
  fix: '重试',
})

// 可操作的修复方案
throw createError({
  message: '上传失败',
  status: 413,
  why: '文件超过最大大小（10MB）',
  fix: '在上传前减小文件大小或压缩图片',
  link: '/docs/upload-limits',
})

import { defineErrorCatalog } from 'evlog'

export const billingErrors = defineErrorCatalog('billing', {
  CART_EMPTY: {
    status: 400,
    message: '购物车为空',
  },
  PAYMENT_DECLINED: {
    status: 402,
    message: '银行卡被拒绝',
    why: '发卡机构拒绝了该扣款',
    fix: '请尝试其他支付方式',
    link: 'https://docs.example.com/errors/billing.payment_declined',
  },
  INSUFFICIENT_FUNDS: {
    status: 402,
    message: ({ available, required }: { available: number, required: number }) =>
      `余额不足：可用 $${available}，需要 $${required}`,
    fix: '充值后重试',
  },
})

import { billingErrors } from '~/errors/billing'

export default defineEventHandler(async (event) => {
  const cart = await getCart(event)

  if (!cart.items.length) throw billingErrors.CART_EMPTY()

  try {
    await stripe.charge(cart.total)
  }
  catch (e) {
    if (e.code === 'card_declined') throw billingErrors.PAYMENT_DECLINED({ cause: e })
    if (e.code === 'insufficient_funds') {
      throw billingErrors.INSUFFICIENT_FUNDS({
        available: e.balance,
        required: cart.total,
        cause: e,
      })
    }
    throw e
  }
})

import type { billingErrors } from './billing'
import type { authErrors }    from './auth'

declare module 'evlog' {
  interface RegisteredErrorCatalogs {
    billing: typeof billingErrors
    auth:    typeof authErrors
  }
}

// createError 会对已注册的 code 提供自动补全（也仍然接受临时字符串）
throw createError({
  code: 'billing.PAYMENT_DECLINED', // ← 自动补全，拼写错误会触发 TS 报错
  message: '银行卡被拒绝',
  status: 402,
})

// parseError().code 的类型是所有已注册 code 的联合类型
const err = parseError(caught)
if (err.code === 'billing.PAYMENT_DECLINED') retry()
//                ↑ 自动补全，重构安全