Bulletproof React 状态管理架构：五类状态的边界划分、方案选型与仓库源码实战解析

本篇技术指南围绕 Bulletproof React 架构文档中的状态管理章节（docs/state-management.md）展开，系统讲解其核心主张——不要把所有状态都塞进一个集中式全局 Store，而是按使用方式将状态划分为组件状态、应用状态、服务端缓存状态、表单状态与 URL 状态五类，分别采用不同的工具与模式管理。文中将以仓库中 apps/react-vite 示例应用的源码与配置为实证，逐一拆解每一类状态的判定标准、推荐选型与落地写法，读完你可以直接把这套分类思想与代码范式迁移到自己的 React 项目中。

一切从"分类"开始：为什么不能把所有状态放进同一个 Store

React 应用开发中最常见的一个陷阱，是开发者在全局状态管理库（Redux、Zustand 等）中存放一切数据——从服务端返回的用户列表、表单临时输入，到某个按钮是否展开，统统放进一个集中式仓库。文档给出的诊断非常直接：这会拖垮性能，也会让状态管理流程变得难以维护。

正确的做法是先给状态分类，每一类状态有不同的生命周期、作用域与访问频率，因此也应该有独立的存储位置与托管方式：

状态分类	典型用途	最佳存放位置	推荐工具	仓库中的示例文件
组件状态	仅单个组件关心的临时 UI 状态	组件内部	useState / useReducer	dashboard-layout.tsx
应用状态	全局弹窗、通知、主题等跨组件 UI 状态	尽量靠近使用组件的全局单例	Context + Hooks、Redux Toolkit、MobX、Zustand、Jotai、XState	notifications-store.ts
服务端缓存状态	从 API 获取、需要缓存/失效的远程数据	专用服务端缓存库	TanStack Query、SWR、Apollo Client、urql、RTK Query	get-discussions.ts
表单状态	表单字段值、校验与提交过程	表单库内部	React Hook Form、Formik、React Final Form（+ Zod/Yup）	form.tsx、register-form.tsx
URL 状态	可分享、可回退、地址栏可见的页面参数	浏览器地址栏 / 路由	react-router 等路由方案	discussion-view.tsx

这个仓库本身就是一套"用正确工具处理正确状态"的可运行范例：同一个业务应用以三种方式实现（apps/react-vite、apps/nextjs-app、apps/nextjs-pages），三套代码都遵循同一份状态分类约定，本文示例统一取自 react-vite 应用。下面逐一深入。

组件状态（Component State）：先用 useState，不够再提升

组件状态是仅属于某个组件、不应全局共享的本地状态。文档给出的原则很简单：

1. 状态默认定义在组件自身内部；
2. 只有当它在应用其他位置也被需要时，才"提升"（Lift State Up）到更高层；
3. 需要下发给子组件时，通过 props 传递。

React 提供了两个处理组件状态的 hook，选择依据是状态复杂度：

• useState——适合相互独立、结构简单的状态；
• useReducer——适合复杂状态，尤其是"一次 action 需要同时更新多个状态片段"的场景。

源码实证：DashboardLayout 中的进度条组件

dashboard-layout.tsx 中内嵌的 Progress 组件就是典型的组件状态实践。它先读取 react-router 的 useNavigation 拿到路由加载状态，再用本地 useState 维护一个 0~100 的进度数值，并在路由跳转、状态变为 loading 时用定时器推进它：

const Progress = () => {
  const { state, location } = useNavigation();
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    setProgress(0);
  }, [location?.pathname]);

  useEffect(() => {
    if (state === 'loading') {
      const timer = setInterval(() => {
        setProgress((oldProgress) => {
          if (oldProgress === 100) {
            clearInterval(timer);
            return 100;
          }
          const newProgress = oldProgress + 10;
          return newProgress > 100 ? 100 : newProgress;
        });
      }, 300);

      return () => {
        clearInterval(timer);
      };
    }
  }, [state]);

  if (state !== 'loading') {
    return null;
  }

  return (
    <div
      className="fixed left-0 top-0 h-1 bg-blue-500 transition-all duration-200 ease-in-out"
      style={{ width: `${progress}%` }}
    ></div>
  );
};

