前情提要

在 Day 8 我們實作了 React Hook Form 與 Zod 驗證的進階應用，今天我們要在現有的 React Query 基礎上，實現更進階的資料管理模式。

在我們的 Kyo 系統中，React Query 已經實作，但我們可以進一步強化：

• 🔄 樂觀更新：即時 UI 回饋的進階實作
• 🚀 無緻表單體驗：表單與資料管理的深度整合
• 📊 智慧快取策略：根據業務場景優化效能
• 🔄 離線支援：網路不穩定時的降級

在我們的 OTP 服務應用中，進階特性的必要性體現在：

• 🔄 更智慧的快取管理：根據業務場景優化快取策略
• 🚀 樂觀更新體驗：即時 UI 回饋，提升使用者體驗
• 📝 表單與資料深度整合：模板管理與表單驗證的體驗
• 🌐 離線優先設計：網路不穩定時的降級體驗

現狀分析：我們的 React Query 實作

讓我們先檢視我們目前的 React Query 實作狀況：

✅ 目前實作：已有 React Query 基礎

// 目前的 OTP 頁面 (apps/kyo-dashboard/src/pages/otp.tsx)
export default function OtpPage() {
  const [lastResult, setLastResult] = useState<any>(null);

  // 已經使用 React Query hooks
  const { data: templates = [], isLoading: templatesLoading, error: templatesError } = useTemplates();
  const sendOtpMutation = useSendOtp();

  const form = useForm({
    initialValues: { phone: '', templateId: null },
    validate: {
      phone: (value) => {
        if (!value.trim()) return '請輸入手機號碼';
        if (!/^09\d{8}$/.test(value)) return '請輸入有效的台灣手機號碼';
        return null;
      }
    }
  });

  const handleSubmit = async (values) => {
    try {
      const result = await sendOtpMutation.mutateAsync({
        phone: values.phone,
        templateId: values.templateId || undefined
      });
      setLastResult(result);
      // 通知和錯誤處理已在 hook 中自動處理
    } catch (error) {
      console.error('Send OTP failed:', error);
    }
  };
}

🚀 目前的作法與優化空間

已有作法：

1. ✅ 基本 React Query 實作：狀態管理已統一化
2. ✅ 智慧錯誤處理：重試策略和通知系統已整合
3. ✅ 快取管理：基本的 5 分鐘快取策略
4. ✅ DevTools 整合：可快速除錯

優化方向：

1. 🔴 模擬 API 限制：目前使用模擬資料，未來連接真實後端
2. 🔴 缺少樂觀更新：在需要即時回饋的場景中可以優化
3. 🔴 表單整合不夠深入：表單驗證與資料管理可以更緊密整合
4. 🔴 離線支援不足：網路不穩定時的體驗可以提升

解決方案：升級到 React Query

第 1 步：安裝與設定

cd apps/kyo-dashboard
pnpm add @tanstack/react-query @tanstack/react-query-devtools

第 2 步：建立 Query Client 設定

// apps/kyo-dashboard/src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // 資料被認為是新鮮的時間（5分鐘）
      staleTime: 5 * 60 * 1000,
      // 快取時間（10分鐘）
      gcTime: 10 * 60 * 1000,
      // 錯誤重試策略
      retry: (failureCount, error: any) => {
        // 4xx 錯誤不重試
        if (error?.status >= 400 && error?.status < 500) {
          return false;
        }
        // 最多重試 3 次
        return failureCount < 3;
      },
      // 重新聚焦時重新取得
      refetchOnWindowFocus: false,
      // 網路重新連線時重新取得
      refetchOnReconnect: true,
    },
    mutations: {
      // 預設重試一次
      retry: 1,
    },
  },
});

第 3 步：整合到應用程式

