# 错误处理和可观察性 ### 何时加载 * **触发器**：Try/catch 模式、重试逻辑、错误响应、断路器、结构化日志记录 * **跳过** ：当前任务中不涉及错误处理或可观察性 ## 错误处理工作流程复制此清单并跟踪进度：错误处理进度： - [ ] 步骤 1：定义错误分类（类别和严重性） - [ ] 步骤2：分层实现错误处理 - [ ] 步骤 3：设置结构化日志记录 - [ ] 步骤 4：添加重试和断路器模式 - [ ] 步骤5：配置错误跟踪服务 - [ ] 步骤 6：定义面向用户的错误消息 - [ ] 步骤 7：根据反模式清单进行验证 ## 按语言划分的错误处理模式 ### JavaScript / TypeScript // 自定义错误层次结构类 AppError 扩展错误 { 构造函数（消息：字符串，公共状态代码：数量 = 500，公共代码：string =“INTERNAL_ERROR”，公共 isOperational: 布尔值 = true, ）{ 超级（消息）； this.name = this.constructor.name; } } 类 NotFoundError 扩展 AppError { 构造函数（资源：字符串，id：字符串）{ super(`未找到 ID 为 ${id} 的 ${resource}`, 404, "NOT_FOUND"); } } 类 ValidationError 扩展 AppError { 构造函数（公共错误：记录<字符串，字符串[]>）{ super("验证失败", 400, "VALIDATION_ERROR"); } } // 错误：默默地吞下错误尝试{ 等待保存用户（数据）； } 捕获 (e) { // 这里什么都没有——bug永远隐藏 } // 错误：在没有上下文的情况下捕获并重新抛出尝试{ 等待保存用户（数据）； } 捕获 (e) { 扔 e； // 无意义的尝试/捕获 } // 正确：添加上下文、处理或传播尝试{ 等待保存用户（数据）； } 捕获（错误）{ if (验证错误的错误实例) { 返回 res.status(400).json({ 错误: error.errors }); } logger.error("保存用户失败", { error, userId: data.id }); throw new AppError("无法保存用户", 500, "USER_SAVE_FAILED"); } ### Express 全局错误处理程序 // 集中式错误处理中间件（必须有 4 个参数） app.use((err: 错误，req: 请求，res: 响应，下一个：NextFunction) => { if (err 实例应用程序错误) { logger.warn("操作错误", { 代码：错误代码，状态代码：err.statusCode，路径：请求路径， }); 返回 res.status(err.statusCode).json({ 错误：{ 代码：err.code，消息：err.message }， }); } // 意外错误——这些是错误 logger.error("意外错误", { 错误：错误消息，堆栈：错误堆栈，路径：请求路径， }); res.status(500).json({ 错误：{代码：“INTERNAL_ERROR”，消息：“发生意外错误”}， }); }); ###Python # 自定义异常层次结构类应用程序错误（异常）： def __init__(self, 消息: str, 代码: str = "INTERNAL_ERROR", 状态: int = 500): self.message = 消息 self.code = 代码 self.status = 状态超级().__init__(消息) 类NotFoundError（应用程序错误）： def __init__(self, 资源: str, id: str): super().__init__(f"{资源} {id} 未找到", "NOT_FOUND", 404) 类验证错误（应用程序错误）： def __init__(self, 错误: dict[str, list[str]]): self.errors = 错误 super().__init__("验证失败", "VALIDATION_ERROR", 400) # 错误：除了尝试：结果=过程（数据） except: # 也捕获 SystemExit、KeyboardInterrupt！通过 # 正确：特定的异常，正确的日志记录尝试：结果=过程（数据）除了 ValidationError 为 e： logger.warning("验证失败", extra={"errors": e.errors}) 提高除了数据库错误为 e： logger.error("处理过程中数据库错误", exc_info=True) 从 e 引发 AppError("处理失败", "PROCESS_FAILED") ### 去 // 定义哨兵错误和自定义类型变量（ ErrNotFound = error.New("找不到资源") ErrUnauthorized = error.New("未经授权") ）类型 ValidationError 结构体 { 字段字符串消息字符串 } func (e *ValidationError) Error() 字符串 { return fmt.Sprintf("验证：%s - %s", e.Field, e.Message) } // 错误：忽略错误 data, _ := json.Marshal(user) // 错误默默地丢弃 // 错误：仅返回错误字符串如果错误！= nil { return fmt.Errorf("failed: %s", err.Error()) // 丢失错误链 } // 正确：用上下文包装错误如果错误！= nil { return fmt.Errorf("保存用户 %s: %w", user.ID, err) // %w 保留链 } // 正确：检查错误类型如果错误。Is(err, ErrNotFound) { http.Error(w, "未找到", http.StatusNotFound) 返回 } var valErr *验证错误如果错误。As(err, &valErr) { http.Error(w, valErr.Error(), http.StatusBadRequest) 返回 } ## 结构化日志记录 ### JSON 日志格式 // 错误：非结构化字符串日志 console.log(`用户 ${userId} 在 ${new Date()} 创建了订单 ${orderId}`); // 无法解析、过滤或聚合 // 正确：结构化 JSON 日志从“pino”导入pino；常量记录器 = pino({ 级别：process.env.LOG_LEVEL || “信息”，格式化程序：{ 级别：（标签）=>（{级别：标签}）， }, 编辑：[“req.headers.authorization”，“密码”，“ssn”]， }); 记录器.info({ 事件：“订单已创建”，用户ID：“123”，订单ID：“456”，金额：99.99，货币：“美元”， }); // 输出：{"level":"info","event":"order_created","userId":"123","orderId":"456",...} ### 相关 ID // 跨请求传播关联 ID 的中间件从“加密货币”导入 { randomUUID } ；从“async_hooks”导入{AsyncLocalStorage}； const asyncStorage = new AsyncLocalStorage<{correlationId: string }>(); app.use((req, res, 下一个) => { 常量相关 ID = (req.headers["x-correlation-id"] 作为字符串) ||随机UUID(); res.setHeader("x-correlation-id",correlationId); asyncStorage.run({ correlationId }, () => next()); }); // 记录器自动包含相关 ID 函数 getLogger() { const store = asyncStorage.getStore(); return logger.child({correlationId: store?.correlationId }); } // 在任何处理程序或服务中使用 const log = getLogger(); log.info({ 事件: " payment_processed", 金额: 50 }); // 输出自动包含correlationId ### 日志级别指南 TRACE：非常详细（循环迭代、变量值）——仅限开发 DEBUG：诊断信息（函数进入/退出、状态变化）——dev/staging 信息：正常操作（请求已处理，作业已完成）--所有环境警告：意外但可恢复（重试成功，使用回退）错误：操作失败（未处理的异常，服务关闭）致命：应用程序无法继续（缺少配置，数据库无法访问）生产默认值：INFO 从不记录：密码、令牌、PII、信用卡、完整请求正文 ## 错误边界和优雅降级 ### React 错误边界类 ErrorBoundary 扩展了 React.Component< { 后备：React.ReactNode;孩子：React.ReactNode }, { 已错误：布尔值；错误？：错误} > { 状态 = { hasError: false, 错误: 未定义 }; 静态 getDerivedStateFromError(错误：错误) { 返回 { hasError: true, 错误 }; } componentDidCatch(错误：错误，信息：React.ErrorInfo) { logger.error("反应错误边界捕获错误", { 错误：错误消息，组件栈：info.componentStack， }); } 渲染（）{ 返回 this.state.hasError ？ this.props.fallback : this.props.children; } } // 用法：独立包装各节仪表板不可用

}> <仪表板/> 侧边栏不可用

}> <侧边栏/> ### 服务降级 // 优雅降级：当服务关闭时提供过时的数据异步函数 getProductRecommendations(userId: string) { 尝试{ 返回等待推荐服务.get(userId); } 捕获（错误）{ logger.warn("推荐服务不可用，正在使用后备", { 用户 ID, 错误：错误消息， }); 返回 getCachedRecommendations(userId) || getDefaultRecommendations(); } } ## 重试模式 ### 指数退避异步函数 withRetry( fn: () => Promise, 选项：{ 最大重试次数？：数量；基本延迟？：数字；最大延迟？：数字；重试？：（错误：错误）=> 布尔值； } = {}, ): 承诺 { 常量{ 最大重试次数 = 3, 基本延迟 = 1000, 最大延迟 = 30000, 重试， } = 选项； for (让尝试 = 0;尝试 <= maxRetries;尝试++) { 尝试{ 返回等待 fn(); } 捕获（错误）{ if (attempt === maxRetries) 抛出错误； if (retryOn && !retryOn(error as Error)) 抛出错误；常量延迟 = Math.min( baseDelay * 2 ** 尝试 + Math.random() * 1000, 最大延迟, ）； logger.warn("重试操作", { attempts: 尝试 + 1, 延迟 }); 等待新的 Promise((r) => setTimeout(r, 延迟)); } } 抛出新错误（“无法访问”）； } // 用法：仅在发生暂时性错误时重试 const data = wait withRetry(() => fetch("https://api.example.com/data"), { 重试: (err) => err.message.includes("ECONNRESET"), }); ### 断路器断路器类{ 私人失败= 0；私人最后失败= 0; 私人状态：“关闭”| “开放”| “半开”=“关闭”；构造函数（私有阈值：数量= 5，私人重置超时：数量= 60000，）{} 异步执行 (fn: () => Promise, 后备？: () => T): Promise { if (this.state === "打开") { if (Date.now() - this.lastFailure > this.resetTimeout) { this.state = "半开"; } 否则{ 如果（后备）返回后备（）； throw new Error("断路器打开"); } } 尝试{ 常量结果 = 等待 fn(); this.失败= 0； this.state = "关闭"; 返回结果； } 捕获（错误）{ this.失败++； this.lastFailure = Date.now(); if (this.failures >= this.threshold) this.state = "open"; 如果（后备）返回后备（）；抛出错误； } } } // 用法：5次失败后跳闸，30秒后复位 const paymentCircuit = new CircuitBreaker(5, 30000); const 结果 = 等待 paymentCircuit.execute( () => paymentService.charge(金额), () => ({ queued: true, message: "付款将很快处理" }), ）； ## 错误跟踪集成 ### 哨兵设置从“@sentry/node”导入*作为哨兵； Sentry.init({ dsn: process.env.SENTRY_DSN, 环境：process.env.NODE_ENV， tracesSampleRate：process.env.NODE_ENV ===“生产”？ 0.1：1.0，发送之前（事件）{ // 清理敏感数据 if (event.request?.headers) 删除 event.request.headers["授权"]; 返回事件； }, }); Sentry.setUser({ id: user.id, email: user.email }); Sentry.captureException(错误, { 标签：{子系统：“付款”，提供商：“条纹”}，额外：{ orderId, 金额 }, }); ## 面向用户的错误与内部错误 // 将内部错误映射到用户友好的消息 const USER_MESSAGES：记录<字符串，字符串> = { VALIDATION_ERROR: "请检查您的输入并重试。", NOT_FOUND: "找不到所请求的资源。", RATE_LIMITED: "请求过多。请稍等。", PAYMENT_FAILED: "付款无法处理。请尝试其他方法。", INTERNAL_ERROR: "出了点问题。请稍后再试。", }; 函数 toUserResponse（错误：AppError）{ 返回{ 错误：{ 代码：错误代码，消息： USER_MESSAGES[错误代码] || USER_MESSAGES["内部错误"], }, }; } // 错误：向用户公开内部详细信息 res.status(500).json({ 错误：'QueryFailedError：关系“用户”不存在'，堆栈：错误.堆栈， }); // 正确：给用户的通用消息，日志中的完整详细信息 logger.error("数据库查询失败", { 错误：错误消息，堆栈：错误.堆栈，查询， }); res.status(500).json(toUserResponse(new AppError("数据库错误", 500))); ## 常见反模式总结避免这样做 ------------------------------------------------------------------- 空 catch 块记录并处理或重新抛出 Python 中的裸露 ` except:` 捕获特定异常 console.log 用于生产结构化记录器（pino、winston）记录密码/令牌编辑敏感字段无退避重试带抖动的指数退避重试所有错误仅重试暂时/网络错误无断路器外部呼叫断路器向用户公开堆栈跟踪通用用户消息、详细日志无关联 ID 跨服务传播关联 ID 每个操作都有一个巨大的 try/catch 精细错误处理记录紧密循环内的日志摘要/聚合 React 中没有错误边界单独包裹独立部分

错误处理

包含技能