小編精選 - 技術文章翻譯 · 05月06日

從源碼到架構：React useActionState 深度剖析

從原始碼到架構：React useActionState 深度剖析

> React 19 引入的 `useActionState` 是近年來 React Hooks 體系中設計最精巧的 API 之一。它表面上只是一個管理表單狀態的 Hook，但內部卻隱藏著**三個 Hook 協作、循環佇列排程、Transition 上下文恢復、Thenable 狀態追蹤**等一系列精妙的工程實作。我們將從原始碼出發，逐層剝開它的架構設計，幫助我們真正理解這個 API 背後的設計哲學。

一、為什麼 useActionState 值得深入分析？

在 React 19 之前，處理一個帶有非同步提交、loading 狀態、錯誤處理的表單，我們需要這樣寫：

jsx 体验AI代码助手 代码解读复制代码function OldForm() {
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);
  const [result, setResult] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setIsLoading(true);
    setError(null);
    try {
      const formData = new FormData(e.target);
      const res = await submitToServer(formData);
      setResult(res);
    } catch (err) {
      setError(err.message);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" />
      <button disabled={isLoading}>
        {isLoading ? '提交中...' : '提交'}
      </button>
      {error && <p className="error">{error}</p>}
      {result && <p className="success">{result.message}</p>}
    </form>
  );
}

三個 useState、一個 try/catch/finally、一個 e.preventDefault()——這是每一個 React 開發者都寫過無數次的樣板程式碼。而 React 19 給出的答案是：

jsx 体验AI代码助手 代码解读复制代码function NewForm() {
  const [state, formAction, isPending] = useActionState(
    async (prevState, formData) => {
      const res = await submitToServer(formData);
      return { success: true, message: res.message };
    },
    { success: null, message: '' }
  );

  return (
    <form action={formAction}>
      <input name="email" />
      <button disabled={isPending}>
        {isPending ? '提交中...' : '提交'}
      </button>
      {state.message && (
        <p className={state.success ? 'success' : 'error'}>
          {state.message}
        </p>
      )}
    </form>
  );
}

一個 Hook，三個回傳值，零樣板程式碼。這不是簡單的語法糖——它背後是一套完整的 Action 驅動狀態管理架構。理解了 useActionState，我們就理解了 React 19 對「副作用即狀態」這一理念的全部思考。

二、從 useFormState 到 useActionState

useActionState 的前身是 React Canary 版本中的 useFormState。React 團隊在正式發布時將其重新命名，這個決策背後蘊含著深刻的設計思考。

useFormState 的問題在於：它把自己框死了。 "Form" 這個詞暗示它只能用於表單場景，但實際上這個 Hook 的能力遠不止於此。任何需要「執行一個副作用，然後基於結果更新狀態」的場景，都可以用它來處理。React 團隊意識到了這個命名上的侷限，做出了一個看似微小實則關鍵的決定——將其更名為 useActionState。

這個改名反映了 React 19 的一個核心設計理念：Action 不只是表單的專利，它是一種通用的非同步狀態變更模式。 在 React 19 的語意體系中，"Action" 指的是任何可能產生副作用並導致狀態變更的函式呼叫。它可以是表單提交、按鈕點擊、資料同步，甚至是一個計時器觸發的操作。useActionState 是這個 Action 體系的基礎設施之一，與 useTransition、useOptimistic、useFormStatus 共同構成了完整的 Action 工具鏈。

從 useFormState 到 useActionState 的演進，本質上是從「資料驅動」到「意圖驅動」的範式轉變。前者關注的是「表單有什麼資料」，後者關注的是「使用者想做什麼」。這種視角的轉換，讓 API 的抽象層級提升了一個維度。

三、API 表面：簡潔之下的設計

3.1 函式簽名

typescript 体验AI代码助手 代码解读复制代码function useActionState<S, P>(
  action: (state: Awaited<S>, payload: P) => Awaited<S> | Promise<Awaited<S>>,
  initialState: Awaited<S>,
  permalink?: string
): [Awaited<S>, (payload: P) => void, boolean];

這個簽名中有幾個值得注意的設計細節：

