用 React Router…

在 React Router 应用中编写 loader、action、表单、路由组织、流式渲染与 SEO 时，按此清单落地性能与架构规范。

适用场景

解决思路

1. 所有数据获取都放在 loader 中，绝不在组件里用 useEffect 拉取；组件通过 useLoaderData<typeof loader>() 读取数据。
2. loader 内并行取数：先取依赖数据（如 user），再用 Promise.all 并行取 posts、comments，避免串行 await 造成瀑布。
3. 利用请求级缓存：同一请求内 API 客户端会去重，多个 loader 可各自调用 getUser，不会产生额外请求。
4. 用 useRevalidator 做轮询/聚焦/重连时的重新校验；轮询前判断 document.visibilityState === 'hidden' 则跳过，避免后台标签页轮询。
5. 用 Route.LoaderArgs 做 TypeScript 类型标注，配合 useLoaderData<typeof loader>() 获得类型推断。
6. 在 loader 里用 zod 或 invariant 尽早校验 URL 参数（如 z.string().parse(params.itemId)）。
7. 把 request.signal 传给 fetch，请求取消时中止异步工作。
8. 把数据查询函数放在路由同目录的 queries.server.ts 中，route.tsx 只调用这些查询函数，组件放 components/ 子目录。
9. 用 middleware 做认证（sessionMiddleware、authMiddleware），在每个 loader/action 中调用 authorize(context, {...}) 做授权。
10. 每个请求保持单一 session 实例（sessionMiddleware）。
11. 用 AsyncLocalStorage 存 context/request，便于无参 helper 使用（contextStorageMiddleware）。
12. 用 batcher 去重请求级 API/DB 调用：getBatcher().batch('key', () => getData())。
13. 为请求加 request ID 便于日志关联：getRequestID()。
14. 用内置 loggerMiddleware 统一记录请求日志。
15. 用 Server-Timing 记录耗时：getTimingCollector().measure('load', 'Load data', () => getData())。
16. 为缓存创建请求级单例：getSingleton(context)。
17. 用 Sec-Fetch 头拒绝跨站变更请求：fetchSite(request) === 'cross-site' 时返回 403。
18. 公开表单加蜜罐输入 <HoneypotInputs /> 防机器人。
19. API 路由应用 CORS 头：return await cors(request, data(await getData()))。
20. 对用户驱动的跳转做安全清洗：redirect(safeRedirect(redirectTo, '/'))。
21. 用 schema 校验 cookie 载荷：createTypedCookie({ cookie, schema })。
22. 从可信代理头提取客户端 IP：getClientIPAddress(request)。
23. UI 层访问父路由数据用 useRouteLoaderData；loader 逻辑需要数据时直接再取一次（请求级缓存，无额外请求）。
24. 只有路由组件调用 useLoaderData/useActionData，子组件通过 props 接收数据。
25. action 中用 zod schema 校验表单数据，错误信息支持 i18n；校验失败返回 data({ errors }, { status: 400 })，不要抛异常。
26. action 错误处理：校验错误返回 data，redirect 和未知错误要重新 throw。
27. 变更成功后用 throw redirect('/items') 跳转，防止重复提交。
28. 用 zod 的 .transform() 做输入清洗：trim/lowercase 邮箱、把货币字符串转数字、把 checkbox 转布尔。
29. 用 clientAction 在提交到服务端前做即时客户端校验，校验通过再调用 serverAction。
30. 非导航型变更（如点赞）用 useFetcher，需要导航的提交用 Form。
31. 用 useNavigation 或 fetcher.state 显示 pending 状态；配合 useSpinDelay 避免闪烁。
32. 提交成功后重置非受控表单：在 fetcher.state === 'idle' && fetcher.data?.ok 时调用 formRef.current?.reset()。
33. 校验失败时 action 返回字段值（fields），组件用 defaultValue={actionData?.fields?.email} 回填。
34. 用 clientLoader 在路由层做防抖：setTimeout(500, serverLoader, { signal: request.signal })，并设置 clientLoader.hydrate = true。
35. 把旧的 defer() 迁移为 data() + Promise（Single Fetch 自动流式）。
36. 流式数据用 <Suspense> 包裹 <Await resolve={lazy}> 渲染。
37. 弃用 jsonHash，改用原生 Promise.all 或 data() 配合 Promise 自动流式。
38. 把已废弃的 json() 迁移为 data()，包括带状态码和 throw data(...) 的用法。
39. 把 namedAction 迁移为 z.discriminatedUnion('intent', [...]) 做类型安全的意图校验。
40. 用 useRouteError 和 isRouteErrorResponse 实现布局感知的 ErrorBoundary。
41. 为有数据获取的路由添加 ErrorBoundary 以捕获 loader/action 错误。
42. 导航链接用 prefetch="intent" 在 hover/focus 时预取。
43. 应用内返回链接避免 navigate(-1)，改用 <Link to={...} state={{ back: location.pathname }}>。
44. 用 PrefetchPageLinks 预加载 fetcher.load() 所需数据。
45. 资源路由用响应 helper，如 html('<h1>Hello</h1>')。
46. 用 eventStream 和 useEventSource 推送 SSE 更新。
47. 预取请求使用短缓存：isPrefetch(request) 时设置 Cache-Control: private, max-age=5。
48. 路由用文件夹组织：queries.server.ts、actions.server.ts、route.tsx、components/ 同目录。
49. API 类端点用资源路由（无 default export 的路由文件）。
50. 把可复用 action 集中到 actions.noun-verb.ts 资源路由，并配 clientAction 做 toast 与跳转。
51. 用 shouldRevalidate 优化重新校验，例如仅 hash 变化时返回 false。
52. 用 handle 导出配合应用定义的 handle 类型控制路由元数据（hydrate、stickyHeader、footerType）。
53. 用 meta 函数配合 loader 数据做动态 SEO，返回 title、description、og:* 等；也可在 loader 中集中生成 meta 再返回。
54. 路由文件的默认导出统一命名为 Component。
55. 路由文件之间不要互相 import；共享组件放 ~/components 等共享位置，仅可 import 其他路由的 loader/action 类型用于 useFetcher 类型推断。

适用边界 · 注意事项

• 不使用 React Router 的项目不适用。
• 未使用 TypeScript 或 Route 类型生成的项目，部分类型标注写法需调整。
• 不涉及服务端渲染/数据路由（纯客户端 SPA 无 loader/action）时，多数规则不适用。