技能使用指南

error-handling（错误处理Skill）Skill 有什么用？

错误处理Skill（error-handling）为前后端提供统一的错误处理方案：自定义错误类、错误处理中间件、React 错误边界、异步请求封装与日志分级指南，帮助团队统一错误码与响应结构，减少联调与排查成本。本文详解安装步骤、使用方法、竞品对比与典型场景，附常见问题解答，助你快速落地错误处理规范。

错误处理Skillerror-handling
8 个章节 约 16 分钟阅读 AI 智能生成

错误处理Skill：让前后端错误处理从“各写各的”变成“一套标准”

  • 技能定位明确：错误处理Skill（error-handling）专注一件事——在整个应用中实现一致、信息丰富的错误处理，而不是泛泛地生成业务代码。
  • 覆盖前后端全链路：后端提供自定义错误类与错误处理中间件模板，前端提供错误边界与异步请求封装，另有日志级别指南贯穿始终。
  • 触发方式自然：当你在 AI 编程助手里提到“加 try-catch”“加错误边界”“写自定义错误类”时，该技能会被唤起，直接给出结构化方案。
  • 适合团队协作场景：统一错误码、统一响应结构、统一日志分级，能显著降低多人协作时的沟通成本和排查成本。
  • 上手门槛低：无需额外学习新语法，产出的是 TypeScript / React 生态的常见写法，可直接粘贴到项目中按需调整。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息：

项目 内容
中文名 错误处理Skill
英文名 error-handling
技能ID 11837
核心描述 在整个应用程序中实现一致的错误处理，在添加 try-catch 块、错误边界或自定义错误类时使用

它解决什么问题？

错误处理是典型“人人都知道重要、但人人都按自己习惯写”的环节。同一个项目里，有人 throw new Error('xxx')，有人返回 { success: false }，有人直接把数据库报错原样抛给前端；前端有人写了错误边界，有人在每个组件里写 try-catch，异步请求失败后页面要么白屏要么静默失败。结果是：错误码不统一、响应结构不统一、日志级别不统一，线上排查时只能靠猜。

错误处理Skill 的价值在于：它把“错误处理”这件事从个人习惯升级为一份可复用的工程约定，包含错误类体系、中间件、错误边界、异步封装和日志分级五个部分，让 AI 助手在你的项目里按同一套标准产出代码。

一键安装思路与步骤：

  1. 确认前提：你使用的 AI 编程助手 / 开发平台需要支持“技能（Skill）”机制，即能够加载外部技能包来增强特定领域的输出质量。具体支持的平台与版本要求，以官方说明为准。
  2. 找到技能：在技能市场、技能库或插件面板中搜索英文名 error-handling，或直接按技能ID 11837 检索。具体的搜索入口与操作路径，以官方说明为准。
  3. 执行安装：点击安装 / 添加到我的技能 / 启用，通常为一步式操作，无需手动配置依赖。若平台要求登录账号或授权工作区，按提示完成即可。
  4. 验证是否生效：安装后新开一个对话，输入类似“帮我给这个 Express 接口加一套统一的错误处理，包含自定义错误类和中间件”的请求。如果返回结果中出现了 AppError 基类、带 code / statusCode / details 字段的结构化错误、以及错误处理中间件形态的代码，说明技能已正常加载。
  5. 验证失败怎么办：先检查技能是否处于“启用”状态，再确认当前对话是否在已启用该技能的工作区中；如仍不生效，可重新安装或参考官方文档的技能加载说明。

需要说明的是：本技能的详情内容中并未提供具体的安装命令行、下载地址或价格信息，上述步骤为通用流程，实际命令与入口请以官方说明为准。

2. 该技能的主要功能和特点

能做什么：

  • 自定义错误类体系：提供 AppError 基类模板，内置 code（错误码）、message（信息）、statusCode（HTTP 状态码，默认 500）、details（附加详情）四个字段，并派生出 ValidationError（校验失败，400）和 NotFoundError（资源不存在，404）两个常用子类。
  • 后端错误处理中间件：提供统一的错误捕获中间件模板，先记录日志，再判断是否为 AppError 实例：是则按错误自带的 statusCode 和 code 返回结构化响应；否则统一兜底为 INTERNAL_ERROR，对外只暴露“发生意外错误”，避免泄露内部实现细节。
  • 前端错误边界：提供 React 类组件形态的 ErrorBoundary，通过 getDerivedStateFromError 切换降级 UI，通过 componentDidCatch 上报错误与组件栈信息，并渲染 ErrorFallback 组件，支持通过 onReset 重置状态恢复渲染。
  • 异步错误处理封装：提供 fetchWithError 泛型函数模板，在 response.ok 为假时解析响应体并抛出 ApiError，把“HTTP 层失败”转换成“业务层可捕获的异常”，避免每个调用点重复写判断。
  • 日志级别指南：以表格形式明确 error / warn / info / debug 四个级别的用途边界——异常与失败用 error，可恢复问题用 warn，重要事件用 info，开发信息用 debug。