泛型 <S, P> 的雙參數設計。S 代表狀態型別，P 代表 payload 型別。S 被 Awaited<> 包裹，意味著狀態可以是 Promise<T> 型別——Action 回傳的 Promise 會被自動解包。這個設計讓同步和非同步 Action 在型別層面保持一致。

action 的第一個參數是 prevState。這和 useReducer 的 reducer 函式簽名一脈相承，但有一個關鍵差異：useReducer 的 reducer 是純同步函式，而這裡的 action 可以是非同步函式。React 內部會自動處理 Promise 的解析和狀態的更新。

permalink 參數。這是一個容易被忽略但設計精巧的參數。它用於 Server Components 場景，告訴 React 這個 Action 修改的是哪個頁面的資料。在串流 SSR 中，React 會利用這個資訊在伺服器渲染時就展示 Action 的結果，而不需要等待客戶端 hydration 完成。

3.2 三個回傳值

typescript 体验AI代码助手 代码解读复制代码const [state, dispatch, isPending] = useActionState(action, initialState);

回傳值型別說明state``Awaited<S>Action 的最新執行結果，初始為 initialState``dispatch``(payload: P) => void觸發 Action 的函式，payload 會作為第二個參數傳給 actionisPending``boolean是否有正在執行的 ActionisPending 的實作尤為巧妙。它不是簡單的「Action 是否正在執行」標誌，而是基於 React 的 Transition 機制實作的。當 Action 在 Transition 中執行時，isPending 會自動變為 true，在 Transition 完成後變為 false。這意味著它天然與 React 的並發渲染特性整合，能夠在長時間執行的 Action 期間保持 UI 的回應性。

四、原始碼剖析：Hook 協作的秘密

這是本文最核心的部分。我們將深入 React 原始碼（packages/react-reconciler/src/ReactFiberHooks.js），看看 useActionState 到底是如何實作的。

4.1 整體架構

useActionState 的核心秘密在於：它不是一個 Hook，而是三個 Hook 的協作體。

當我們在元件中呼叫 useActionState 時，React 內部會建立三個獨立的 Hook 實例，它們各自管理不同的職責：

stateHook：儲存 Action 的執行結果，本質上是 useState 的底層實作
pendingStateHook：追蹤 pending 狀態，使用 Thenable 模式實現細粒度的非同步追蹤
actionQueueHook：管理 Action 的執行佇列，使用循環鏈結串列實現高效的入佇列與出佇列

4.2 mountActionState：初始化的精密工程

讓我們看看首次渲染時的原始碼：

javascript 体验AI代码助手 代码解读复制代码// packages/react-reconciler/src/ReactFiberHooks.js

// 一個恆等 reducer——直接回傳新狀態
function actionStateReducer<S>(oldState: S, newState: S): S {
  return newState;
}

function mountActionState<S, P>(
  action: (Awaited<S>, P) => Awaited<S>,
  initialStateProp: Awaited<S>,
  permalink?: string
): [Awaited<S>, (P) => void, boolean] {
  // Hook 1: 狀態 Hook —— 儲存 Action 結果
  const stateHook = mountStateImpl<Awaited<S>>(initialStateProp);
  const setState = stateHook.queue.dispatch;

  // Hook 2: Pending 狀態 Hook —— 追蹤非同步執行狀態
  // 使用 Thenable 模式，類似 Transition 的 pending 追蹤
  const pendingStateHook = mountStateImpl<Thenable<boolean> | boolean>(false);
  const setPendingState: boolean => void =
    dispatchOptimisticSetState.bind(null, pendingStateHook.queue, false);

  // Hook 3: Action 佇列 Hook —— 管理執行佇列
  const actionQueueHook = mountRefImpl<ActionStateQueue<S, P> | null>(null);
  const actionQueue = actionQueueHook.mutableRef;

  // 初始化佇列
  if (actionQueue.current === null) {
    actionQueue.current = {
      action: action,
      state: initialStateProp,
      pending: null,  // 循環鏈結串列的頭指標
    };
  }

  // 建立 dispatch 函式
  const dispatch = dispatchActionState.bind(
    null,
    actionQueue.current,
    setState,
    setPendingState,
    action,
    permalink
  );

  // 計算 isPending
  const isPending =
    pendingStateHook.memoizedState !== false &&
    pendingStateHook.memoizedState !== null;

  return [stateHook.memoizedState, dispatch, isPending];
}

