技能使用指南

error-handling（错误处理模式）Skill 是什么？

错误处理模式Skill（error-handling）让 AI 编程助手用 trySync/tryAsync 替代 try-catch，通过 Ok/Err 结果类型实现类型安全的优雅错误恢复，内置最小化包装与立即返回规范。本文详解技能功能、安装验证步骤、使用示例、竞品对比与典型场景，帮团队快速统一错误处理风格。

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

错误处理模式Skill：用 trySync / tryAsync 替代 try-catch，让错误恢复更优雅、类型更安全

  • 一句话定位：这是一个专注「优雅错误处理」的 AI 技能，它教 AI 编程助手按照 wellcrafted 的 trySync / tryAsync 模式写代码，而不是随手甩一个 try-catch 块。
  • 核心机制：把可能失败的操作包进 trySync（同步）或 tryAsync（异步），统一返回 { data, error }，错误以 Ok / Err 的 Result 形式显式呈现。
  • 最大差异点：可恢复错误直接返回 Ok(回退值) 继续跑，不可恢复错误返回 Err(...) 向上传播，错误边界清晰、类型安全，不需要靠异常满天飞。
  • 附带规范：技能内置「最小化包装原则」「立即返回模式」「何时才该扩展 try 块」等工程约定，让 AI 写出来的代码风格一致、可评审。
  • 适用人群：使用 AI 编程助手的中高级前端 / 全栈 / 桌面端开发者，尤其是做音视频、文件读写、设备权限、网络请求等「失败是常态」的场景。

一、该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息一览：

项目 内容
技能中文名 错误处理模式Skill
技能英文名 error-handling
技能ID 11878
作者 epicenter
版本 1.1

它到底解决什么问题？

传统 try-catch 有三个长期困扰开发者的问题：

  1. 类型不安全：catch (e) 里的 e 在 TypeScript 中类型模糊，调用方无法从函数签名看出「这里会失败」，错误被隐式吞掉。
  2. 错误边界模糊：一个 try 块里塞了十几行代码，报错后很难判断究竟是哪一步炸的，错误信息只能写成「某些操作失败」这种没用的描述。
  3. 控制流嵌套：想处理多个可能失败的操作，很容易写出四层 if (!error) { if (!error) { ... } } 的箭头形代码。

这个技能让 AI 助手在生成或重构错误处理代码时，统一改用 wellcrafted 提供的 trySync / tryAsync 与 Ok / Err 的 Result 模式，从「抛异常」转向「返回值即结果」。

一键安装思路与步骤：

  1. 确认前提：你的 AI 编程助手需要支持「技能（Skill）」机制，即能够加载 SKILL.md 描述文件，并在合适的对话上下文里自动启用。若客户端不支持技能机制，则只能手动把技能内容作为提示词粘贴使用。
  2. 找到技能入口：在客户端的技能市场 / 技能管理面板中搜索技能中文名「错误处理模式」或英文名 error-handling，也可通过技能ID 11878 定位（具体入口路径、命令与安装包地址以官方说明为准）。
  3. 一键安装：点击安装 / 启用，客户端会把技能内容写入本地技能目录；部分客户端支持导入技能包文件，具体方式以官方说明为准。
  4. 触发验证：安装后在对话中提一个真实需求，例如「帮我用 tryAsync 重写这段读取文件的代码，读不到就用默认内容」。如果 AI 输出了 import { trySync, tryAsync, Ok, Err } from 'wellcrafted/result'，并且 catch 里返回 Ok('默认内容') 而不是空的 catch {}，说明技能已生效。
  5. 反向验证：如果 AI 仍然只给你裸 try-catch、或者在 catch 里只 console.error 一下就完事，说明技能未被加载，需要检查客户端是否开启了技能自动匹配，或手动在对话开头声明使用该技能。

二、该技能的主要功能和特点

  • 双函数分流：同步操作用 trySync（立即返回，无需 await），异步操作用 tryAsync（返回 Promise，必须 await）。技能会主动提醒 AI 遵守这个区分，避免混用。
  • 统一的解构形态：两者都返回可解构的结果对象，写法固定为 const { data, error } = ...，读代码时一眼就能看出失败路径在哪里。
  • 优雅恢复能力：catch 回调里可以直接 return Ok(回退值)，把「失败」转成「降级成功」，例如配置解析失败就用默认配置、麦克风占用失败就提示用户重选设备。
  • 显式错误传播：需要向上抛出时，返回 Err(...) 或自定义的 ServiceErr({ message, cause })，让错误带上业务语义与原始 cause。
  • 关键防坑规则：技能特别强调——从结果中解构出来的 error 是原始错误值，不是 Result，必须用 Err(error) 包装后再返回；只有直接返回整个结果对象时才可以 return userResult。这是新手最容易写错的一步，技能把它列为硬性规则。
  • 最小化包装原则：只包住「真正可能失败的那一行」，而不是把整段业务逻辑一锅端，从而让错误信息具体、可定位。
  • 立即返回模式：检查到错误就马上 return Err(...)，保持「快乐路径」一路平铺，杜绝嵌套。
  • 扩展 try 块的判断标准：原子操作、错误类型一致、失败后需要统一清理这三种情况才适合把多个操作合并进同一个块。
  • 保留 try-catch 的合理场景：模块级初始化（不能用 await）、即发即忘的简单操作、与期望抛异常的第三方代码集成时，仍建议使用传统 try-catch——技能不做「一刀切」的教条式改造。
  • 生态联动：技能说明了与 services-layer（createTaggedError 模式）和 query-layer（错误转换为 WhisperingError）的配合关系，便于在分层架构中保持错误体系一致。

