# 反应开发使用 React Router v7 的生产应用程序的服务器优先 React 模式。涵盖框架层——加载器、操作、突变、状态、错误处理和 API 客户端集成。所有模式都假设使用路由加载器和操作进行服务器端渲染，而不是 SPA 时代的客户端数据获取。有关 TypeScript 严格性、测试和构建工具，请参阅“/typescript”。有关组件设计、表单 UX 和可访问性，请参阅“/ux-design”。有关 CSS 和响应式模式，请参阅“/css-responsive”。 ** ** ## 1\.反应 19 种模式 ### 通过 `fetcher.formData` 实现乐观 UI 在 React Router v7 中，从“fetcher.formData”（待提交的数据）派生乐观状态。不需要“useOptimistic”（这是 React 19 的 React Actions 原语，而不是 React Router 的数据层）。与数据列表分开渲染待处理项目 - 乐观的项目是瞬态 UI 状态，而不是数据。服务器通过加载器重新验证分配真实ID： const fetcher = useFetcher(); 返回（ <>

{item.name}
{String(fetcher.formData.get("名称") ?? "")}

<输入类型=“隐藏”名称=“_intent”值=“创建”/> <输入名称=“名称”必需/> ）；当提交正在进行时，`fetcher.formData` 不为空。当操作完成时，加载器重新验证，真实项目（及其服务器分配的 ID）出现在“items”中，并且“fetcher.formData”重置为 null - 乐观元素自动消失。对于多个并发提交，请使用“useFetchers()”来呈现所有待处理的项目。 ### `use()` 钩子读取条件和循环内的承诺和上下文（与其他钩子不同）： function ResourceDetail({ resourcesPromise }: { resourcesPromise: Promise }) { const 资源 = use(resourcePromise); // 暂停直到解决 return

{资源名称}

; } ** ** ## 2\.数据获取 ### 路由加载器是缓存加载器在渲染之前在服务器上运行。它们是服务器数据的单一来源——顶部不需要 SPA 时代的客户端缓存层。导出异步函数加载器({ request, params }: LoaderFunctionArgs) { const id = params.id; if (!id) throw new Response("Not Found", { status: 404 }); const 资源 = 等待 api.getResource(id); 返回{资源}； } 导出默认函数 ResourcePage() { const { 资源 } = useLoaderData<加载器类型>(); 返回 ; } ### 关键规则 * **加载器是缓存** - 页面渲染时数据可用，初始数据没有加载微调器 * **永远不要将服务器数据复制到 `useState`** — `useLoaderData` 拥有它 * 加载程序在成功操作后自动重新运行 - 无需手动使缓存失效 * 使用“parsePaginationParams()”或类似的帮助器来处理 URL 驱动的数据（过滤器、排序、分页） * 出错时抛出“Response”以触发路由的“ErrorBoundary” * 成功返回普通对象 — 通过 `useLoaderData()` 访问 ** ** ## 3\.突变 ### 所有突变的“