這段程式碼有幾個值得深入分析的細節：

actionStateReducer 是一個恆等函式。它直接回傳 newState，不做任何計算。這意味著 useActionState 的狀態更新不是透過 reducer 邏輯推導出來的，而是由 Action 函式直接決定的。這與 useReducer 形成了鮮明對比——useReducer 的狀態是由舊狀態和 action type 推導而來，而 useActionState 的狀態是 Action 函式的回傳值。這個設計選擇反映了兩種不同的狀態管理哲學。

pendingStateHook 使用 dispatchOptimisticSetState。這不是普通的 setState，而是 React 內部的樂觀更新機制。當 Action 開始執行時，pending 狀態會被設定為一個 Thenable 物件（一個具有 then 方法的物件），而不是簡單的 true。React 的並發渲染器能夠識別 Thenable 物件，並在其 resolve 時自動觸發重新渲染。這種設計讓 isPending 的更新與 React 的排程系統深度整合，而不是簡單地設定一個布林值。

actionQueue 使用 mountRefImpl 而非 mountStateImpl。這是一個關鍵的設計決策。佇列的變更不應該觸發重新渲染——只有佇列中 Action 的執行結果才應該觸發渲染。使用 Ref 來儲存佇列，確保了佇列操作（入隊、出隊）不會導致不必要的渲染。

4.3 循環鏈結串列：Action 佇列的資料結構

useActionState 的 Action 佇列使用了一個循環單向鏈結串列（Circular Singly Linked List）來實作。這是一個在演算法面試中經常出現的資料結構，React 團隊將其應用到了實際的工程問題中。

javascript 体验AI代码助手 代码解读复制代码// Action 佇列節點的資料結構
interface ActionStateQueueNode<S, P> {
  action: (state: Awaited<S>, payload: P) => Awaited<S>;
  payload: P;
  nextState: Awaited<S> | null;  // Action 執行後的結果
  status: 'pending' | 'fulfilled' | 'rejected';
  value: Awaited<S> | null;
  then: Thenable<Awaited<S>>['then'] | null;
  next: ActionStateQueueNode<S, P> | null;  // 指向下一個節點
}

// Action 佇列的資料結構
interface ActionStateQueue<S, P> {
  action: ((state: Awaited<S>, payload: P) => Awaited<S>) | null;
  state: Awaited<S>;
  pending: ActionStateQueueNode<S, P> | null;  // 佇列尾指標
}

為什麼選擇循環鏈結串列而不是陣列或普通佇列？有三個原因：

O(1) 的入隊和出隊操作。在循環鏈結串列中，入隊只需要將新節點連結到尾節點的 next，並更新尾指標；出隊只需要將尾節點的 next 指向第二個節點。不需要像陣列那樣進行元素移動或擴容。

天然的空佇列判斷。當佇列中只有一個節點時，last.next === last，這個條件可以用來判斷「這是最後一個 Action」。當佇列為空時，pending === null。

記憶體效率。不需要預先分配固定大小的陣列，也不需要在佇列增長時進行擴容複製。每個節點只在需要時建立，Action 完成後可以被垃圾回收。

五、dispatchActionState：觸發 Action 的完整鏈路

當使用者呼叫 dispatch(payload) 時，到底發生了什麼？讓我們追蹤完整的執行鏈路。

5.1 dispatchActionState 原始碼

javascript 体验AI代码助手 代码解读复制代码function dispatchActionState<S, P>(
  actionQueue: ActionStateQueue<S, P>,
  setState: (newState: Awaited<S>) => void,
  setPendingState: (isPending: boolean) => void,
  action: (Awaited<S>, P) => Awaited<S>,
  permalink: string | undefined,
  payload: P
) {
  // 1. 建立 Action 節點
  const node: ActionStateQueueNode<S, P> = {
    action: action,
    payload: payload,
    nextState: null,
    status: 'pending',
    value: null,
    then: null,
    next: null,
  };

  // 2. 加入循環佇列（O(1) 操作）
  const last = actionQueue.pending;
  if (last === null) {
    // 佇列為空，自我循環
    node.next = node;
  } else {
    // 插入到尾部
    node.next = last.next;
    last.next = node;
  }
  actionQueue.pending = node;

  // 3. 設定 pending 狀態
  setPendingState(true);

  // 4. 在 Transition 中執行 Action
  startTransition(() => {
    runActionStateAction(actionQueue, node);
  });
}

