Skip to content

智能合約前端集成架構:Web3 DApp 的工程實踐

Web3 DApp 的前端架構和傳統 Web 應用有着根本性的差異。傳統應用的數據來自中心化 API 伺服器,身份驗證靠 Cookie/Token,請求-響應模型同步且可預測。而 DApp 面對的是去中心化的區塊鏈網絡:數據源是多 RPC 節點,身份驗證依賴錢包簽名,交易提交後需要等待區塊確認——整個過程充滿了異步性、不確定性和網絡延遲。

這些差異意味着,把傳統前端架構直接套用到 DApp 上會處處碰壁。狀態管理需要處理鏈上數據的異步同步,錯誤處理需要區分用戶拒絕簽名和鏈上交易回滾,性能優化需要應對大量 ABI 編解碼帶來的開銷。這篇文章從工程實踐角度,梳理一套可落地的 DApp 前端架構。

DApp 前端架構的核心差異 ​

先明確 DApp 前端和傳統前端的幾個關鍵區別:

數據來源:傳統應用從 REST/GraphQL API 獲取數據,DApp 則需要從鏈上(通過 RPC 節點讀取合約狀態)和鏈下(通過 The Graph 等索引服務或後端 API)兩個渠道獲取數據。鏈上讀取是強一致性的(取決於區塊確認數),但延遲較高。

身份模型:傳統應用通過用戶名密碼或 OAuth 獲取服務端簽發的 Token,DApp 的身份是錢包地址本身——用戶通過簽名證明自己擁有該地址的私鑰,不需要任何中心化註冊流程。

寫操作模型:傳統應用的寫操作是同步的(POST 請求立即返回結果),DApp 的寫操作是異步的——提交交易後需要等待區塊打包,可能需要幾秒到幾分鐘,期間交易可能失敗、被替換或回滾。

不可變性:鏈上數據不可篡改是優勢,但也意味着前端不能像傳統應用那樣依賴後端"修複數據"。合約部署後邏輯不可更改,前端必須做好版本兼容。

這些差異決定了 DApp 前端需要一個專門的架構層來隔離區塊鏈的複雜性。

以太坊交互層:ethers.js v7 與 viem 的選型 ​

當前以太坊前端交互層的主流選擇是 ethers.js v7 和 viem。兩者的設計哲學截然不同。

ethers.js v7 延續了傳統的 OOP 風格,Provider/Signer/Contract 都是類實例,適合習慣面向對象思維的開發者。它的生態最成熟,文檔豐富,但類型推導相對弱——很多操作需要手動類型斷言。

viem 採取了函數式設計,所有操作都是純函數,配合 TypeScript 提供了極佳的類型推導體驗。它的包體積更小(Tree-shaking 友好),性能在批量調用場景下表現更好。viem 的 Actions 模式讓你可以按需引入功能,而不是引入一個龐大的 Provider 實例。

typescript
// viem 的函數式風格
import { createPublicClient, http, getContract, parseEther } from 'viem';
import { mainnet } from 'viem/chains';
import { erc20Abi } from 'viem/abis';

const client = createPublicClient({
  chain: mainnet,
  transport: http('https://eth-mainnet.example.com'),
});

// 類型安全:erc20Abi 提供了完整的函數簽名類型推導
const usdc = getContract({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  abi: erc20Abi,
  client,
});

// 返回值類型自動推導爲 bigint,不需要手動斷言
const balance = await usdc.read.balanceOf([
  '0x1234567890123456789012345678901234567890',
]);
console.log(balance); // bigint

我的建議是:新項目首選 viem。函數式設計更契合 React Hooks 和 Vue Composition API 的心智模型,類型安全也更上一層樓。但如果項目已有大量 ethers.js 代碼積累,v7 的遷移成本需要評估——可以先用 ethers-to-viem 遷移工具做逐步替換。

錢包連接管理:多錢包適配與狀態同步 ​

DApp 的用戶入口是錢包。當前的錢包生態已經從 MetaMask 一家獨大變成了多錢包並立:MetaMask、WalletConnect、Coinbase Wallet、Rabby、Phantom(Solana 生態)各有用戶羣體。前端需要一個統一的錢包連接管理層。

EIP-6963(多注入錢包發現協議)的普及解決了 window.ethereum 被最後一個注入的錢包覆蓋的問題。配合 EIP-1193 標準,我們可以構建一個不依賴特定錢包實現的多錢包適配層。

typescript
// wallet/connection-manager.ts
import { createStore } from 'zustand/vanilla';

