yuxuanhui
42 lines
1.9 KiB
Markdown
42 lines
1.9 KiB
Markdown
# Hook 与数据请求
|
|
|
|
## API 适配三件套
|
|
|
|
服务端数据按 feature 放置为 API 函数、query hook 和类型文件：
|
|
|
|
1. `features/system/api/system.types.ts` 定义 `SystemStatus`。
|
|
2. `features/system/api/system.api.ts:getSystemStatus` 调用 shared transport，并把 `AbortSignal` 传给 `fetch`。
|
|
3. `features/system/api/system.query.ts:useSystemStatus` 暴露 React Query hook，并使用 `systemStatusQueryKey`。
|
|
|
|
页面只调用 `useSystemStatus`，不直接调用 `fetch`。新增 feature 应保持同样分层。
|
|
|
|
```ts
|
|
export const systemStatusQueryKey = ["system", "status"] as const
|
|
|
|
export function useSystemStatus() {
|
|
return useQuery({
|
|
queryFn: ({ signal }) => getSystemStatus(signal),
|
|
queryKey: systemStatusQueryKey,
|
|
})
|
|
}
|
|
```
|
|
|
|
## React Query
|
|
|
|
- 服务器状态由 TanStack Query 管理；公共默认值在 `app/query-client.ts`（不跟随窗口刷新、失败重试 1 次、`staleTime` 30 秒）。
|
|
- query key 使用 `as const` 常量，避免页面散落字符串。
|
|
- 使用 query function 提供的 `signal` 支持取消请求；不要忽略它或在页面手写生命周期 fetch。
|
|
- 页面显式处理 `isPending`、`isError` 和 `data`，参照 `SystemStatusPage`。
|
|
|
|
## Hook 命名与副作用
|
|
|
|
- 自定义 hook 以 `use` 开头并表达资源或行为，例如 `useSystemStatus`、`useUiStore`。
|
|
- 纯数据 hook 不执行额外副作用；需要同步 DOM 的副作用集中在 `app/providers.tsx:ThemeEffect`，由 Zustand 主题驱动 `document.documentElement` 的 class。
|
|
- 不要把一个 hook 同时用作服务器缓存和 UI 偏好存储；两者分别使用 React Query 与 Zustand。
|
|
|
|
## 反模式
|
|
|
|
- 不要在组件中直接 `fetch`、重复设置 query key 或把响应复制到本地 `useState`。
|
|
- 不要用 Zustand 保存 API 响应以“共享”数据，也不要用 React Query 保存主题等本地偏好。
|
|
- 不要为了复用一次性的 `useEffect` 创建泛化 hook；先确认是否已有跨页面重复模式。
|