前端状态管理
Purpose
为前端状态确定清晰归属，避免全局 store 膨胀、重复缓存和派生状态同步错误。
Procedure
1. 先分类状态来源
不要先选 Redux、Zustand、Pinia 或 Context。先把每个状态标到唯一归属，再决定工具。
| 状态类型 | 典型例子 | 默认归属 |
|---|---|---|
| 本地 UI 状态 | 弹窗开关、tab、展开行、hover 编辑态 | 组件内 state / ref |
| 表单状态 | 输入值、脏字段、校验错误、提交中 | 表单库或表单组件 |
| 服务端状态 | 列表、详情、分页结果、远程错误 | 请求缓存库 |
| URL 状态 | 搜索词、筛选、排序、页码、选中 tab | 路由参数 / search params |
| 全局客户端状态 | 登录用户、主题、权限快照、购物车草稿 | 全局 store |
| 浏览器持久化状态 | 跨刷新保留的草稿、偏好、离线队列 | 存储层 + 状态适配器 |
type ReportsStateMap = {
search: "url";
selectedReportId: "url";
reports: "server-state-cache";
isFilterPanelOpen: "local-ui";
draftColumns: "browser-persistence";
};
2. 保持最小状态
可从 props、server state、URL 或已有 state 推导出来的值，不要另存一份。
interface Invoice {
id: string;
status: "draft" | "sent" | "paid";
}
function InvoiceList({ invoices }: { invoices: Invoice[] }) {
const paidInvoices = invoices.filter((invoice) => invoice.status === "paid");
return <span>{paidInvoices.length}</span>;
}
3. 选择 React 全局状态方案
React 中优先本地化和组合；只有跨页面、跨 feature 或需要统一动作时才引入全局 store。
import { create } from "zustand";
interface WorkspaceState {
activeWorkspaceId: string | null;
setActiveWorkspaceId: (workspaceId: string) => void;
}
export const useWorkspaceStore = create<WorkspaceState>((set) => ({
activeWorkspaceId: null,
setActiveWorkspaceId: (activeWorkspaceId) => set({ activeWorkspaceId }),
}));
决策顺序：
- 只在一个组件或一个小子树使用：
useState/useReducer。 - 低频全局配置或依赖注入：Context。
- 中等复杂业务状态：Zustand 或 Jotai，按仓库现有选型优先。
- 大型应用、严格动作流、审计或时间旅行调试：Redux Toolkit。
- 远程数据：使用数据获取 skill 管理 query key、缓存和失效策略。
4. 选择 Vue 全局状态方案
Vue 3 中，局部跨层级传递使用 provide/inject；全局业务状态使用 Pinia 或项目既有 store。
import { computed, readonly, ref } from "vue";
import { defineStore } from "pinia";
export const useSessionStore = defineStore("session", () => {
const userId = ref<string | null>(null);
const isSignedIn = computed(() => userId.value !== null);
function signIn(nextUserId: string) {
userId.value = nextUserId;
}
return {
userId: readonly(userId),
isSignedIn,
signIn,
};
});
5. 明确状态边界和迁移步骤
重构状态时先做状态清单，再逐步移动读写入口。每一步都应保持行为可验证。
interface StateMigrationItem {
name: string;
currentOwner: "component" | "context" | "store" | "query-cache" | "url";
targetOwner: "component" | "context" | "store" | "query-cache" | "url";
verification: string;
}
const migrationPlan: StateMigrationItem[] = [
{
name: "dashboard filters",
currentOwner: "store",
targetOwner: "url",
verification: "refreshing the page preserves filters through search params",
},
];
Detailed References
需要 Store 形状示例、选择器模式、URL 状态同步、持久化适配器、SSR 边界或审查清单时，加载 references/state-patterns.md。
Constraints
- 不把服务端响应复制到全局 store；缓存、失效和重试归数据获取层。
- 不把表单每个字段提升到全局 store；跨步骤共享也优先由表单上下文或提交草稿适配器处理。
- 不用 Context 承载高频变化的大对象；会扩大重渲染范围。
- 持久化状态必须明确字段白名单、版本号、过期策略和敏感数据排除。
- SSR 场景不要在模块顶层创建带用户数据的单例 store。
Expected Output
产出状态归属清单、选型理由、store/API 边界和验证步骤。实现时应保留 loading/error/empty、刷新、回退、跨路由和权限变化等关键行为。