这段代码里的 progress 完全不需要进入任何全局 Store——它只服务于这一个组件渲染一条顶部加载条。同理，DashboardLayout 里其他导航/抽屉/用户菜单的开关状态也由 UI 组件内部自行管理，外部无人关心。这正是文档强调的就近声明：状态离使用它的组件越近，代码越容易推理，组件也越容易复用到别处。只有当"状态真的要在别处使用"时才提升，而不是一开始就为了"以后可能用到"而全局化。

一个常见误区是把"避免重复请求"误当成"必须全局共享"。远程数据的复用属于服务端缓存状态（见下文），不要把组件状态与服务端数据混在一起处理。

应用状态（Application State）：管理全局 UI 状态，但仍要"就近"

应用状态用于管理应用层面的全局片段，例如全局模态框、通知提示、明暗主题切换等。与直觉相反，文档给出的第一条建议不是"统统全局化"，而是：把状态尽可能局限在需要它的组件附近。只有确实被很多无关组件共享、且无法通过局部化组织消解时，才引入全局方案。

文档认可的方案包括（均为业界成熟选择）：

• Context + Hooks：React 内建，适合中低频全局数据；
• Redux + Redux Toolkit：适合复杂全局状态与严格规范的大团队；
• MobX：响应式、可观察状态；
• Zustand：极简 API 的轻量全局 Store；
• Jotai：原子化状态，按需组合；
• XState：显式状态机建模，适合状态流转复杂的场景。

源码实证：用 Zustand 实现通知系统

仓库在 notifications-store.ts 里用 Zustand 定义了一个典型的"应用级全局状态"——通知列表。它全文件只有约 30 行，通过 create 定义 Store，用不可变更新产出新数组，id 交给 nanoid 生成：

import { nanoid } from 'nanoid';
import { create } from 'zustand';

export type Notification = {
  id: string;
  type: 'info' | 'warning' | 'success' | 'error';
  title: string;
  message?: string;
};

type NotificationsStore = {
  notifications: Notification[];
  addNotification: (notification: Omit<Notification, 'id'>) => void;
  dismissNotification: (id: string) => void;
};

export const useNotifications = create<NotificationsStore>((set) => ({
  notifications: [],
  addNotification: (notification) =>
    set((state) => ({
      notifications: [
        ...state.notifications,
        { id: nanoid(), ...notification },
      ],
    })),
  dismissNotification: (id) =>
    set((state) => ({
      notifications: state.notifications.filter(
        (notification) => notification.id !== id,
      ),
    })),
}));

观察这个 Store 的边界，能提炼出"什么才值得放全局"的判断标准：

• 通知可以被任何业务功能触发（例如 update-discussion.tsx 在 mutation 成功后调用 const { addNotification } = useNotifications() 并 addNotification({ type: 'success', title: 'Discussion Updated' })），这是典型的跨模块共享；
• 数据是纯 UI 级、易失效的瞬时信息，不属于需要长期缓存的服务端数据；
• 消费方是少数（一个渲染区域 + 若干触发点），Store 保持最小化。

消费端 notifications.tsx 订阅 notifications 与 dismissNotification，把整个列表渲染在一个 aria-live="assertive" 的无障碍通告区域内。全局状态既然被刻意设计成"小而专"，维护成本也随之降到最低——这与把全部数据塞进一个大 Store 的"大泥球"式写法形成鲜明对比。

服务端缓存状态（Server Cache State）：远程数据要交给"缓存库"，而不是"全局状态库"

服务端缓存状态指从服务器取回、在客户端暂存以便复用的数据。文档明确指出：把远程数据塞进 Redux 这类状态库虽然技术上可行，但并非最优解，因为状态库擅长的是"客户端 UI 状态"，而远程数据有自己的一套问题域——缓存命中、过期失效、窗口聚焦重新拉取、请求去重、分页/无限滚动预取。

因此需要引入专门的服务端缓存库：

• TanStack Query（react-query）——同时支持 REST 与 GraphQL；
• SWR——同时支持 REST 与 GraphQL；
• Apollo Client——专注 GraphQL；
• urql——轻量 GraphQL 客户端；
• RTK Query——Redux Toolkit 官方数据缓存方案。

react-vite 应用采用 TanStack Query，并在 lib/react-query.ts 集中定义了一组默认查询策略：

import { UseMutationOptions, DefaultOptions } from '@tanstack/react-query';