注意第 4 步：Action 總是在 startTransition 中執行。這確保了 Action 的狀態更新被標記為低優先級的 Transition 更新，不會阻塞使用者的高優先級互動（如輸入、點擊）。這是 React 19「非阻塞 UI」理念在 useActionState 中的具體體現。

5.2 runActionStateAction：執行引擎

javascript 体验AI代码助手 代码解读复制代码function runActionStateAction<S, P>(
  actionQueue: ActionStateQueue<S, P>,
  node: ActionStateQueueNode<S, P>
) {
  const action = node.action;
  const payload = node.payload;
  const prevState = actionQueue.state;

  if (node.isTransition) {
    // 恢復原始的 Transition 上下文
    const prevTransition = ReactSharedInternals.T;
    const currentTransition = ({}: any);
    ReactSharedInternals.T = currentTransition;

    try {
      const returnValue = action(prevState, payload);
      const onStartTransitionFinish = ReactSharedInternals.S;
      if (onStartTransitionFinish !== null) {
        onStartTransitionFinish(currentTransition, returnValue);
      }
      handleActionReturnValue(actionQueue, node, returnValue);
    } catch (error) {
      onActionError(actionQueue, node, error);
    } finally {
      ReactSharedInternals.T = prevTransition;
    }
  } else {
    try {
      const returnValue = action(prevState, payload);
      handleActionReturnValue(actionQueue, node, returnValue);
    } catch (error) {
      onActionError(actionQueue, node, error);
    }
  }
}

這段程式碼中最精妙的部分是 Transition 上下文的恢復。當 dispatch 在一個既有的 Transition 中被呼叫時（例如透過 <form action> 觸發），React 會保存目前的 Transition 上下文（ReactSharedInternals.T），在 Action 執行時恢復它，執行完畢後再還原。這確保了巢狀 Transition 的正確性——內層 Action 能夠感知到外層 Transition 的存在，從而正確處理 pending 狀態和優先級。

ReactSharedInternals.T 和 ReactSharedInternals.S 是 React 內部的全域狀態槽位，分別儲存目前 Transition 實例和 Transition 完成回呼。這些是 React 排程系統的核心內部 API，正常情況下開發者不應該直接存取它們。但在 useActionState 的實作中，React 團隊需要操作這些底層 API 來確保 Action 執行與 Transition 系統的正確整合。

六、非同步處理：Thenable 追蹤

handleActionReturnValue 是 useActionState 處理非同步 Action 的核心函式。它需要處理三種情況：同步值、Promise、Thenable。

javascript 体验AI代码助手 代码解读复制代码function handleActionReturnValue<S, P>(
  actionQueue: ActionStateQueue<S, P>,
  node: ActionStateQueueNode<S, P>,
  returnValue: Awaited<S> | Promise<Awaited<S>>
) {
  if (typeof returnValue === 'object' && returnValue !== null) {
    if (typeof returnValue.then === 'function') {
      // Promise 或 Thenable —— 非同步處理
      returnValue.then(
        (nextState: Awaited<S>) => onActionSuccess(actionQueue, node, nextState),
        (error: mixed) => onActionError(actionQueue, node, error)
      );
    } else {
      // 同步物件值
      const nextState = (returnValue: any);
      onActionSuccess(actionQueue, node, nextState);
    }
  } else {
    // 同步原始值
    const nextState = (returnValue: any);
    onActionSuccess(actionQueue, node, nextState);
  }
}

這裡有一個容易忽略但極其重要的設計：useActionState 檢查的是 then 方法的存在，而不是 instanceof Promise。這意味著它能夠處理任何 Thenable 物件，不僅僅是原生 Promise。這個設計選擇與 React 18 引入的 Thenable 概念一脈相承——React 的並發特性（如 Suspense、Transition）都基於 Thenable 協議而非 Promise API，因為 Thenable 是一個更通用的非同步協議。