三、如何使用该技能？

第 1 步：明确告诉 AI 你的场景是同步还是异步。 描述需求时带上语境，例如「这是同步的 JSON 解析」「这是 async 的文件读取」，AI 会自动选择 trySync 或 tryAsync。

第 2 步：让 AI 生成基础包装。 同步场景示例：

const { data: config } = trySync({
	try: () => JSON.parse(configString),
	catch: (e) => {
		console.log('无效配置，使用默认值');
		return Ok({ theme: 'dark', autoSave: true });
	},
});

输出说明：data 在成功时是解析结果，失败时是默认配置，调用方无需再判断异常，代码可直接往下走。

第 3 步：异步场景记得 await。

const { data: content } = await tryAsync({
	try: () => readFile(path),
	catch: (e) => {
		console.log('文件未找到，使用默认内容');
		return Ok('默认内容');
	},
});

第 4 步：需要向上传播时返回 Err。

const { data, error } = await tryAsync({
	try: () => criticalOperation(),
	catch: (error) =>
		ServiceErr({
			message: '关键操作失败',
			cause: error,
		}),
});
if (error) return Err(error);

注意这里的 Err(error) 包装——如果写成 return error，类型会报错，因为解构出的 error 是 TaggedError 而非 Result。

第 5 步：让 AI 按最小化包装重写已有代码。 可以直接提要求：「把我这段 try-catch 拆成多个最小的 tryAsync 块，每个块配一条具体的中文错误信息，出错就立即返回」。AI 会产出类似下面的结构：

const { data: devices, error: enumerateError } = await enumerateDevices();
if (enumerateError) return Err(enumerateError);

const { data: stream, error: streamError } = await getStreamForDevice(devices[0]);
if (streamError) return Err(streamError);

return Ok(stream);

第 6 步：void 函数用 Ok(undefined)。 当被包装的函数没有返回值时，catch 中要写 return Ok(undefined)，而不是 return Ok() 或 return undefined。

第 7 步：复核产出。 重点检查三件事：是否 await 了 tryAsync；catch 返回类型是否与 try 的返回类型匹配；解构出的 error 是否被 Err() 包装。

四、同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
错误处理模式Skill（error-handling） AI 技能：约束 AI 生成规范化错误处理代码 trySync/tryAsync 包装、Ok/Err 结果、最小化包装规范、立即返回模式 需支持技能的 AI 客户端，搜索技能名或技能ID 安装（以官方说明为准）；无需引入新依赖即可先统一风格 让 AI 助手在团队项目中稳定产出同风格的错误处理代码 优势：零学习成本地获得「团队级代码规范」；不足：效果依赖客户端是否正确加载技能
原生 try-catch 语言内置语法 捕获同步/异步异常 零门槛 任意 JavaScript/TypeScript 代码 优势：无需任何依赖；不足：类型不安全、错误边界易失控、容易被写成空 catch
Promise 的 .catch() 链 语言内置 捕获 Promise 拒绝 零门槛 简单异步调用链 优势：直观；不足：链式写法易断裂，多步操作难以统一错误语义，依旧存在「错误是隐式」的问题
neverthrow 等 Result 库 第三方函数式错误处理库 Result / ResultAsync 类型、链式组合子 需安装依赖并改造现有代码风格 追求函数式风格、需要强类型错误联合的项目 优势：类型完备、可组合；不足：需要团队整体迁移思维模型，学习曲线较陡
Effect 类框架 完整的效应系统 依赖注入、并发、错误通道、资源管理 需引入框架并重构核心逻辑 大型服务端应用 优势：能力最全；不足：体量重、上手成本高，小项目容易过度设计

从对比可以看出：原生方案「零成本但无规范」，函数式库「强类型但迁移重」，而该技能的切入点是——在不改变项目依赖的前提下，先把 AI 生成的代码质量拉齐到统一的工程规范，属于「低摩擦、可渐进」的路线。

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

场景一：前端音视频设备访问（录音、麦克风） 角色：桌面端 / Web 音频应用开发者。痛点：getUserMedia 可能因权限、设备被占用而失败，传统写法容易弹出「操作失败」这种无信息量的 toast。使用方式：让 AI 把获取流包成最小的 tryAsync，catch 里抛出带 extractErrorMessage(error) 的 DeviceStreamServiceErr，并在错误分支后立即 return。实际体验：报错文案能精确到「麦克风访问失败 + 原因」，排查效率明显提升；注意要检查失败时是否调用了 cleanupRecordingStream 做资源清理，否则会残留设备占用。