export const queryConfig = {
  queries: {
    // throwOnError: true,
    refetchOnWindowFocus: false,
    retry: false,
    staleTime: 1000 * 60,
  },
} satisfies DefaultOptions;

staleTime: 1000 * 60（1 分钟内数据视为新鲜、不重复请求）、refetchOnWindowFocus: false、retry: false 这些参数直接决定了缓存命中的行为边界，属于"缓存策略"而非"业务状态"，集中定义让全站行为可预期。同文件还导出了 QueryConfig / MutationConfig 类型工具，用于把 query/mutation 的配置类型化地透传给业务 Hook。

源码实证：get-discussions.ts 的标准封装范式

docs/state-management.md 引用的示例 get-discussions.ts 展示了仓库推荐的服务端缓存封装套路——"裸 API 函数 + queryOptions + 业务 Hook"三层结构：

export const getDiscussions = (
  page = 1,
): Promise<{ data: Discussion[]; meta: Meta }> => {
  return api.get(`/discussions`, {
    params: { page },
  });
};

export const getDiscussionsQueryOptions = ({
  page,
}: { page?: number } = {}) => {
  return queryOptions({
    queryKey: page ? ['discussions', { page }] : ['discussions'],
    queryFn: () => getDiscussions(page),
  });
};

export const useDiscussions = ({ queryConfig, page }: UseDiscussionsOptions) => {
  return useQuery({
    ...getDiscussionsQueryOptions({ page }),
    ...queryConfig,
  });
};

要点拆解：

1. queryKey 是缓存的索引：这里把分页参数写进 key（['discussions', { page }]），不同页码的数据天然分桶缓存，切页时互不污染；
2. Hook 层可注入 queryConfig：调用方（如列表页）可在不改业务逻辑的前提下叠加 enabled、select 等 react-query 选项；
3. api 客户端抽离：所有请求走统一封装的 api-client.ts，方便统一注入鉴权与错误处理。

同样的范式出现在详情查询 get-discussion.ts（key 为 ['discussions', discussionId]）、评论的无限滚动 getInfiniteCommentsQueryOptions 等所有远程数据模块中。缓存数据甚至可以在路由 loader 阶段"先查缓存、没有再请求"，见 discussions.tsx 的 clientLoader：

const page = Number(url.searchParams.get('page') || 1);
const query = getDiscussionsQueryOptions({ page });

return (
  queryClient.getQueryData(query.queryKey) ??
  (await queryClient.fetchQuery(query))
);

再配合 discussions-list.tsx 中鼠标悬停时的 queryClient.prefetchQuery(...) 预热，这套"缓存优先"的服务端数据层完全不占用全局 UI 状态，是"分类治理"最典型的收益点。

表单状态（Form State）：用表单库封装，而不是用全局 Store 硬管

表单是绝大多数应用的刚需，而表单状态是最不该被塞进全局 Store 的一类状态。文档强调：表单状态管理得好坏直接决定交互体验，因此在 React 中管理表单时应优先考虑 Formik、React Hook Form、React Final Form 这类专门库——它们内置了校验、错误处理与提交能力。

React 的表单输入分为受控与非受控两种形态：受控组件的值由 React state 驱动，非受控组件把值存放在 DOM 自身。复杂的表单往往有大量需要校验的字段，仅用 React 原生 API 徒手实现虽然可行，但边界情况（脏值检测、异步校验、提交防抖、字段卸载保留等）极易出错。

文档推荐的库：

• React Hook Form——以最小重渲染著称，性能好、API 简洁；
• Formik——上手简单、生态成熟；
• React Final Form——订阅式架构，性能与灵活性兼顾。

真正让这些库在大型项目中可用的，是文档给出的工程化建议：抽象出统一的 Form 组件与各类输入字段组件（Input/Select/Textarea/Switch…），把库的能力封装在内部，再按应用需求适配。这样业务代码永远不直接依赖某个表单库的具体 API，日后替换库时只需改一层封装。

源码实证：Form 组件如何把 React Hook Form + Zod 焊成一体

仓库在 components/ui/form 目录下完整实现了这套抽象。核心 form.tsx 里，Form 是泛型组件：schema 类型必须继承 ZodType，并借助 z.infer 推导出表单值类型；内部用 useForm + zodResolver(schema) 打通"Zod schema → RHF 校验"，通过 FormProvider 把方法注入子组件，再用 handleSubmit(onSubmit) 包住原生表单：