和普通工具比强在哪：

  • 一致性优先：普通代码生成工具往往“你要什么给什么”，十次请求可能给出十种错误处理风格；该技能的输出遵循同一套错误类与响应结构约定。
  • 前后端打通：多数方案只解决后端或只解决前端，该技能同时给出两端模板，错误码可以在前后端对齐。
  • 细节到位：中间件里包含“未识别错误不暴露内部信息”的兜底逻辑，错误边界里包含重置恢复逻辑，这些都是实际项目中容易漏掉的点。
  • 自带可观测性视角：日志分级指南让错误处理不只停留在“catch 住”，而是与日志体系衔接。

3. 如何使用该技能？

以下为推荐的分步使用流程，示例基于技能详情中给出的 TypeScript / React 生态模板，其他语言可按同样思路迁移。

步骤 1：安装并启用技能 按第 1 部分的步骤完成安装，确保技能处于启用状态。

步骤 2：用自然语言描述场景，触发技能 技能描述中明确了触发时机：添加 try-catch 块、错误边界或自定义错误类时使用。因此请求中带上这些关键词，效果最好。

输入示例：

“我有一个 Express + TypeScript 的后端项目，现在错误返回格式乱七八糟，帮我建一套统一的错误类和一个全局错误处理中间件。”

步骤 3：落地自定义错误类 技能会给出类似下面的结构（节选）：

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

输出说明：你会得到 AppError 基类，以及继承它的 ValidationError（固定 VALIDATION_ERROR / 400）和 NotFoundError（固定 NOT_FOUND / 404，消息自动拼接为“资源名 + not found”）。把这些类放到项目的公共错误目录中，业务代码只抛这些子类，不再直接抛原生 Error。

步骤 4：接入后端错误处理中间件 技能会给出形如 errorHandler(err, req, res, next) 的中间件：先 logger.error(err) 记录日志；若 err instanceof AppError，按 err.statusCode 返回 { error: { code, message, details } }；否则返回 500 与 INTERNAL_ERROR，消息为固定文案“发生意外错误”。把它注册为框架的最后一个错误中间件即可。

步骤 5：为前端加错误边界 在 React 应用中，用技能给出的 ErrorBoundary 包裹路由或页面级组件。输出说明：出错时渲染 ErrorFallback 降级界面，用户点击重试时通过 onReset 把 hasError 置回 false，从而恢复渲染；同时在 componentDidCatch 中把错误与组件信息上报到日志系统。

步骤 6：统一异步请求的错误出口 把散落在各处的 fetch 调用替换为技能给出的 fetchWithError<T>(url) 泛型封装：响应不 OK 时解析错误体并抛出 ApiError，调用方只需处理一种异常类型。

步骤 7：按日志分级规范记录 对照技能提供的日志级别表统一项目中日志调用：异常与失败用 error，可恢复问题用 warn，重要事件用 info，开发期信息用 debug，避免全项目只有 console.log。

步骤 8：自查 检查三点：业务代码是否只抛自定义错误子类、所有接口错误响应结构是否一致、前端是否存在未包裹错误边界的关键页面。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
错误处理Skill（error-handling） AI 技能，提供一致的错误处理代码方案 自定义错误类、后端中间件、前端错误边界、异步封装、日志分级指南 低：在支持技能的平台中一键启用即可 需要快速建立统一错误规范的前后端项目、团队规范落地 优势：前后端一套标准、生成即可用、自带兜底与重置逻辑；不足：模板以 TypeScript/React 生态为主，其他技术栈需自行适配
通用大模型直接生成 无专用技能的通用代码生成 按提示词即时生成任意错误处理代码 低：直接对话即可 一次性、零散的错误处理需求 优势：灵活；不足：风格不稳定、缺少统一错误码体系、容易漏掉安全兜底细节
静态检查工具（如 ESLint 类规则） 代码规范检查 检查未捕获异常、未使用 catch 等问题并报错 中：需配置规则集与构建流程 提交前拦截低级错误 优势：自动化、可强制；不足：只“发现问题”，不“给出结构方案”，无法生成错误类体系
错误监控平台（如 Sentry 类服务） 线上错误采集与告警 运行时异常捕获、聚合、告警与堆栈追踪 中高：需接入 SDK、配置项目与采样策略 线上问题发现与追踪 优势：可观测性强；不足：偏事后监控，不负责代码层的错误处理规范，两者互补而非替代
框架内置异常机制 框架自带的错误处理能力 如统一异常过滤器、默认错误响应 低：框架自带 标准化框架项目 优势：零成本；不足：需要团队自己约定错误码与业务错误类，跨前后端仍不统一

