SuperAPI AI 工具集

define-errors

编程与开发

查看项目

更新于 10-16 08:37

技能介绍

define-errors 是 Epicenter 仓库中的一个技能,围绕 wellcrafted 错误库的 defineErrors 展开,用于创建错误类型或审查错误处理代码。相关技能:error-handling 负责 trySync/tryAsync 用法与 toast-on-error 模式,services-layer 负责服务架构与命名空间导出。该技能只负责变体构造、命名、字段与类型提取;异常适配与 Result 消费归 error-handling,日志级别与输出归 logging。

主要能力与规则:从 wellcrafted/error 导入 defineErrors、extractErrorMessage 及类型 InferErrors、InferError。一个公开失败契约的变体放进同一次 defineErrors 调用;不同契约(如 KV 读写失败)可各有命名空间。工厂函数返回 { message, ...fields },没有 .withMessage()/.withContext()/.withCause() 链;cause: unknown 只是普通字段,需在输入中接收并在返回对象中转发;工厂接收 cause 时应在内部调用 extractErrorMessage(cause),让调用点传原始值。每次 MyError.Variant({...}) 自动返回 Err(...),无需单独的 FooErr。用 InferErrors 为同名 const 定义同名类型,用 InferError<typeof FooError.Variant> 提取单个变体类型。变体数量由公开失败契约决定,不合并可区分的失败,也不人为拆分。message 应按实际消费者书写:会进入 toastOnError 或 $lib/report 的变体需安全可读,诊断专用变体可偏技术。呈现给用户的错误避免以原始路径、状态码或堆栈为主,技术细节放在人类可读前缀之后。

模式:静态 message 的简单变体;带结构化字段(如 table、id)并由输入计算 message;带 cause 并在工厂内提取错误消息;一次定义多个变体自动形成判别联合;按具体操作定义领域错误(如读、写、删失败)。消费变体联合时应使用基于 error.name 的穷尽 switch,并用 default: error satisfies never 锁定,不要用 if/else 链;但针对单个变体的谓词判断或守卫式特判保留 if 或普通表达式是合理的。

限制与约定:不要另造 { ok, data } 平行信封,内部边界应使用 Result<T, E>({ data, error });外部协议保留各自的线上契约。Whispering 的 $lib/rpc 保留 tagged errors,不在 RPC 适配器内转换成 { title, description };仅当适配器自身拥有下层无法拥有的失败时才定义 RPC 局部 defineErrors 命名空间。状态机不是 Result,{ state: ... }、{ outcome: ... } 这类真正的状态枚举应保持为判别联合。name 为类型级保留字段,工厂返回 name 会报错。软约定避免用 data 作为字段名,建议用 payload、body、value 或领域名。变体工厂返回非空 tagged 对象,便于用 error !== null 判别;被捕获值究竟变成该变体、回退、选择性重抛还是异常响应,属于 error-handling 的职责。