// apps/kyo-dashboard/src/App.tsx
import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { queryClient } from './lib/queryClient';

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MantineProvider theme={theme}>
        <ModalsProvider>
          <Notifications position="top-right" />
          <BrowserRouter>
            <DashboardLayout>
              <Routes>
                <Route path="/" element={<OtpPage />} />
                <Route path="/verify" element={<VerifyPage />} />
                <Route path="/templates" element={<TemplatesPage />} />
                <Route path="/analytics" element={<div>數據分析頁面（即將推出）</div>} />
              </Routes>
            </DashboardLayout>
          </BrowserRouter>
          {/* 開發時顯示 React Query DevTools */}
          <ReactQueryDevtools initialIsOpen={false} />
        </ModalsProvider>
      </MantineProvider>
    </QueryClientProvider>
  );
}

第 4 步：建立智慧的 API Hooks

// apps/kyo-dashboard/src/hooks/useTemplates.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { notifications } from '@mantine/notifications';

interface Template {
  id: number;
  name: string;
  content: string;
  isActive: boolean;
  createdAt?: string;
  updatedAt?: string;
}

// 模擬 API 呼叫（之後可以替換為真實的 API）
const templatesApi = {
  async getAll(): Promise<Template[]> {
    // 模擬網路延遲
    await new Promise(resolve => setTimeout(resolve, 500));

    return [
      {
        id: 1,
        name: 'default',
        content: '您的驗證碼：{code}，請於 5 分鐘內輸入。',
        isActive: true,
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
      },
      {
        id: 2,
        name: 'urgent',
        content: '【緊急】驗證碼：{code}，限時 5 分鐘有效！',
        isActive: true,
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
      },
      {
        id: 3,
        name: 'welcome',
        content: '歡迎使用 Kyo 系統！您的驗證碼：{code}',
        isActive: false,
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
      },
    ];
  },

  async create(template: Omit<Template, 'id' | 'createdAt' | 'updatedAt'>): Promise<Template> {
    await new Promise(resolve => setTimeout(resolve, 300));
    return {
      ...template,
      id: Date.now(),
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    };
  },
};

// ✅ 查詢模板列表
export function useTemplates() {
  return useQuery({
    queryKey: ['templates'],
    queryFn: templatesApi.getAll,
  });
}

// ✅ 創建模板
export function useCreateTemplate() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: templatesApi.create,
    onSuccess: (newTemplate) => {
      // 智慧更新快取
      queryClient.setQueryData<Template[]>(['templates'], (old) => {
        return old ? [...old, newTemplate] : [newTemplate];
      });

      notifications.show({
        title: '成功',
        message: '模板建立成功！',
        color: 'green',
      });
    },
    onError: (error: any) => {
      notifications.show({
        title: '錯誤',
        message: `建立模板失敗：${error.message || '未知錯誤'}`,
        color: 'red',
      });
    },
  });
}

第 5 步：OTP API Hooks

// apps/kyo-dashboard/src/hooks/useOtp.ts
import { useMutation } from '@tanstack/react-query';
import { notifications } from '@mantine/notifications';

interface OtpSendRequest {
  phone: string;
  templateId?: number;
}

interface OtpSendResponse {
  success: boolean;
  msgId: string;
  status: string;
  phone: string;
}

// 模擬 API
const otpApi = {
  async send(data: OtpSendRequest): Promise<OtpSendResponse> {
    await new Promise(resolve => setTimeout(resolve, 800));

    if (!data.phone || !/^09\d{8}$/.test(data.phone)) {
      throw new Error('請輸入有效的台灣手機號碼');
    }

    return {
      success: true,
      msgId: `MSG${Date.now()}`,
      status: 'sent',
      phone: data.phone,
    };
  },
};

// ✅ 發送 OTP
export function useSendOtp() {
  return useMutation({
    mutationFn: otpApi.send,
    onSuccess: (data) => {
      notifications.show({
        title: '驗證碼已發送',
        message: `訊息 ID: ${data.msgId}`,
        color: 'green',
      });
    },
    onError: (error: any) => {
      notifications.show({
        title: '發送失敗',
        message: error.message || '發送驗證碼時發生錯誤',
        color: 'red',
      });
    },
  });
}