6.1 onActionSuccess：成功後的連鎖反應

javascript 体验AI代码助手 代码解读复制代码function onActionSuccess<S, P>(
  actionQueue: ActionStateQueue<S, P>,
  actionNode: ActionStateQueueNode<S, P>,
  nextState: Awaited<S>
) {
  // 1. 標記節點為已完成
  actionNode.status = 'fulfilled';
  actionNode.value = nextState;
  notifyActionListeners(actionNode);

  // 2. 更新佇列的狀態快照
  actionQueue.state = nextState;

  // 3. 從循環佇列中出隊，並執行下一個
  const last = actionQueue.pending;
  if (last !== null) {
    const first = last.next;
    if (first === last) {
      // 這是佇列中最後一個 Action
      actionQueue.pending = null;
    } else {
      // 移除頭節點，更新尾指標
      const next = first.next;
      last.next = next;
      // 遞迴執行下一個 Action
      runActionStateAction(actionQueue, next);
    }
  }
}

注意第 3 步的遞迴呼叫：當一個 Action 完成後，它會自動觸發佇列中的下一個 Action。這就是 useActionState 實作「順序執行」的機制——即使我們快速點擊了提交按鈕三次，三個 Action 也會按照順序依次執行，每個 Action 都能拿到前一個 Action 的執行結果作為 prevState。

6.2 onActionError：錯誤的級聯處理

javascript 体验AI代码助手 代码解读复制代码function onActionError<S, P>(
  actionQueue: ActionStateQueue<S, P>,
  actionNode: ActionStateQueueNode<S, P>,
  error: mixed
) {
  actionNode.status = 'rejected';
  actionNode.value = error;
  notifyActionListeners(actionNode);

  // 關鍵：將 action 設為 null，阻止後續 Action 執行
  actionQueue.action = null;
  actionQueue.pending = null;

  // 錯誤沿 Fiber 樹向上傳播
  throw error;
}

當 Action 擲出例外時，onActionError 會將 actionQueue.action 設為 null。這個操作的效果是阻止佇列中所有後續 Action 的執行。這是一種「快速失敗」（fail-fast）策略——一旦某個 Action 失敗，後續的 Action 即使已經入隊也不會被執行，因為它們可能依賴於失敗 Action 的結果。

七、updateActionState：更新時的 Hook 一致性

React 的 Hooks 系統要求 Hook 的呼叫順序在每次渲染時保持一致。useActionState 在更新時的實作確保了這一點：

javascript 体验AI代码助手 代码解读复制代码function updateActionState<S, P>(
  action: (Awaited<S>, P) => Awaited<S>,
  initialState: Awaited<S>,
  permalink?: string
): [Awaited<S>, (P) => void, boolean] {
  // 按照掛載時的順序恢復三個 Hook
  const stateHook = updateWorkInProgressHook();
  const pendingStateHook = updateWorkInProgressHook();
  const actionQueueHook = updateWorkInProgressHook();

  return updateActionStateImpl(
    stateHook, currentStateHook,
    pendingStateHook, currentPendingStateHook,
    actionQueueHook, currentActionQueueHook,
    action, initialState, permalink
  );
}

updateWorkInProgressHook() 是 React Hooks 系統的核心函式，它按照 Fiber 節點上 Hook 鏈結串列的順序依次恢復每個 Hook 的狀態。由於 mountActionState 按照固定順序建立了三個 Hook（stateHook → pendingStateHook → actionQueueHook），updateActionState 必須以相同的順序恢復它們。如果順序不一致，React 會拋出「Hooks 順序錯誤」的例外。

updateActionStateImpl 還會處理一個重要的邊界情況：Action 函式的更新。如果元件重新渲染時傳入了不同的 action 函式，updateActionStateImpl 會更新 actionQueue.action 的參照，確保後續的 dispatch 使用最新的 action 函式。這種「函式參照更新」的模式在 React 內部很常見，useEffect 和 useCallback 也採用了類似的策略。

八、架構全景：useActionState 在 React 19 生態中的位置

理解了 useActionState 的內部實作後，讓我們把它放到 React 19 的整體架構中來看。

在這個架構圖中，我們可以看到 useActionState 處於一個承上啟下的關鍵位置：