interface WalletState {
  status: 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
  address: string | null;
  chainId: number | null;
  provider: EIP1193Provider | null;
  error: Error | null;
}

interface WalletAdapter {
  name: string;
  icon: string;
  rdns: string; // EIP-6963 recommended wallet id
  connect(): Promise<{ address: string; chainId: number; provider: EIP1193Provider }>;
  disconnect(): Promise<void>;
  getProvider(): EIP1193Provider | null;
}

// EIP-6963 錢包發現
function discoverWallets(): WalletAdapter[] {
  const wallets: WalletAdapter[] = [];
  const handlers: ((event: EIP6963AnnounceProviderEvent) => void)[] = [];

  return new Promise((resolve) => {
    let timeoutId: number;

    const handler = (event: EIP6963AnnounceProviderEvent) => {
      wallets.push(createAdapter(event.detail));
    };

    window.addEventListener('eip6963:announceProvider', handler);
    window.dispatchEvent(new Event('eip6963:requestProvider'));

    // 給錢包 500ms 響應時間
    timeoutId = window.setTimeout(() => {
      window.removeEventListener('eip6963:announceProvider', handler);
      resolve(wallets);
    }, 500);
  });
}

狀態同步是錢包管理中最容易出 Bug 的地方。用戶可能在 DApp 運行期間切換賬戶、切換網絡、甚至斷開錢包連接。這些事件需要被正確監聽並同步到應用狀態:

typescript
// 監聽錢包事件
function setupWalletEventListeners(
  provider: EIP1193Provider,
  store: WalletStore,
) {
  provider.on('accountsChanged', (accounts: string[]) => {
    if (accounts.length === 0) {
      store.setState({ status: 'disconnected', address: null });
    } else {
      store.setState({ address: accounts[0] });
    }
  });

  provider.on('chainChanged', (chainId: string) => {
    // chainChanged 必須觸發頁面刷新或狀態重置
    // 因爲鏈切換後所有合約地址和狀態都變了
    store.setState({ chainId: parseInt(chainId, 16) });
    store.getState().onChainChanged?.();
  });

  provider.on('disconnect', () => {
    store.setState({ status: 'disconnected', address: null, provider: null });
  });
}

一個實踐中常見的坑:chainChanged 事件在某些錢包中不會自動刷新頁面。如果你的應用緩存了某個鏈上的合約數據,鏈切換後這些數據全部失效,必須強制刷新或清除緩存。

智能合約 ABI 類型安全:TypeScript 類型生成 ​

ABI(Application Binary Interface)是合約與前端交互的契約。手寫 ABI 類型既繁瑣又容易出錯。當前的標準做法是用 wagmi/cli 或 typechain 從 ABI 自動生成 TypeScript 類型。

typescript
// wagmi.config.ts - 從 Etherscan / Foundry out 目錄拉取 ABI 並生成類型
import { defineConfig } from '@wagmi/cli';
import { etherscan } from '@wagmi/cli/plugins';

export default defineConfig({
  out: 'src/generated/',
  plugins: [
    etherscan({
      apiKey: process.env.ETHERSCAN_API_KEY!,
      contracts: [
        {
          name: 'VestingVault',
          address: {
            1: '0xabc...', // mainnet
            8453: '0xdef...', // base
          },
        },
      ],
    }),
  ],
});

生成的類型讓你在調用合約方法時獲得完整的參數和返回值類型推導。這不僅是開發體驗的提升,更是安全保障——如果合約升級後 ABI 變化,前端編譯期就能發現不兼容。

鏈上數據讀取策略:多 RPC 節點輪詢與緩存 ​

RPC 節點是 DApp 的數據生命線。單一節點存在單點故障和速率限制風險。生產環境需要多節點 fallback 和負載均衡。

viem 的 fallback transport 提供了開箱即用的多節點支持:

typescript
import { createPublicClient, fallback, http } from 'viem';
import { mainnet } from 'viem/chains';

const transport = fallback(
  [
    http('https://mainnet.infura.io/v3/xxx', { timeout: 5000 }),
    http('https://eth-mainnet.alchemyapi.io/v2/xxx', { timeout: 5000 }),
    http('https://cloudflare-eth.com', { timeout: 10000 }),
  ],
  {
    rank: true, // 自動按延遲和成功率排序
    retryCount: 2, // 每個節點重試次數
  },
);

const client = createPublicClient({ chain: mainnet, transport });