✅ 升級後：簡潔的元件

// 升級後的 OTP 頁面
export default function OtpPage() {
  const [lastResult, setLastResult] = useState<any>(null);

  // React Query hooks：一行搞定所有狀態管理
  const { data: templates = [], isLoading: templatesLoading, error: templatesError } = useTemplates();
  const sendOtpMutation = useSendOtp();

  const form = useForm({
    initialValues: { phone: '', templateId: null },
    validate: {
      phone: (value) => {
        if (!value.trim()) return '請輸入手機號碼';
        if (!/^09\d{8}$/.test(value)) return '請輸入有效的台灣手機號碼';
        return null;
      }
    }
  });

  const handleSubmit = async (values: { phone: string; templateId: number | null }) => {
    try {
      const result = await sendOtpMutation.mutateAsync({
        phone: values.phone,
        templateId: values.templateId || undefined
      });
      setLastResult(result);
      // 通知和錯誤處理都已經在 hook 中自動處理了！
    } catch (error) {
      console.error('Send OTP failed:', error);
    }
  };

  // 智慧的錯誤處理
  if (templatesError) {
    return (
      <Alert color="red" title="載入模板失敗" icon={<IconAlertCircle size="1rem" />}>
        無法載入簡訊模板，但您仍可以使用預設模板發送 OTP。
      </Alert>
    );
  }

  const templateOptions = templates
    .filter(t => t.isActive)
    .map(t => ({ value: t.id.toString(), label: t.name }));

  return (
    <Stack>
      <Card withBorder>
        <form onSubmit={form.onSubmit(handleSubmit)}>
          <Stack>
            <TextInput
              label="手機號碼"
              placeholder="09XXXXXXXX"
              required
              {...form.getInputProps('phone')}
            />

            <Select
              label="簡訊模板"
              placeholder={templatesLoading ? "載入模板中..." : "選擇模板（可選）"}
              description="不選擇將使用預設模板"
              data={templateOptions}
              value={form.values.templateId?.toString() || null}
              onChange={(value) => form.setFieldValue('templateId', value ? parseInt(value) : null)}
              clearable
              disabled={templatesLoading || sendOtpMutation.isPending}
              rightSection={templatesLoading ? <Loader size="xs" /> : undefined}
            />

            <Button
              type="submit"
              loading={sendOtpMutation.isPending}
              leftSection={<IconMessages size="1rem" />}
              disabled={!form.isValid()}
            >
              發送驗證碼
            </Button>
          </Stack>
        </form>
      </Card>
    </Stack>
  );
}

🚀 升級帶來的實際好處

1. 程式碼大幅簡化