场景二：配置文件与环境变量解析 角色：全栈开发者。痛点：配置解析一失败整个应用起不来。使用方式：trySync 包装 JSON.parse，catch 返回 Ok(默认配置)。实际体验：这是技能里最「无脑好用」的一段——降级逻辑从三层嵌套变成三行代码，新人也看得懂；注意默认值要有明确注释，避免「静默降级」掩盖真实配置错误。

场景三：异步文件读写与进程管理 角色：Node / 桌面端工具开发者。痛点：文件不存在、进程已退出属于预期内的常见情况，却常常被当成异常上抛。使用方式：await tryAsync 包装读文件，失败返回 Ok('默认内容')；终止进程失败则返回 Ok(undefined) 并记录「进程已经终止」。实际体验：控制流变得非常平直，代码评审时关注点从「错误处理写没写」变成「错误语义对不对」；注意 tryAsync 必须 await，漏掉会导致 data 恒为 undefined，这是最常踩的坑。

场景四：服务层错误统一传播 角色：中大型项目架构负责人。痛点：不同模块各自造错误类型，上层无法统一处理。使用方式：让 AI 按技能建议，与 services-layer 的 createTaggedError 模式配合，各服务返回各自的 ServiceErr，在 query 层统一转换为 WhisperingError。实际体验：错误类型成为接口契约的一部分，前端展示层不需要再猜测错误结构；注意统一包装后要复查 if (error) return Err(error) 这类包装是否到位。

整体上手难度评估：对熟悉 TypeScript 的开发者属于「低门槛」，主要成本在于改掉「抛异常」的思维惯性；对新手则建议先让 AI 生成、自己再逐行读懂 catch 的返回类型。

六、该技能能为用户带来的价值

  • 效率提升：原本需要人工逐行重构的错误处理代码，交给 AI 一次性产出规范版本，重构一个中型模块的 try-catch 改造通常从数小时压缩到数次对话。
  • 门槛降低：Result 模式、标签化错误、错误边界划分这些偏「架构经验」的知识，被固化成技能里的规则，初中级开发者也能写出资深风格的错误处理代码。
  • 质量可量化：可以从三个指标看到收益——空 catch 块数量下降、错误信息模糊率（「操作失败」类文案）下降、错误嵌套层级从多层压平到一层。
  • 长期价值：错误语义统一后，日志与监控可以按错误类型聚合，线上问题定位从「看堆栈猜位置」变成「看错误标签直达模块」；同时团队成员与 AI 的协作有共同语言，代码评审的沟通成本显著降低。
  • 渐进式落地：技能明确保留了 try-catch 的合理使用场景，团队可以只在新代码与重构点采用新模式，不必一次性大改存量项目。

七、常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？ A：在支持技能机制的 AI 编程助手的技能市场 / 技能管理面板中，搜索中文名「错误处理模式」或英文名 error-handling，也可用技能ID 11878 定位（入口路径与命令以官方说明为准）。技能本身由作者 epicenter 以版本 1.1 发布，是否收费、是否有额度限制请以官方说明为准，不要轻信第三方来源。

Q2：装了技能后，AI 还是给我写普通 try-catch，怎么办？ A：先确认客户端是否真正加载了技能（查看技能列表状态）。其次在提问时给出明确语境，例如「这是 async 的文件读取，请用 tryAsync 包装，读不到就返回 Ok 默认内容」。技能的触发依赖上下文描述，「编写错误处理代码」「try-catch 重构」「Result 类型」这类关键词更容易命中。

Q3：tryAsync 和 trySync 到底怎么选？我老是搞混。 A：看被包装的操作本身——同步的（JSON.parse、校验、计算、fs.existsSync）用 trySync 且不用 await；返回 Promise 的（网络请求、数据库调用、异步读写文件、navigator.mediaDevices.getUserMedia）用 tryAsync 且必须 await。技能里也列了「何时仍用传统 try-catch」：模块级初始化、即发即忘操作、与期望抛异常的第三方库集成。

Q4：为什么 return error 会报类型错误？ A：因为从 { data, error } 解构出来的 error 是原始错误值（例如 TaggedError），不是 Result 类型，函数签名要求返回 Result，所以必须写成 return Err(error)。如果想省事，也可以不解构、直接持有整个结果对象后 return userResult，那时它本身就是 Result。

Q5：它和 neverthrow、Effect 这类方案怎么选？ A：如果目标是把现有项目整体迁移到强类型函数式错误处理，neverthrow 或 Effect 更系统性；如果目标是「让 AI 写出来的代码立刻统一风格、可评审、不引入新依赖」，这个技能是更低摩擦的起点，二者也能并存——技能负责生成规范代码，库负责提供运行时能力（以官方说明为准）。