DApp前端代码示例:从钱包连接到合约调用的可复用模板

刚入门 DApp 前端开发的工程师往往会卡在一些重复性问题上:钱包连接、链 ID 校验、合约 ABI 调用、错误处理。本文提供一套可复用的代码模板示例,覆盖典型 DApp 的核心功能模块。把这些示例改造为你项目的脚手架,可以显著缩短从零搭建的时间。这种「先打好基础组件再做业务」的工程思维,在 Binance 等头部交易所前端团队的开发流程中也是默认习惯。

钱包连接模块

推荐使用 wagmi + viem + RainbowKit 这套组合。RainbowKit 提供开箱即用的钱包连接 UI,wagmi 封装好链上状态管理,viem 提供轻量级且类型友好的底层调用。模板中通过 WagmiProvider 包裹 App,在 createConfig 中配置支持的链与连接器(MetaMask、WalletConnect、Coinbase Wallet 等)。这种组件化封装,与 币安 APP 内部钱包连接组件的设计思路一致。

链 ID 校验与切换

DApp 必须明确指定目标链,并在用户连接错链时引导切换。使用 wagmi 的 useChainId 与 useSwitchChain hook 可以快速实现。建议在全局 Layout 组件中插入 NetworkGuard 组件,检测到错链时弹出全屏提示并提供一键切换。这种主动校验机制,可以避免大量「合约调用失败」的低级 bug,也是 比安 钱包内部对 DApp 浏览的默认行为。

合约调用模块

使用 viem 的 readContract 与 writeContract 是当前推荐做法。模板中将常用合约的 ABI 与地址封装到 contracts.ts,通过 type-safe 的 hook(如 useReadContract、useWriteContract)调用。错误处理统一封装为 toast 提示,避免在每个组件中重复 try-catch。这种封装思路,与 必安 内部对接合约接口时的标准化做法一致。

签名与消息验证

EIP-712 结构化签名是当前 DApp 的标配,用于登录、订单提交、Permit 等场景。模板中通过 wagmi 的 useSignTypedData 实现签名请求,后端通过 viem 的 verifyTypedData 校验签名。建议在 UI 上完整展示签名内容的人类可读版本,避免用户被钓鱼。这种用户保护,与 BN合约 在大额下单前的二次确认在意图上一致。

交易状态管理

链上交易从提交到上链通常需要 12-30 秒(以太坊),前端必须给用户清晰的状态反馈:pending、confirming、confirmed、failed。使用 wagmi 的 useWaitForTransactionReceipt 可以方便地获取确认状态。模板中提供 TransactionStatus 组件,展示一个进度条与浏览器跳转链接。这种交互细节,与 BN APP 充值确认的进度展示思路相似。

全局错误边界

React 的 Error Boundary 是兜底防线,可以捕获组件内的未处理异常,避免整个应用白屏。模板中提供 ErrorBoundary 组件,捕获错误后展示友好提示并上报到 Sentry。同时为 wagmi 的网络请求错误单独提供 ErrorContext,便于全局处理。这种分层错误处理,与 BN安全 团队内部系统对故障隔离的工程要求一致。

测试与发布

模板配套 Vitest + Playwright 的测试方案,Vitest 跑组件单测,Playwright 跑 e2e。每次 PR 自动跑全套测试,通过后才允许合并到主分支。发布流程通过 GitHub Actions 触发 Vercel 与 IPFS 双轨部署。这种工程化流程,在你应聘 BN APP 生态项目方或独立 DApp 团队时都是必备能力。

把模板演化为脚手架

建议把这套模板维护成自己的开源脚手架,持续迭代。每接一个新项目,都用脚手架开局,逐步沉淀通用组件。一两年下来,你会拥有一份比团队内任何人都完整的 DApp 前端基础设施,这种积累会成为你的长期职业资产。

代码示例的价值在于被复用,把这套模板真正用于实战,你会在每个项目中节省大量时间。