# Frontend Data Flow

> 前端数据流与状态管理规范。涵盖 TanStack Query (React Query) 的使用模式、Query Keys 结构、API SDK 集成以及交互反馈标准。 Use when this capability is needed.

- Skill: `tomevault-io/frontend-data-flow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/frontend-data-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/frontend-data-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/frontend-data-flow

---


## 数据获取规范 (TanStack Query)

为了保持前端状态管理的一致性和可维护性，所有异步数据操作必须遵循以下模式。

### 1. 钩子封装 (Custom Hooks)
- 所有的 `useQuery` 和 `useMutation` 必须封装在 `src/shared/hooks/` 目录下的专用文件中（如 `use-posts.ts`, `use-categories.ts`）。
- 禁止在页面组件（Page）或 UI 组件中直接编写复杂的 `queryFn` 逻辑。

### 2. 查询键管理 (Query Keys)
- 使用一致的数组格式：`['资源名', '操作/范围', ...标识符]`。
  - 例如：`['posts', 'me', postType]` (我创作的文章)
  - 例如：`['posts', 'detail', id]` (文章详情)
- 这种层次化的 Key 结构便于使用 `invalidateQueries` 进行批量刷新。

### 3. API SDK 集成
- 必须使用 `src/shared/api/generated` 中自动生成的 SDK 函数。
- 严禁使用原生的 `fetch` 或 `axios` 直接调用后端接口（SSR 场景除外，见 ARCHITECTURE.md）。
- 示例：
  ```typescript
  queryFn: () => getMyPosts({ query: { post_type: type } })
  ```

### 4. 交互与反馈标准
- **成功反馈**: 在 `Mutation` 的 `onSuccess` 回调中使用 `sonner` 库的 `toast.success()` 提供反馈。
- **错误处理**: 统一在 `onError` 中使用 `toast.error()` 展示后端返回的错误信息。
- **数据同步**: 在执行修改操作（Create/Update/Delete）成功后，必须调用 `queryClient.invalidateQueries` 刷新相关的查询缓存。

### 5. 加载状态
- 在 Page 层级处理整体的 `isLoading` 状态，配合 `src/components/ui/` 中的 `Loader` 或 `Skeleton` 组件。

## 注意事项
- 尽量通过 `Promise` 链式调用或 `async/await` 保持逻辑清晰。
- 对于不经常变动的数据（如文章类型列表），设置适当的 `staleTime: Infinity` 以减少冗余请求。

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/sumanin5) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->