實戰範例 002：移除過度設計的 React 狀態管理與 Context 嵌套

在 React 開發中，開發者常有一種迷思：只要有跨組件的狀態傳遞需求，就必須引入 Context API，甚至是配置複雜的 useReducer 或外部狀態庫 (如 Redux / Zustand)。這種過度設計 (Over-engineering) 往往會帶來大量的樣板程式碼，並可能因為 Context 的非必要重繪 (Re-render) 而導致效能低落。

本實戰範例將展示如何使用 Ponytail 代理，將一個僅僅用於「商品列表篩選與排序」的過度設計狀態管理模組，重構成為僅有數十行的極簡版。

原始狀況：過度設計的狀態上下文 (約 180 行)

原始代碼中，為了讓表格篩選器（Filter Bar）與表格主體（Table Body）共享篩選與分頁狀態，作者設計了完整的 Context Provider 與 Reducer 機制，並將其拆分到多個檔案中。

以下是該狀態管理器的程式碼：

// src/context/FilterContext.tsx
import React, { createContext, useReducer, useContext } from 'react';

export interface FilterState {
  searchQuery: string;
  category: string;
  sortBy: string;
  page: number;
  pageSize: number;
}

type FilterAction =
  | { type: 'SET_SEARCH'; payload: string }
  | { type: 'SET_CATEGORY'; payload: string }
  | { type: 'SET_SORT'; payload: string }
  | { type: 'SET_PAGE'; payload: number }
  | { type: 'RESET' };

const initialFilterState: FilterState = {
  searchQuery: '',
  category: 'ALL',
  sortBy: 'price_asc',
  page: 1,
  pageSize: 10,
};

function filterReducer(state: FilterState, action: FilterAction): FilterState {
  switch (action.type) {
    case 'SET_SEARCH':
      return { ...state, searchQuery: action.payload, page: 1 };
    case 'SET_CATEGORY':
      return { ...state, category: action.payload, page: 1 };
    case 'SET_SORT':
      return { ...state, sortBy: action.payload };
    case 'SET_PAGE':
      return { ...state, page: action.payload };
    case 'RESET':
      return initialFilterState;
    default:
      return state;
  }
}

const FilterStateContext = createContext<FilterState | undefined>(undefined);
const FilterDispatchContext = createContext<React.Dispatch<FilterAction> | undefined>(undefined);

export const FilterProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [state, dispatch] = useReducer(filterReducer, initialFilterState);

  return (
    <FilterStateContext.Provider value={state}>
      <FilterDispatchContext.Provider value={dispatch}>
        {children}
      </FilterDispatchContext.Provider>
    </FilterStateContext.Provider>
  );
};

export function useFilterState() {
  const context = useContext(FilterStateContext);
  if (context === undefined) {
    throw new Error('useFilterState must be used within a FilterProvider');
  }
  return context;
}

export function useFilterDispatch() {
  const context = useContext(FilterDispatchContext);
  if (context === undefined) {
    throw new Error('useFilterDispatch must be used within a FilterProvider');
  }
  return context;
}

當我們在組件中使用時，必須外包一層 FilterProvider，並在篩選器與清單組件中分別呼叫兩個自定義 Hook。這使得每一次 searchQuery 的輸入都會觸發整個 Provider 底下所有組件的重繪，造成輸入框打字卡頓。

⚡ 實戰對話錄：Ponytail 代理的極簡思維

人類： /ponytail-review src/context/FilterContext.tsx

我只是想在同一個頁面內共享篩選商品的狀態，但這個 FilterContext 寫法太繁瑣了，打字時甚至有點 Lag。請幫我重構。

Ponytail 代理： 收到。正在檢視 FilterContext.tsx。

根據 7 階「必要才寫」階梯：

1. 第 1 階 YAGNI 檢查：此篩選狀態僅在此單一頁面（包含 FilterBar 與 ProductTable）內使用，根本不需要全域狀態或多層 Context 傳遞。
2. 第 4 階 平台功能優先 (Web API)：篩選、分頁狀態的最佳儲存媒介其實是 URL Query Parameters (搜尋參數)。使用 URL 作為狀態源有兩大好處：
   • 使用者可以直接複製連結分享當前的篩選結果給其他人，這是 Context 無法直接做到的。
   • 點擊瀏覽器的「上一頁」可以自然回退篩選條件。

🛡️ 安全防護保留規劃

在重構為 URL 參數驅動時，我將完整保留：

• page 與 pageSize 的數值安全檢查（防止負數或非數字導致的 API 崩潰）。
• 篩選參數的邊界清洗，防止 XSS 與無效字串輸入。

我建議完全刪除 FilterContext.tsx，改在頁面組件中使用簡單的原生 React Hooks 與 URL 狀態同步。是否同意？

人類： 同意，請提供極簡重構後的實作代碼。

重構後：URL 參數驅動的極簡篩選 (約 35 行)

Ponytail 代理建議直接廢除 Context，並將狀態交給 React 原生 useState 或瀏覽器內建 URLSearchParams。

以下是重構後的頁面組件：

// src/components/ProductPage.tsx
import React from 'react';

export const ProductPage: React.FC = () => {
  // 🛡️ 防禦性防護 (第 7 階)：從 URL 解析參數並進行邊界安全清洗
  const getParams = () => {
    if (typeof window === 'undefined') return { search: '', category: 'ALL', page: 1 };
    const params = new URLSearchParams(window.location.search);
    const page = Math.max(1, parseInt(params.get('page') || '1', 10)); // 防止 page <= 0
    return {
      search: (params.get('search') || '').trim().slice(0, 100), // 防止超長字串
      category: (params.get('category') || 'ALL').toUpperCase(),
      page: isNaN(page) ? 1 : page,
    };
  };

  const { search, category, page } = getParams();

  // 🛡️ 安全地更新 URL 狀態，無須任何複雜的 Action 傳遞 (第 4 階)
  const updateParam = (key: string, value: string) => {
    if (typeof window === 'undefined') return;
    const params = new URLSearchParams(window.location.search);
    if (value && value !== 'ALL') {
      params.set(key, value);
    } else {
      params.delete(key);
    }
    params.set('page', '1'); // 篩選條件改變時重置到第一頁
    
    // 使用瀏覽器原生 History API 進行無感跳轉 (免除 React Router 依賴)
    const newUrl = `${window.location.pathname}?${params.toString()}`;
    window.history.replaceState({ path: newUrl }, '', newUrl);
    
    // 觸發重新繪製
    window.dispatchEvent(new Event('popstate'));
  };

  return (
    <div className="product-container">
      <input
        type="text"
        placeholder="搜尋商品..."
        value={search}
        onChange={(e) => updateParam('search', e.target.value)}
        className="border p-2 rounded"
      />
      
      <select value={category} onChange={(e) => updateParam('category', e.target.value)} className="border p-2 ml-2">
        <option value="ALL">全部類別</option>
        <option value="ELECTRONICS">電子產品</option>
        <option value="BOOKS">圖書</option>
      </select>

      <p className="mt-4">當前搜尋條件: {search || '無'} | 類別: {category} | 頁碼: {page}</p>
    </div>
  );
};

📊 成果與效益分析

使用 /ponytail-gain 分析重構後的效果：