const Form = <
  Schema extends ZodType<any, any, any>,
  TFormValues extends FieldValues = z.infer<Schema>,
>({
  onSubmit, children, className, options, id, schema,
}: FormProps<TFormValues, Schema>) => {
  const form = useForm({ ...options, resolver: zodResolver(schema) });
  return (
    <FormProvider {...form}>
      <form
        className={cn('space-y-6', className)}
        onSubmit={form.handleSubmit(onSubmit)}
        id={id}
      >
        {children(form)}
      </form>
    </FormProvider>
  );
};

围绕它，同目录还提供 FormItem / FormLabel / FormControl / FormDescription / FormMessage 等配套组件，全部通过两个 Context（FormFieldContext、FormItemContext）把"字段名、唯一 id、错误状态、无障碍描述 id"串联起来，并用 useId 保证 label 与输入框的 htmlFor/id 关联——表单的无障碍细节因此被封装并复用。

字段组件则负责"值绑定 + 展示 + 错误展示"。以 input.tsx 为例，它接收 label、error、registration（来自 register('字段名') 的返回值），内部交给 FieldWrapper 统一渲染 label 与错误信息，再透传 registration 到原生 input：

export type InputProps = React.InputHTMLAttributes<HTMLInputElement> &
  FieldWrapperPassThroughProps & {
    className?: string;
    registration: Partial<UseFormRegisterReturn>;
  };

const Input = React.forwardRef<HTMLInputElement, InputProps>(
  ({ className, type, label, error, registration, ...props }, ref) => {
    return (
      <FieldWrapper label={label} error={error}>
        <input
          type={type}
          className={cn(/* tailwind 样式 */)}
          ref={ref}
          {...registration}
          {...props}
        />
      </FieldWrapper>
    );
  },
);

Select、Textarea、Switch、Label 与 FormDrawer 遵循同样的封装哲学，并统一从 form/index.ts 导出，业务侧只需一条 import 即可使用整组表单原语。

客户端校验：Zod / Yup + schema 前置

文档建议把校验逻辑交给专用校验库，在客户端对输入先行把关。常用选项是 Zod（schema 声明式、TypeScript 类型推导优秀）与 Yup。react-vite 应用选择 Zod，其注册表单的校验 schema 定义在 lib/auth.tsx，甚至在类型层就做到了"两种注册分支"建模——要么 teamId 必填、teamName 为 null，要么反过来：

export const registerInputSchema = z
  .object({
    email: z.string().min(1, 'Required'),
    firstName: z.string().min(1, 'Required'),
    lastName: z.string().min(1, 'Required'),
    password: z.string().min(5, 'Required'),
  })
  .and(
    z
      .object({
        teamId: z.string().min(1, 'Required'),
        teamName: z.null().default(null),
      })
      .or(
        z.object({
          teamName: z.string().min(1, 'Required'),
          teamId: z.null().default(null),
        }),
      ),
  );

export type RegisterInput = z.infer<typeof registerInputSchema>;

业务组件 register-form.tsx 中，把 schema 直接交给 Form，即可获得完全类型安全的表单值（onSubmit 收到的 values 就是 RegisterInput），同时声明 shouldUnregister: true 让未渲染字段卸载时自动注销其值：

<Form
  onSubmit={(values) => {
    registering.mutate(values);
  }}
  schema={registerInputSchema}
  options={{ shouldUnregister: true }}
>
  {({ register, formState }) => (
    <>
      <Input
        type="text"
        label="First Name"
        error={formState.errors['firstName']}
        registration={register('firstName')}
      />
      {/* ... 更多字段 */}
    </>
  )}
</Form>

"是否加入已有团队"这类条件分支，则通过 Switch（受控组件）动态切换渲染 Select（选团队）还是 Input（建新团队），印证了文档所说表单既有简单场景、也有大量字段需联动校验的复杂场景——这正是交给专业表单库的理由。编辑场景 update-discussion.tsx 则展示了用 options.defaultValues 从服务端缓存回填表单初值的做法。

URL 状态（URL State）：让地址栏成为可分享的状态容器

URL 状态指存在并操作于浏览器地址栏中的数据。它有两种载体：

• 路径参数（path params）：形如 /app/${dynamicParam}；
• 查询参数（query params）：形如 /app?dynamicParam=1。