鏈上數據讀取的性能瓶頸在於大量 eth_call 請求。對於高頻讀取的數據(如代幣餘額、價格信息),需要在前端做緩存層。但緩存鏈上數據有一個微妙的問題:如何知道緩存過期?

區塊鏈的"緩存失效"依賴於新區塊的產生。以太坊平均每 12 秒出一個區塊,所以緩存的 TTL 可以設爲 12 秒(一個區塊周期)。更精確的做法是訂閱 blockNumber 事件,新區塊到來時清除相關緩存。

typescript
// 基於區塊號的緩存層
class BlockBasedCache {
  private cache = new Map<string, { value: unknown; blockNumber: bigint }>();
  private currentBlock: bigint = 0n;

  constructor(client: PublicClient) {
    // 監聽新區塊
    client.watchBlockNumber({
      onBlockNumber: (blockNumber) => {
        this.currentBlock = blockNumber;
        // 清除超過 3 個區塊的緩存
        for (const [key, entry] of this.cache) {
          if (this.currentBlock - entry.blockNumber > 3n) {
            this.cache.delete(key);
          }
        }
      },
      poll: true,
      pollingInterval: 4000,
    });
  }

  async read<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
    const cached = this.cache.get(key);
    if (cached && this.currentBlock - cached.blockNumber < 3n) {
      return cached.value as T;
    }
    const value = await fetcher();
    this.cache.set(key, { value, blockNumber: this.currentBlock });
    return value;
  }
}

對於更複雜的數據查詢(如歷史事件、聚合統計),直接 RPC 調用效率很低。這時應該引入 The Graph 等 Subgraph 索引服務,把鏈上事件索引成可查詢的 GraphQL API。

交易狀態管理與用戶反饋 ​

交易是 DApp 中最需要精心設計用戶體驗的環節。一筆交易的完整生命周期包括:構建交易 → 估算 Gas → 發起簽名 → 等待打包 → 確認成功/失敗。整個過程可能持續數十秒,用戶需要持續的狀態反饋。

typescript
// 交易狀態機
type TransactionStatus =
  | { stage: 'idle' }
  | { stage: 'preparing' }
  | { stage: 'estimating_gas'; estimatedGas?: bigint }
  | { stage: 'awaiting_signature' }
  | { stage: 'submitted'; hash: string }
  | { stage: 'confirming'; hash: string; confirmations: number }
  | { stage: 'success'; hash: string; receipt: TransactionReceipt }
  | { stage: 'failed'; hash: string; error: TransactionError }
  | { stage: 'rejected'; error: UserRejectedError };

async function executeTransaction(
  walletClient: WalletClient,
  params: WriteContractParameters,
  onStatusChange: (status: TransactionStatus) => void,
): Promise<TransactionStatus> {
  try {
    onStatusChange({ stage: 'preparing' });

    // Gas 估算
    onStatusChange({ stage: 'estimating_gas' });
    const gasEstimate = await walletClient.estimateGas(params);
    // 加 20% buffer,防止鏈上狀態變化導致 Gas 不足
    const gas = (gasEstimate * 120n) / 100n;
    onStatusChange({ stage: 'estimating_gas', estimatedGas: gas });

    // 請求用戶簽名
    onStatusChange({ stage: 'awaiting_signature' });
    const hash = await walletClient.writeContract({ ...params, gas });

    // 等待打包
    onStatusChange({ stage: 'submitted', hash });
    const receipt = await waitForTransactionReceipt(walletClient, { hash });

    if (receipt.status === 'success') {
      onStatusChange({ stage: 'success', hash, receipt });
      return { stage: 'success', hash, receipt };
    } else {
      onStatusChange({ stage: 'failed', hash, error: { code: 'REVERTED' } });
      return { stage: 'failed', hash, error: { code: 'REVERTED' } };
    }
  } catch (error) {
    if (isUserRejectedError(error)) {
      onStatusChange({ stage: 'rejected', error });
      return { stage: 'rejected', error };
    }
    throw error;
  }
}

UI 層需要根據交易狀態顯示不同的反饋:awaiting_signature 時提示"請在錢包中確認",submitted 時顯示交易哈希和區塊瀏覽器鏈接,confirming 時顯示確認進度。這些狀態反饋不是可選項——沒有它們,用戶會以爲 DApp 卡死了。

Gas 費估算與優化 ​

Gas 費是 DApp 用戶體驗的痛點之一。前端能做的優化包括:

EIP-1559 的 Gas 預估:不再使用 gasPrice,而是用 maxFeePerGas 和 maxPriorityFeePerGas。viem 的 estimateFeesPerGas 會返回當前網絡的建議費率。