5. 该技能的典型应用场景与实际体验情况

场景一：后端 API 统一错误响应

  • 角色与痛点：后端开发者维护十几个接口，每个接口的失败返回结构都不一样，前端要写多套兼容逻辑。
  • 使用方式：让技能生成错误类与全局中间件并注册，业务代码改为抛 ValidationError / NotFoundError。
  • 实际体验：上手几乎零成本，产出代码可直接落库；注意要先确定自己的错误码命名规范，模板里的 VALIDATION_ERROR / NOT_FOUND 只是示例，需要与团队约定对齐。

场景二：前端页面白屏兜底

  • 角色与痛点：React 项目中某个子组件渲染报错导致整页白屏，用户只能刷新。
  • 使用方式：用技能给出的 ErrorBoundary 包裹页面级或路由级组件，配合 ErrorFallback 与重置回调。
  • 实际体验：降级 UI 与恢复逻辑一次生成，体验提升明显；注意事项是错误边界只能捕获渲染期错误，事件处理与异步代码中的错误仍需配合 fetchWithError 这类封装。

场景三：前后端错误码联调对齐

  • 角色与痛点：联调时前端收到的错误信息是数据库原始报错，既看不懂也不安全。
  • 使用方式：用技能统一两端的错误结构，后端只返回 code / message / details，前端按 code 做分支处理。
  • 实际体验：联调沟通成本明显下降；注意 details 字段要控制内容，避免把敏感信息透出给客户端。

场景四：新人代码评审与规范落地

  • 角色与痛点：团队新成员不了解错误处理约定，代码评审反复指出同类问题。
  • 使用方式：把技能产出的模板作为团队参考实现，评审时直接对照。
  • 实际体验：规范从“口口相传”变成“有模板可依”；建议把错误类文件纳入代码库公共目录，形成长期资产。

整体上手难度：低。技能输出的是可直接阅读和修改的代码模板，不需要学习新工具链；真正的成本在于团队内部就错误码体系达成一致。

6. 该技能能为用户带来的价值

  • 提升效率：错误类体系、中间件、错误边界、异步封装这些“每次都要重写一遍”的样板代码，可以由技能一次性产出，开发者把精力放在业务逻辑上。
  • 降低门槛：对不熟悉错误处理最佳实践的同学，技能直接给出了包含安全兜底（不暴露内部错误）、恢复机制（错误边界重置）、日志分级在内的完整参考实现，相当于随身带一份可执行的最佳实践清单。
  • 减少返工与排查成本：统一错误码与响应结构后，前端无需为每个接口写兼容逻辑，线上排查时也能凭 code 快速定位问题来源。
  • 长期价值：错误处理规范一旦落地，就会成为项目的公共资产——新接口默认复用同一套错误类，新页面默认包裹同一套错误边界，团队规模扩大时规范不会走形。
  • 可量化方向：可以从“重复编写错误处理代码的次数”“错误响应结构不一致的接口数量”“因错误信息不明确导致的排查时长”三个维度衡量使用前后的变化。

7. 常见问题 FAQ

Q1：错误处理Skill 怎么安装？需要收费吗？ 在支持技能机制的平台中，通过技能市场或技能库搜索英文名 error-handling 或技能ID 11837，一键添加并启用即可，通常无需手动配置依赖。具体入口、是否收费及计费方式，以官方说明为准；技能详情本身未提供价格信息。

Q2：它支持哪些语言和框架？ 技能详情中给出的模板基于 TypeScript，后端中间件形态接近 Express 风格的 (err, req, res, next)，前端为 React 类组件形式的错误边界。其他语言或框架（如 Java、Go、Vue 等）可以参照其错误类分层、统一响应结构、日志分级的思路自行迁移，但生成结果需要人工校验。

Q3：它和错误监控平台、ESLint 这类工具冲突吗？ 不冲突，定位不同。该技能解决的是“代码层怎么写”，静态检查工具解决“写得对不对”，监控平台解决“线上出了什么问题”。三者组合使用效果最好：技能统一规范，检查工具守住底线，监控平台兜住线上。

Q4：适合谁用？ 适合正在搭建或重构前后端错误处理规范的后端/前端开发者、需要统一团队代码风格的 Tech Lead，以及希望减少联调摩擦的全栈工程师。如果只是写一次性脚本，收益相对有限。

Q5：用了它是不是就不用自己设计错误码了？ 不是。技能提供的是结构模板和示例错误码（如 VALIDATION_ERROR、NOT_FOUND），业务错误码体系仍需要团队根据自身领域设计，技能负责保证“结构一致、出口统一”。