通过 react-router-dom 这类路由方案，可以读写在地址栏中的 URL 状态，让"返回按钮、收藏夹、分享链接"天然地成为状态的传输通道。URL 状态的独特价值在于：它不需要任何内存缓存，却能被持久化、被分享、被搜索引擎索引，适合存放"页面定位"型数据（当前页签、筛选条件、分页页码、详情条目 id）。

源码实证一：路径参数驱动详情页

讨论详情路由在 router.tsx 中注册为 path: 'discussions/:discussionId'。路由组件 discussion.tsx 通过 useParams() 取出 discussionId，先在 clientLoader 里用它做查询预取，再把它传给展示组件：

export const clientLoader =
  (queryClient: QueryClient) =>
  async ({ params }: LoaderFunctionArgs) => {
    const discussionId = params.discussionId as string;
    const discussionQuery = getDiscussionQueryOptions(discussionId);
    // ... fetchQuery / fetchInfiniteQuery
  };

const DiscussionRoute = () => {
  const params = useParams();
  const discussionId = params.discussionId as string;
  const discussionQuery = useDiscussion({ discussionId });
  // ...
  return <DiscussionView discussionId={discussionId} />;
};

这正对应文档示例 discussion-view.tsx——视图本身只接收 discussionId 并驱动 useDiscussion 查询，不维护任何"当前详情"的全局状态。URL 的 discussionId 即唯一的"状态源"，刷新、分享、前进后退全部免费成立。

源码实证二：查询参数驱动分页

讨论列表页把分页页码放进 query string：分页组件 pagination.tsx 用 createHref(page) => $rootUrl?page=${page}`` 生成"上一页/下一页/页码"链接；列表组件 discussions-list.tsx 则用 useSearchParams() 读出页码喂给服务端缓存 Hook：

const [searchParams] = useSearchParams();

const discussionsQuery = useDiscussions({
  page: +(searchParams.get('page') || 1),
});

于是"第 3 页的讨论列表"拥有了稳定的 URL（/app/discussions?page=3），可以收藏、分享，且页面在 loader 阶段还能用同一个 URL 参数完成缓存预取（前文 clientLoader 里的 url.searchParams.get('page')），三类状态在此优雅汇合。此外，仓库把全部路由与链接构造集中在 config/paths.ts，例如登录页 getHref(redirectTo) 会用 encodeURIComponent 把回跳地址拼进 ?redirectTo=——防止 URL 状态被随意写散在各组件里。

选型决策：拿到一个状态，先回答"它属于哪一类"

综合文档与源码，可以沉淀出一份可直接照做的决策清单：

1. 先声明在组件内部：任何新状态默认用 useState 写在"使用它"的组件里；状态结构复杂、一个动作要联动多处更新时改用 useReducer。
2. 确实需要跨组件共享、且偏 UI 性质（通知、主题、全局弹窗）才"提升"，优先采用离使用方最近的 Context/轻量 Store（如示例中的 Zustand 通知 Store），且保持 Store 小而专。
3. 是服务器返回的数据吗？ 一律交给服务端缓存库（TanStack Query / SWR 等）管理，按 queryKey 分桶缓存，绝不复制进 Redux/Zustand 这类 UI 状态库。
4. 是表单字段与校验吗？ 交给 React Hook Form / Formik 等表单库，并在其上封装自己的 Form/字段组件层，配合 Zod/Yup 做客户端校验。
5. 希望状态可以被收藏、分享、刷新保留吗？ 把它放进 URL——路径参数管"是哪条数据"，查询参数管"当前处于什么视图"。

这套思想是 Bulletproof React 全仓库一致遵循的约定：三个示例应用（react-vite、nextjs-app、nextjs-pages）在 features、components/ui/form、lib 等处保持相同结构与命名；docs/state-management.md 只是其架构文档体系中的一章，与之配套的还有 项目结构、API 层、错误处理 等指南，共同勾勒出一套"各类状态各得其所"的生产级 React 架构。

核心结论：状态管理没有银弹，但有清晰的分层——把状态按"作用域 + 生命周期"分类，再用每类最合适的工具管理，你的应用就能同时获得更好的性能（局部重渲染最小化）、更高的可维护性（每类状态的读写路径一目了然）与更强的可扩展性（新增功能时知道状态该放哪里）。这正是"Bulletproof（防弹）"式架构在状态层面的落地方式。