批量交易:如果一筆操作涉及多次合約調用,考慮使用 multicall 合約(如 Multicall3)把多次調用合併爲一筆交易,分攤 Gas 成本。

L2 優先:對於高頻交互場景,優先部署到 Layer 2(Base、Arbitrum、Optimism),Gas 費可以降低一到兩個數量級。前端需要優雅地提示用戶切換到正確的鏈。

完整的合約交互封裝層 ​

把前面的各個部分組合起來,一個完整的合約交互封裝層如下:

typescript
// lib/contract-manager.ts
import {
  createPublicClient,
  createWalletClient,
  custom,
  fallback,
  http,
  type PublicClient,
  type WalletClient,
} from 'viem';
import { mainnet, base } from 'viem/chains';
import { getContract } from 'viem';
import type { Abi } from 'viem';

interface ContractManagerConfig {
  abi: Abi;
  address: Record<number, `0x${string}`>;
  chains?: typeof mainnet[];
}

export function createContractManager<TAbi extends Abi>(
  config: ContractManagerConfig,
) {
  const chains = config.chains ?? [mainnet, base];
  const clients = new Map<number, { public: PublicClient; wallet: WalletClient | null }>();

  // 爲每條鏈創建 public client
  for (const chain of chains) {
    const transport = fallback([
      http(`https://${chain.id}.example-rpc.com`),
      http(`https://${chain.id}.fallback-rpc.com`),
    ]);
    clients.set(chain.id, {
      public: createPublicClient({ chain, transport }),
      wallet: null,
    });
  }

  function getContractForChain(chainId: number, walletClient?: WalletClient) {
    const entry = clients.get(chainId);
    if (!entry) throw new Error(`Unsupported chain: ${chainId}`);
    const address = config.address[chainId];
    if (!address) throw new Error(`No contract address for chain ${chainId}`);

    return getContract({
      address,
      abi: config.abi,
      client: {
        public: entry.public,
        wallet: walletClient ?? entry.wallet ?? undefined,
      },
    });
  }

  return { getContractForChain, clients };
}

DApp 前端性能挑戰 ​

DApp 前端的性能瓶頸和傳統應用不同:

Bundle 體積:viem/ethers.js 本身不小,加上多鏈配置和 ABI 文件,首屏 JS 容易膨脹。解決方案是按鏈 lazy load——用戶連接前只加載錢包發現邏輯,連接後再按需加載對應鏈的配置。

大量 eth_call 的並發控制:如果一個頁面需要讀取 20 個合約的狀態,20 個並發 RPC 請求會觸發節點速率限制。用 Multicall3 合約把多次 eth_call 合併成一次。

WebSocket vs HTTP 輪詢:實時監聽鏈上事件可以用 WebSocket(更及時)或 HTTP 輪詢(更穩定)。生產環境建議用 HTTP 輪詢爲主、WebSocket 爲輔——WebSocket 在網絡不穩定時頻繁斷開重連,維護成本高於輪詢。

優缺點分析與實踐建議 ​

這套架構的優勢在於:關注點分離清晰(交互層、錢包層、狀態層各司其職),類型安全貫穿全鏈路,多鏈和多錢包支持可擴展。代價是初始搭建成本較高——對於簡單的單鏈 DApp 可能過度設計。

幾個實踐建議:

  1. 不要在業務組件中直接調用 viem/ethers.js,統一通過封裝層訪問,方便後續替換底層庫
  2. 交易狀態必須對用戶可見,每一階段都要有 UI 反饋
  3. RPC 節點至少配置 3 個來源,分屬不同服務商
  4. ABI 類型生成納入 CI,合約升級後自動檢測 ABI 變更
  5. 錯誤信息要區分用戶可操作的(如餘額不足)和系統級的(如 RPC 節點故障)

小結 ​

Web3 DApp 的前端架構核心挑戰在於:處理區塊鏈網絡的異步性和不確定性、適配多錢包多鏈生態、保證合約交互的類型安全。選擇 viem 作爲交互層、用 EIP-6963 做錢包發現、用自動生成的 ABI 類型保證類型安全、用基於區塊號的緩存優化讀取性能、用狀態機管理交易生命周期——這些組合在一起,構成了一套可落地的 DApp 前端工程方案。DApp 前端不需要重新發明輪子,但需要把傳統前端的每個環節都重新審視一遍,因爲底層假設已經完全不同了。

MIT Licensed