向上，它為開發者提供了簡潔的 API，隱藏了非同步狀態管理的複雜性。開發者只需要定義 Action 函式和初始狀態，剩下的交給框架。

向下，它依賴 useTransition 的排程能力來管理更新的優先級，依賴 Reconciler 來處理新舊狀態的差異，依賴 Committer 來將變更套用到 DOM。

橫向，它與 useOptimistic 和 useFormStatus 形成互補。useOptimistic 負責在 Action 執行期間顯示樂觀的 UI 狀態，useFormStatus 負責在表單子元件中存取父層表單的提交狀態。三者配合使用，可以建構出完整的表單互動體驗。

與 Server Actions 的整合是 useActionState 最重要的架構特性之一。當 Action 函式是一個 Server Action（透過 "use server" 指令標記的函式）時，useActionState 能夠在伺服器渲染階段就執行 Action 並將結果包含在初始 HTML 中。這意味著使用者在頁面載入時就能看到 Action 的結果，而不需要等待客戶端 JavaScript 載入和執行。這種「伺服器優先」的策略是 React 19 全端架構的核心優勢。

九、舉一反三：從原始碼推導行為

深入理解原始碼的最大價值在於：我們可以從實作推導出行為，而不是死記硬背 API 文件。 讓我們用幾個實際情境來驗證這一點。

9.1 快速連續點擊：佇列的順序保證

jsx 体验AI代码助手 代码解读复制代码function Counter() {
  const [count, dispatch, isPending] = useActionState(
    async (prev, delta) => {
      await new Promise(r => setTimeout(r, 1000));
      return prev + delta;
    },
    0
  );

  return (
    <div>
      <p>Count: {count}</p>
      <p>Pending: {isPending ? 'yes' : 'no'}</p>
      <button onClick={() => startTransition(() => dispatch(1))}>+1</button>
    </div>
  );
}

快速點擊兩次 "+1"，兩次 dispatch 會被依次加入循環佇列。第一個 Action 完成後（count 變為 1），第二個 Action 才開始執行（基於 prevState=1，結果為 2）。isPending 在整個過程中保持 true。

這個行為完全可以從原始碼推導出來：dispatchActionState 將每個 dispatch 包裝為一個 ActionNode 並加入循環佇列，onActionSuccess 在當前 Action 完成後遞迴呼叫 runActionStateAction 執行下一個。佇列的 FIFO 順序保證了 Action 的執行順序與 dispatch 的呼叫順序一致。

9.2 錯誤傳播：快速失敗的連鎖效應

jsx 体验AI代码助手 代码解读复制代码function Form() {
  const [state, formAction, isPending] = useActionState(
    async (prev, formData) => {
      const name = formData.get('name');
      if (!name) throw new Error('Name is required');
      return { submitted: true, name };
    },
    { submitted: false, name: '' }
  );

  return (
    <ErrorBoundary fallback={<p>Something went wrong</p>}>
      <form action={formAction}>
        <input name="name" />
        <button disabled={isPending}>Submit</button>
      </form>
    </ErrorBoundary>
  );
}

當 Action 擲出例外時，onActionError 會將 actionQueue.action 設為 null，阻止後續排隊的 Action 執行。錯誤會沿 Fiber 樹向上傳播，直到被最近的 Error Boundary 捕獲。同時，isPending 會被重設為 false，確保 UI 不會永久卡在 loading 狀態。

9.3 Transition 約束：為什麼必須在 Transition 中呼叫？

如果直接呼叫 dispatch 而不包裹在 startTransition 中，且不透過 <form action> 傳遞，React 會拋出錯誤：

javascript 体验AI代码助手 代码解读复制代码An async function with useActionState was called outside of a transition.

從原始碼可以理解這個約束的原因：isPending 的正確性依賴於 dispatchOptimisticSetState，而這個函式需要在 Transition 上下文中才能正確工作。沒有 Transition 上下文，React 無法追蹤 pending 狀態的變化，也無法正確地將狀態更新標記為低優先級。這不是一個任意的限制，而是架構上的必然要求。

9.4 與 useReducer 的對比：何時選擇哪個？

