将内部错误映射为类型化的接口错误

概述

只有当错误结构化且稳定时，客户端才能正确应对。一个小型分类加一个集中映射器即可保持状态码一致、隐藏内部细节，并给支持人员一个可追溯的引用 ID。

关键步骤

1. 定义携带稳定错误码、HTTP 状态与安全信息的领域错误类。
2. 集中捕获错误，并把已知类型映射为对应状态与响应体。
3. 未知错误映射为通用 500，并带引用 ID 记录真实原因。
4. 返回请求引用 ID，便于支持人员定位日志。

验证

• 每种领域错误映射到有文档的错误码与状态。
• 未知错误返回 500 且不泄露细节。
• 每个 500 响应都包含引用 ID。
• 处理函数中不含手写响应格式。

注意事项

• 只有当处理函数抛出领域错误而非通用错误时分类才有用，需在评审中强制。
• 映射无法解决需求歧义，选择正确状态码仍是设计决策。

适用范围

本条目围绕「将内部错误映射为类型化的接口错误」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

class AppError extends Error {
  constructor(code, status, message) {
    super(message); this.code = code; this.status = status;
  }
}
if (err instanceof AppError) send(res, err.status, { error: { code: err.code, message: err.message } });