Wagmi React 错误处理用强类型 error 属性与 name 判别式精准处理链上异常【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文基于 Wagmi 官方 React 指南 error-handling.md 展开讲解 Wagmi React Hooks 中error属性的强类型设计、如何用name属性做错误判别式并结合 packages/react/src/errors/ 与 packages/core/src/errors/ 的源码实现说明 Wagmi 错误体系从底层BaseError到具体错误类的完整链路帮助你写出类型安全、可维护的以太坊应用错误处理代码。一、核心设计error 属性是强类型联合Wagmi React Hooks 的每个返回值中error属性都被强类型标注为其对应的联合错误类型。这意味着你不需要在运行时做instanceof判断也不需要any就能在编译期获得精确的错误字段。指南中的核心示例对应 error-handling.md 的 twoslash 代码组import { useBlockNumber } from wagmi function App() { const { data, error } useBlockNumber() // ^? // error 的类型是联合错误类型 error?.name // ^? // name 是可枚举的判别字段 if (error?.name HttpRequestError) { const { status } error // ^? // status 是 number return divA HTTP error occurred. Status: {status}/div } if (error?.name LimitExceededRpcError) { const { code } error // ^? // code 是 number return divRate limit exceeded. Code: {code}/div } // ... }这里的两个要点error是可选的undefined表示请求成功所以判定时要用error?.name而非error.name避免null访问。name是所有错误对象共享的判别式discriminant字段取值是具体的错误类名字符串字面量联合这正是 TypeScript 的 discriminated union 模式。编译器会依据name的值自动收窄narrow出对应的错误字段。这种设计的直接收益是在if (error?.name HttpRequestError)分支里error的类型自动收窄为HttpRequestErrorstatus、headers等字段无需手动断言即可访问。二、用 name 判别式区分错误类型Wagmi 的错误判别完全依赖name属性。不同的name对应不同的错误语义与可访问字段下面结合典型场景说明如何组织判别逻辑。HTTP 层错误HttpRequestError当 RPC 节点返回非 2xx 状态时底层 HTTP 传输抛出HttpRequestError。它的特征字段是statusHTTP 状态码与headers响应头。典型处理if (error?.name HttpRequestError) { const { status } error if (status 429) return div请求过于频繁请稍后重试/div if (status 500) return div节点服务异常/div }RPC 层错误LimitExceededRpcError 等当节点返回 JSON-RPC 错误码如 -32000 系列时会被映射为对应的*RpcError。例如LimitExceededRpcError携带code字段可用于识别限流if (error?.name LimitExceededRpcError) { const { code } error return divRate limit exceeded. Code: {code}/div }判别式组织的通用模式由于name是字符串字面量联合可以用switch或连续的if穷举所有关心的分支并为兜底情况保留默认 UIfunction ErrorFallback({ error }: { error: unknown }) { if (!error) return null if (error.name HttpRequestError) { return divHTTP {error.status}/div } if (error.name LimitExceededRpcError) { return div限流{error.code}/div } if (error.name WagmiProviderNotFoundError) { return div请将组件包裹在 WagmiProvider 内/div } // 兜底 return div未知错误/div }三、底层实现BaseError 错误体系Wagmi 的所有错误都继承自一个BaseError基类理解它的结构能帮你读懂任何错误实例的字段含义。Core 层基类packages/core/src/errors/base.tsCore 的 BaseError 定义了统一的错误形态name默认WagmiCoreError子类覆写为自己的类名作为判别式。details底层原始错误消息字符串来源于cause。shortMessage人类可读的简短描述。docsPath指向官方文档的相对路径用于在错误消息里拼接出文档链接。metaMessages附加的提示行数组。version当前库版本号便于排障时定位环境。它的构造函数会把上述片段拼装成多行的message先shortMessage再metaMessages然后是Docs: baseUrldocsPath.html#slug再Details: details最后是Version: version。因此打印error.message时你能直接看到文档链接 底层细节 版本三段信息对线上排障极有价值。此外它还提供了walk(fn)方法沿cause链逐层遍历错误对象直到某个节点使回调返回true。这让你可以方便地从外层错误中钻取出最内层的根因例如从HttpRequestError中取出被包裹的底层 fetch 错误// 沿 cause 链找到第一个满足条件的根因 const root error.walk((e) e instanceof SomeBaseError)React 层基类packages/react/src/errors/base.tsReact 的 BaseError 继承自 Core 层BaseError将name覆写为WagmiError并把docsBaseUrl固定为 React 文档站。React 包的所有具体错误Provider 相关、Connector 相关等都从此类派生从而共享上述消息拼装与walk能力。示例具体错误WagmiProviderNotFoundErrorcontext.ts 中的WagmiProviderNotFoundError是一个最小示例——它表示在WagmiProvider之外使用了useConfig等 Hook构造时固定给出提示消息与docsPathexport class WagmiProviderNotFoundError extends BaseError { override name WagmiProviderNotFoundError constructor() { super(useConfig must be used within WagmiProvider., { docsPath: /api/WagmiProvider, }) } }这类配置类错误通常发生在开发期name判别后给出明确修复指引即可。四、可导出的错误类型清单Wagmi 的错误类按模块分组完整清单见 site/shared/errors.md并通过 packages/react/src/exports/index.ts 对外导出每个类同时导出X与XType两个符号。常见分类分类错误类触发场景基类BaseError所有错误的公共父类ConfigConnectorAccountNotFoundError连接器上不存在该账户或不可用ConfigConnectorAlreadyConnectedError连接器已处于连接状态ConfigConnectorChainMismatchErrorConfig 与连接器当前链 ID 不同步罕见多为钱包上游问题ConfigChainNotConfiguredError链未在Config[chains]中配置ConfigConnectorNotConnectedError连接器未连接ConfigConnectorNotFoundError找不到可用连接器ConfigConnectorUnavailableReconnectingError重连阶段连接器方法尚不可用ConnectorProviderNotFoundError连接器 provider 缺失或不可用ConnectorSwitchChainNotSupportedError连接器不支持切换链ReactWagmiProviderNotFoundError在WagmiProvider外使用 Hook实际编码时建议按判别优先级组织先处理 Config/Provider 这类结构性错误多为开发期问题再处理 HTTP/RPC 这类运行时错误多为网络/节点问题最后兜底。五、与 wagmi/core 的衔接Action 的 ErrorTypeReact 指南处理的是声明式 Hook的error属性若你直接调用 Wagmi Core 的 actions命令式 API错误处理方式略有不同由于 TypeScript 暂无类型化异常抽象最务实的做法是在catch中显式断言为对应的ErrorType。Core 指南给出的示例import { type GetBlockNumberErrorType, getBlockNumber } from wagmi/core import { config } from ./config try { const blockNumber await getBlockNumber(config) } catch (e) { const error e as GetBlockNumberErrorType error.name // ^? // Error | HttpRequestError | InternalRpcError | LimitExceededRpcError | ... if (error.name InternalRpcError) error.code // ^? // -32603 if (error.name HttpRequestError) { error.headers error.status } }命名规律是ModuleErrorType如getBlockNumber对应GetBlockNumberErrorType。Core 指南也特别提示若你使用 React Hooks则无需手动断言因为error属性已经是强类型的。六、实践建议优先依赖name判别式而非instanceof。name是字符串字面量便于序列化、跨包比较且编译器能据此自动收窄类型。始终用可选链error?.name因为成功时error为undefined。在 UI 层做兜底未识别的name应落入默认错误块避免静默失败。打印error.message排障它已自带文档链接 底层细节 版本比单独打印error.name信息量更大需要根因时可用error.walk沿cause链钻取。区分两类错误处理路径React Hooks 用强类型error属性Core actions 用catchModuleErrorType断言。两条路径的判别字段name与底层BaseError体系是共通的可复用同一套判别逻辑。小结Wagmi React 的错误处理建立在强类型error属性 name判别式 统一BaseError基类三件套之上。从 Core 的 BaseError 的消息拼装与walk根因遍历到 React 的 BaseError 继承与 具体错误类再到 完整错误清单 与 Core 指南 的 actions 断言模式构成了一套编译期安全、运行时可读的错误体系。掌握name判别式的组织方式后你就能为 HTTP、RPC、Connector、Provider 等不同层级的异常写出精确、可维护的处理逻辑。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考