維度useReduceruseActionState狀態計算純同步 reducer可以是非同步函式更新觸發dispatch({type: 'X'})``dispatch(payload)Pending 追蹤需要手動實作內建 isPending錯誤處理在 reducer 中處理自動傳播到 Error Boundary佇列管理無（每次 dispatch 立即執行）內建順序佇列適用場景複雜的同步狀態邏輯非同步 Action、表單提交、資料變更一個實用的判斷標準：如果我們的狀態更新涉及 I/O 操作（網路請求、資料庫寫入、檔案讀寫），使用 useActionState；如果只是純計算邏輯，使用 useReducer。

十、設計模式提煉：從 useActionState 學到的工程智慧

10.1 組合模式（Composition over Inheritance）

useActionState 沒有實作一套全新的狀態管理機制，而是組合了三個既有的基礎 Hook（useState、useState、useRef）來建構更高階的抽象。這種「用簡單的積木搭建複雜的建築」的思路，是 React Hooks 體系的核心設計原則。它告訴我們：好的 API 設計不是發明新的基礎語彙，而是在正確的抽象層級上組合既有的語彙。

10.2 關注點分離（Separation of Concerns）

三個 Hook 各自管理一個獨立的關注點：狀態、pending 追蹤、佇列排程。它們透過閉包和參照相互溝通，但各自的生命週期是獨立的。這種分離使得每個部分都可以獨立測試和優化，也使得整個系統的複雜度被控制在可管理的範圍內。

10.3 Thenable 協議優於 Promise API

useActionState 檢查 then 方法而非 instanceof Promise，這個設計選擇體現了「協議優於實作」的工程原則。Thenable 是一個更輕量的協議，任何實作了 then 方法的物件都可以參與 React 的非同步系統，不需要依賴特定的 Promise 實作。這種設計在 React 的 Suspense、Transition 等特性中一以貫之。

10.4 快速失敗與優雅降級

onActionError 中的「清空佇列」策略是一種快速失敗模式。在分散式系統和並發程式設計中，快速失敗是一種重要的設計原則——當偵測到不可恢復的錯誤時，立即停止所有後續操作，而不是讓錯誤在系統中級聯傳播。useActionState 將這個原則應用到了前端狀態管理中。

十一、總結：從實作細節到設計哲學

回顧 useActionState 的完整實作，我們可以看到四個層次的設計智慧：

第一層：API 設計的簡潔性。 三個回傳值 [state, dispatch, isPending] 覆蓋了 Action 驅動狀態變更的所有需求，沒有多餘的設定項，沒有複雜的選項物件。好的 API 就像好的數學公式——簡潔，但蘊含豐富的資訊。

第二層：資料結構的精巧性。 循環鏈結串列實現 O(1) 的佇列操作，Thenable 模式實現細粒度的非同步追蹤，ActionNode 的狀態機設計確保了生命週期的清晰可控。這些資料結構的選擇不是隨意的，而是針對具體問題的最佳解。

第三層：架構整合的一致性。 useActionState 不是孤立存在的——它與 useTransition 共享底層機制，與 Server Components 無縫整合，與 <form action> 形成完整的表單解決方案。這種「在正確的抽象層級上保持一致性」的設計，是框架級 API 和函式庫級 API 的本質差別。

第四層：設計哲學的前瞻性。 從 useFormState 到 useActionState 的改名，從「資料驅動」到「意圖驅動」的範式轉變，React 團隊正在建構一個以 Action 為核心的宣告式副作用體系。useActionState 是這個體系的關鍵拼圖——它不僅僅是一個表單 Hook，而是 React 對「如何在 UI 框架中優雅地處理副作用」這個根本性問題的回答。

作為工程師，從優秀的框架原始碼中學習的不僅僅是實作技巧，更是如何在簡潔性和表達力之間找到平衡，如何在效能和正確性之間做出取捨，如何設計出既能解決當下問題又能適應未來演進的抽象。這些才是真正值得反覆品味的設計智慧。

本文基於 React 19 原始碼（packages/react-reconciler/src/ReactFiberHooks.js）分析，涉及的內部 API 可能隨版本更新而變化。建議結合 React GitHub 儲存庫的最新程式碼對照閱讀。

原文出處：https://juejin.cn/post/7636230868706623528