前端工程化实践：用 ADR 规范架构决策与项目文档治理

# 0003. 使用 TanStack Query 替代 Redux 管理服务端状态

- **状态**：已接受 (Accepted)
- **日期**：2024-03-15
- **决策人**：一步梅、前端基础组件小组

## 背景 (Context)
当前项目中，我们使用 Redux Toolkit + createAsyncThunk 来处理所有 API 请求和缓存。
随着业务复杂度增加，暴露了以下问题：
1. 样板代码过多：每个接口都需要定义 Slice、Thunk、Pending/Fulfilled/Rejected 状态。
2. 缓存失效与轮询逻辑复杂：在多标签页同步和数据失效刷新场景下，手写缓存逻辑极易出现 UI 与数据不一致的 Bug。
3. 团队成员经常把「服务端返回的临时数据」和「真正的全局客户端状态（如主题、当前登录用户信息）」混在同一个 Store 里。

## 决策 (Decision)
我们决定引入 `TanStack Query (React Query) v5` 来专门管理**服务端状态（Server State）**，原有的 `Redux Toolkit` 仅保留用于管理纯粹的**客户端全局状态（Client State）**。

执行原则：
1. 所有 GET 请求的列表、详情数据，必须封装为自定义 Hook 并使用 `useQuery`。
2. 涉及新增、修改、删除的操作，统一使用 `useMutation` 并触发相关的 Query Key 失效。
3. 禁止再将接口返回的业务实体数据手动同步到 Redux 中。

## 替代方案 (Alternatives Considered)
- **方案 A：继续沿用 Redux Toolkit + RTK Query**
  - 未采纳原因：RTK Query 学习曲线稍陡，团队对 TanStack Query 的 Hooks API 更熟悉，且后者在 DevTools 调试和离线缓存方面更灵活。
- **方案 B：SWR**
  - 未采纳原因：SWR 功能相对轻量，但在复杂的 Mutation 联动和分页缓存策略上，TanStack Query 提供的工具链更完善。

## 后果 (Consequences)
### 正面影响
- 减少约 40% 的数据请求相关样板代码。
- 自动获得开箱即用的窗口聚焦重新拉取、请求去重和后台静默更新能力。
- 职责清晰：Server State 归 TanStack Query，Client State 归 Redux。

### 负面影响 / 成本
- 引入了新的依赖包（打包体积增加约 13KB Gzip）。
- 存量代码需要分阶段迁移，在过渡期内项目中会同时存在两种数据获取方式（预计在 Q2 迭代中全部收敛）。

my-frontend-project/
├── docs/
│   └── adr/
│       ├── 0001-record-architecture-decisions.md
│       ├── 0002-adopt-pnpm-and-monorepo.md
│       └── 0003-use-tanstack-query-for-server-state.md
├── src/
├── package.json
└── README.md

# 安装轻量管理工具（例如通过 npm）
npm install -g adr-log

# 或者在 package.json 里写一个极简脚本
# 运行 npm run adr:new -- "引入 Tailwind CSS" 自动生成编号和模版文件

┌──────────────────────────────────────────────┐
│  1. 入口层：README.md                          │  👉 快速上手、本地启动、基础规范指引
├──────────────────────────────────────────────┤
│  2. 决策层：ADR (docs/adr/*.md)               │  👉 技术选型历史、架构演进原因、权衡分析
├──────────────────────────────────────────────┤
│  3. 指南层：Guides (docs/guides/*.md)         │  👉 状态管理规范、组件封装指南、CI/CD 流程
├──────────────────────────────────────────────┤
│  4. 代码层：TS Types + TSDoc + Storybook      │  👉 组件 API、类型定义、交互 Demo（随代码走）
└──────────────────────────────────────────────┘