” 所有突变都通过 `` 流经路由操作 — 绝不是 `onClick` \+ `fetch()`： <表单方法=“post”> <输入类型=“隐藏”名称=“_intent”值=“创建”/> “Form”来自“react-router”，而不是 HTML——它处理序列化并在操作完成后触发加载器重新验证。 ### 意图模式多操作路线使用隐藏的“_intent”字段来区分：导出异步函数 action({ request }: ActionFunctionArgs) { const formData = 等待 request.formData(); const Intent = String(formData.get("_intent") ?? "创建"); if（意图===“删除”）{ const id = String(formData.get("id") ?? ""); if (!id) return Response.json({ error: "缺少 id", Intent: "删除" }, { status: 400 }); 尝试{ 等待 api.deleteResource(id); return Response.json({ success: true, Intent: "delete" }); } 捕获（错误）{ const status = extractErrorStatus(错误); return Response.json({ error: "删除失败", Intent: "删除" }, { status }); } } // 处理创建、更新... } ### 动作返回形状类型 ActionResult = { 意图：字符串；错误？：字符串；成功？：布尔值 }; * 始终包含“意图”，以便 UI 可以将错误显示范围调整为正确的形式 * 对于成功和错误都使用 `Response.json()` ——永远不要抛出预期的错误 * 通过 `useActionData()` 访问 — 使用类型保护进行验证，因为它返回 `unknown` ### `useFetcher` 用于非导航突变当突变不应触发全页导航时，请使用“useFetcher”： const fetcher = useFetcher(); <输入类型=“隐藏”名称=“_intent”值=“切换”/> 使用案例：内联切换、后台保存、列表项中不应滚动到顶部的操作。 ### 提交状态 const 导航 = useNavigation(); const isSubmitting = navigation.state === "正在提交"; <按钮类型=“提交”禁用= {isSubmitting}> {正在提交？ “正在保存...”：“保存”} 对于 fetcher 驱动的突变，请改用“fetcher.state”。 ### 表单输入 * 对表单字段使用“defaultValue”（不受控制的输入）——浏览器管理表单状态 * 切勿将 `useState` \+ `value` 用于将通过 `` 提交的字段 * 将 FormData 解析提取到命名函数中以保持操作集中 ** ** ## 4\.错误处理 ### 分层错误边界 1. **根边界：** 捕获灾难性错误，显示整页错误屏幕 2. **路由边界：** 捕获每个路由的加载器/操作错误（框架提供的“ErrorBoundary”导出） 3. **功能边界：** 包装各个小部件，因此单个故障不会导致页面崩溃从“react-error-boundary”导入{ErrorBoundary}； <错误边界 FallbackComponent={ErrorFallback} onReset={() => { /* 重新验证加载器或导航到相同的路线 */ }} 重置密钥={[资源ID]} > <资源详情/> ### 哪些错误边界不能捕获 * 事件处理程序中的错误（使用 try/catch） * React 渲染之外的异步错误（在承诺链中处理） * 误差边界本身的误差 ### 重试模式提供一个调用 `resetErrorBoundary()` 的“重试”按钮。对于路由级错误，页面重新加载会重新触发加载器。 ### Toast 通知用于非阻塞错误（例如，“保存失败，正在重试...”）。库：“sonner”、“react-hot-toast”。切勿使用 toast 作为表单验证的唯一错误指示器。 ** ** ## 5\.状态管理 ### 决策框架状态类型 |工具|示例 ---|---|--- 服务器数据 | `useLoaderData` / `useActionData` |获取的资源、列表、操作结果 URL 状态 | `useSearchParams` |过滤、分页、搜索、排序表格数据|不受控制的 DOM 输入 (`defaultValue`) |在“”中输入值瞬态用户界面 | `useState` |工作表打开/关闭、删除确认、上岗 ### 关键规则 * **没有客户端数据层** - 加载器和操作拥有所有服务器数据。 SPA 时代的缓存库（TanStack Query、SWR、用于服务器状态的 Zustand）是不必要的并且与框架相冲突 * **永远不要将服务器数据复制到 `useState`** — `useLoaderData` 是事实来源 * **URL 状态是最未充分利用的位置** — 过滤器、排序顺序和分页通过 `useSearchParams` 属于 URL 中 * `useState` 仅适用于瞬态 UI：模式打开/关闭、删除确认切换、仅客户端库安装防护 * 在渲染期间使用 `useMemo` 派生状态 — 切勿使用 `useEffect` 来同步派生值 ** ** ## 6\. API 客户端模式 ### 从 OpenAPI 生成客户端使用生成的客户端（例如，`@hey-api/openapi-ts`）进行类型安全的 API 调用： * 根据 OpenAPI 规范生成类型安全函数 * 仅在加载器和操作中调用 - 从不在组件中调用 * 错误处理：动作捕获错误并返回 `Response.json({ error }, { status })` ### 在哪里调用API客户端 // 正确 — 在加载器中（服务器端）导出异步函数加载器({ request }: LoaderFunctionArgs) { const data = 等待 apiClient.getResources(); 返回{数据}； } // 正确 — 在操作中（服务器端）导出异步函数 action({ request }: ActionFunctionArgs) { const formData = 等待 request.formData(); 等待 apiClient.createResource(parseFormData(formData)); 返回 Response.json({ 成功: true }); } 切勿直接在 React 组件中导入或调用 API 客户端。组件专门从“useLoaderData”和“useActionData”读取数据。 ** ** ## 7\.钩子和组合 ### 何时提取自定义钩子在以下情况下拔出钩子： * 逻辑在 2 个以上组件之间共享 * 组件具有复杂的状态管理，掩盖了其渲染意图 * 你需要独立于UI来测试逻辑在以下情况下不要提取： * 逻辑仅在一个组件中使用，简单 * “钩子”只是一个围绕单个 `useState` 的薄包装 ### 命名约定 * `use` 前缀是强制性的（React 强制执行此操作） * 名称描述了钩子提供的内容，而不是如何提供的：“useAssets()”而不是“useFetchAssets()” * 返回 3 个以上值的对象，1-2 个元组： `const [value, setValue] = useToggle()` ### 钩子组成从简单的钩子构建复杂的钩子：函数 useAssetFilters() { const [searchParams, setSearchParams] = useSearchParams(); const 过滤器 = useMemo(() => parseFilters(searchParams), [searchParams]); const setFilter = useCallback((键：字符串，值：字符串) => { setSearchParams(prev => { prev.set(key, value); return prev; }); }, [setSearchParams]); 返回{过滤器，setFilter}； } ### 钩子测试使用测试库中的“renderHook”测试钩子：从“@testing-library/react”导入{renderHook，act}； test("useToggle 切换值", () => { const { 结果 } = renderHook(() => useToggle(false)); 期望(结果.当前[0]).toBe(假); act(() => result.current[1]()); Expect(result.current[0]).toBe(true); }); 将需要提供者（路由器）的钩子包装在包装器中： const 包装器 = ({ 孩子 }: { 孩子: ReactNode }) => ( {子项} ）； const { 结果 } = renderHook(() => useAssetFilters(), { 包装器 }); ** ** ## 8\.反模式 ### SPA 时代模式（切勿与 React Router v7 一起使用）这些模式属于SPA时代，客户端管理自己的数据。在具有加载器和操作的服务器优先架构中，它们增加了复杂性，与框架相冲突，并破坏了渐进增强。 SPA反模式|问题 |服务器优先的替代方案 ---|---|--- 用于数据获取的`useEffect`瀑布、竞赛条件、无 SSR |路线装载机 `onClick` \+ `fetch` 用于突变 |无需渐进增强，无需重新验证 | `<表单方法=“post”>` 组件中的客户端“fetch” |绕过加载器缓存，对框架不可见 |移动到加载程序或操作用于路线数据的 TanStack 查询/SWR |重复的缓存层，与重新验证作斗争| `useLoaderData` 是缓存表单字段的“useState” |额外状态，与 DOM 不同步 | `defaultValue` \+ 不受控制的输入 `useReducer` 用于表单状态 |过度设计 DOM 已经做的事情 | `<表单>` \+ `FormData` 客户端表单验证库 |重复服务器逻辑，错误的安全感 | HTML5 属性 + 服务器验证的实际应用 `useEffect` 同步操作结果 |额外的渲染周期、过时的值 |直接`useActionData()` 用于服务器数据的 Zustand/Redux |错误的工具 - 这些仅适用于客户端状态 |加载器拥有服务器数据因用户错误而引发操作 |触发 ErrorBoundary，丢失表单状态 | `Response.json({ 错误 })` ### 一般 React 反模式反模式|问题 |修复 ---|---|--- 道具钻探超过 4 个关卡 |脆弱，难以重构 |上下文或组合没有 SSR 防护的 `useLayoutEffect`服务器警告，在服务器上作为“useEffect”运行 | `useEffect` 或 `useIsomorphicLayoutEffect` 派生状态的“useEffect” |额外的渲染周期、过时的值 |在渲染期间使用“useMemo”进行计算到处手动`useMemo`/`useCallback`噪音、过早优化 | React Compiler 处理记忆化 ** ** ## 交叉引用 * `/typescript` — TypeScript 严格性、路由类型安全、测试 (Vitest/Playwright)、模块、构建工具 * `/ux-design` — 组件 API 设计、服务器验证的表单 UX、可访问性 * `/css-responsive` — 响应式渲染，Tailwind CSS 模式

反应

包含技能