Community程式設計與開發github.com

React Data Hook

用於在 React + TypeScript 元件中擷取伺服器資料 — 編寫或審查具有型別回應、載入/錯誤狀態、請求取消且在卸載後不更新狀態的自訂 Hook,或取代臨時的 useEffect + fetch。

React Data Hook 是什麼?

這項技能提供了一個經過實戰檢驗的 playbook,用於在 React 中正確擷取資料,重點關注型別安全、請求取消和全面的狀態管理。它倡導將資料擷取邏輯封裝在自訂 Hook 中,以保持元件的宣告式特性,強制要求對 loading、error 和 data 三種狀態進行建模,並使用 AbortController 來取消卸載或輸入變更時的進行中請求,從而防止常見的競爭條件錯誤。該技能包含一個零依賴的基礎 useFetch Hook 示範,使用鑑別聯合(discriminated union)來使無效狀態無法表示,並提供了一個逐步檢查清單。它還引導開發者優先使用 TanStack Query 或 SWR 等成熟資料庫,但會在專案尚未導入這些函式庫且不需要引入新依賴時,提供一個可靠的替代方案。

相容平台~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/karthik1210100/agent-skills/tree/main/skills/react-data-hook

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

React Data Hook 是做什麼的?

一份關於在 React 中正確擷取伺服器資料的 playbook:具備型別、可取消,且每次都能妥善處理載入與錯誤狀態。

原則

  • 元件應該渲染狀態,而非編排擷取。將擷取邏輯放在 Hook 中,讓元件保持宣告式。
  • 總是建模三種狀態 — loading、error、data。永遠不要假設請求一定成功。
  • 在元件卸載或輸入變更時取消進行中的請求。一個延遲的回應更新了已卸載或過時的 UI,會造成真實的錯誤(畫面閃爍、顯示錯誤資料、React 警告),而非理論上的問題。
  • 為回應加上型別。一個回傳 any 的 Hook 只是把 bug 往後推。

優先:當專案已有真實資料庫時,請使用它

如果專案已經使用了 TanStack Query (React Query) 或 SWR,就使用它們 — 不要在一旁自己手寫擷取邏輯。它們免費提供了快取、去重、重試和取消功能:

const { data, isLoading, error } = useQuery({
  queryKey: ["article", id],
  queryFn: ({ signal }) => fetchArticle(id, signal),
});

僅在專案沒有任何資料層且你不想引入一個時,才建立下面的 Hook。

基礎型別 Hook(零依賴)

// useFetch.ts
import { useEffect, useState } from "react";

type State<T> =
  | { status: "loading"; data: null; error: null }
  | { status: "success"; data: T; error: null }
  | { status: "error"; data: null; error: Error };

export function useFetch<T>(url: string, init?: RequestInit): State<T> {
  const [state, setState] = useState<State<T>>({
    status: "loading",
    data: null,
    error: null,
  });

  useEffect(() => {
    const controller = new AbortController();
    setState({ status: "loading", data: null, error: null });

    fetch(url, { ...init, signal: controller.signal })
      .then(async (res) => {
        if (!res.ok) throw new Error(`Request failed: ${res.status}`);
        return (await res.json()) as T;
      })
      .then((data) => setState({ status: "success", data, error: null }))
      .catch((err: unknown) => {
        if (err instanceof DOMException && err.name === "AbortError") return; // 預期中的情況
        setState({
          status: "error",
          data: null,
          error: err instanceof Error ? err : new Error(String(err)),
        });
      });

    return () => controller.abort(); // 在卸載或 url 變更時取消
  }, [url]); // 僅在請求標識變更時重新執行

  return state;
}

為什麼這樣寫是正確的:

  • 鑑別聯合(discriminated union) 讓非法狀態無法表示 — 你在 loading 時無法讀取 data。
  • AbortController 加上 cleanup 回傳,在開始新請求前取消前一個請求,消滅了經典的競爭條件(回應以錯誤順序解析)。
  • AbortError 分支保持靜默,因此正常的取消永遠不會顯示錯誤。

使用它 — 渲染全部三種狀態

function Article({ id }: { id: string }) {
  const result = useFetch<ArticleDto>(`/api/v1/articles/${id}`);

  if (result.status === "loading") return <Spinner aria-label="Loading article" />;
  if (result.status === "error") return <ErrorBanner message={result.error.message} />;

  return <ArticleView article={result.data} />;
}

渲染載入與錯誤分支並非可選的修飾 — 這是空白畫面與可用畫面之間的差異。

此技能可防止的常見錯誤

  • useEffect(() => { fetch(url).then(r => r.json()).then(setData) }, []) — 沒有載入狀態、沒有錯誤處理、沒有取消,且 [] 忽略了變更的 url。
  • 將不穩定的值(物件/陣列字面量、內聯的 init)放入依賴陣列,導致無限重新擷取循環。請對它們進行記憶化(memoize)或依賴於基本型別。
  • setData 在卸載後觸發。cleanup 中的 abort() 讓延遲的 .then 在 AbortError 上短路結束。
  • 忽略非 2xx 的回應 — fetch 僅在網路故障時拒絕,因此你必須自己檢查 res.ok。

完成前的檢查清單

  • 擷取邏輯位於 Hook 中;元件僅讀取狀態。
  • Loading、error 和 data 都已表示並已渲染。
  • 回應已加上型別(沒有 any);非 2xx 的回應已被轉換為錯誤。
  • 使用 AbortController 在卸載和輸入變更時取消請求。
  • 依賴陣列僅包含定義請求的穩定值。
  • 如果專案已有 React Query / SWR,則優先使用它們,而非此 Hook。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能