// 升級前：需要管理多個狀態
const [templates, setTemplates] = useState<Template[]>([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);

useEffect(() => {
  async function loadTemplates() {
    setLoading(true);
    try {
      const data = await getTemplates('');
      setTemplates(data);
    } catch (e) {
      setError(e.message);
    } finally {
      setLoading(false);
    }
  }
  loadTemplates();
}, []);

// 升級後：只需一行
const { data: templates = [], isLoading, error } = useTemplates();

2. 智慧快取與同步

當你在模板管理頁面新增一個模板後，OTP 頁面的模板選項會自動更新，無需重新載入頁面！

// 在模板管理頁面
const createMutation = useCreateTemplate();

const handleCreate = async (template) => {
  await createMutation.mutateAsync(template);
  // OTP 頁面會自動顯示新模板，因為快取已經更新了！
};

3. 自動錯誤重試與恢復

// 在 queryClient 設定中，我們定義了重試邏輯：
retry: (failureCount, error: any) => {
  // 4xx 錯誤（用戶端錯誤）不重試
  if (error?.status >= 400 && error?.status < 500) {
    return false;
  }
  // 網路錯誤或 5xx 錯誤最多重試 3 次
  return failureCount < 3;
}

4. 開發者體驗提升

React Query DevTools 提供了強大的除錯功能：

// 在 App.tsx 中加入
<ReactQueryDevtools initialIsOpen={false} />

這讓你可以即時觀察：

• 🔍 所有活躍的查詢和變更狀態
• ⏱️ 快取資料的有效期限
• 🔄 背景重新取得的時機
• 📊 詳細的查詢效能指標

效能提升對比

立即體驗升級效果

1. 啟動開發伺服器：

   cd apps/kyo-dashboard
   pnpm dev
   

2. 開啟瀏覽器訪問：http://localhost:5173

3. 觀察效果：

   • 打開 React Query DevTools（右下角圖示）
   • 在模板管理頁面新增模板
   • 切換到 OTP 頁面，新模板會立即出現
   • 觀察快取狀態和背景同步

實際檔案結構

升級後我們的專案檔案結構如下：

apps/kyo-dashboard/src/
├── lib/
│   └── queryClient.ts          # React Query 全域設定
├── hooks/
│   ├── useTemplates.ts         # 模板管理 hooks
│   └── useOtp.ts              # OTP 相關 hooks
├── pages/
│   ├── otp.tsx                # 升級後的 OTP 頁面
│   ├── templates.tsx          # 升級後的模板管理頁面
│   └── verify.tsx             # 驗證頁面
└── App.tsx                    # 整合 QueryClientProvider

為什麼要使用React Query

1. 狀態管理的思維轉變

// ❌ 舊思維：我需要管理這個資料的狀態
const [data, setData] = useState();
const [loading, setLoading] = useState();
const [error, setError] = useState();

// ✅ 新思維：我只需要描述我要什麼資料
const { data, isLoading, error } = useQuery({
  queryKey: ['myData'],
  queryFn: fetchMyData
});

2. 快取是資料管理的核心

React Query 把快取放在第一位，這改變了我們對資料流的思考方式：

• 資料不再是「元件的私有狀態」
• 而是「應用程式的共享資源」
• 任何地方都可以安全地消費這些資料

3. 宣告式的副作用管理

// 當資料變更時，相關的快取會自動更新
const createMutation = useMutation({
  mutationFn: createTemplate,
  onSuccess: (newTemplate) => {
    // 這會讓所有使用 templates 查詢的地方自動更新
    queryClient.setQueryData(['templates'], old => [...old, newTemplate]);
  }
});

對比分析：為什麼 React Query 更勝一籌？

傳統方式 vs React Query

// ❌ 傳統方式：重複的樣板代碼
function TraditionalComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetchData()
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data}</div>;
}

// ✅ React Query：專注於業務邏輯
function ModernComponent() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['data'],
    queryFn: fetchData
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data}</div>;
}

快取機制比較

// ❌ 傳統方式：沒有快取，每次都重新請求
function Page1() {
  useEffect(() => {
    fetchTemplates().then(setTemplates); // API 請求
  }, []);
}

function Page2() {
  useEffect(() => {
    fetchTemplates().then(setTemplates); // 又一次 API 請求
  }, []);
}

// ✅ React Query：智慧快取，一次請求到處使用
function Page1() {
  const { data } = useTemplates(); // 第一次請求
}

function Page2() {
  const { data } = useTemplates(); // 從快取讀取，無需請求
}

今日成果

通過升級到 React Query，我們的應用現在具備了：

✅ 智慧快取機制：自動管理資料的新鮮度和過期時間
✅ 統一狀態管理：所有 API 請求狀態的一致處理
✅ 自動錯誤重試：網路錯誤時的智慧重試機制
✅ 背景同步：在使用者不察覺的情況下保持資料最新
✅ 開發者工具：強大的除錯和監控功能
✅ 效能大幅提升：減少不必要的網路請求和重新渲染