react-best-practices

React 最佳实践

概述

面向 React 性能与质量的路由与优先级指南，共包含 9 个类别下的 27 条规则。规则文件中包含详细说明、示例、代码审查中的常见问题（smells）以及影响指标。

适用场景

在以下情况下参考本指南：

• 编写新的 React 组件
• 实现数据获取
• 审查代码中的性能问题
• 重构现有的 React 代码
• 优化包体积或加载时间

按优先级排列的指南

规则按影响程度排序：

优先级	类别	影响
1	消除瀑布流	CRITICAL
2	包体积优化	CRITICAL
3	客户端数据获取	MEDIUM-HIGH
4	重渲染优化	MEDIUM
5	渲染性能	MEDIUM
6	JavaScript 性能	LOW-MEDIUM
7	组件结构	MEDIUM-HIGH（可维护性）
8	测试	MEDIUM-HIGH（正确性）
9	类型安全	HIGH

快速参考

关键模式（优先应用）

消除瀑布流：

• 对相互独立的异步操作使用 Promise.all()（async-parallel）

减少包体积：

• 避免使用 barrel 文件导入，直接从源文件导入（bundle-barrel-imports）
• 延迟加载非关键的第三方库（bundle-defer-third-party）

中等影响模式

客户端数据获取：

• 使用 Tanstack Query 自动去重请求（client-request-dedupe）
• 依赖的查询参数只能是值或 undefined，绝不能使用 | null 或虚假的回退值；在调用方收窄类型，使 hook 保持严格；若 hook 必须接受可选参数，则使用 skipToken 进行守卫（client-request-dedupe）

重渲染优化：

• 对开销较大的值使用惰性 state 初始化（rerender-lazy-state-init）
• 对非紧急更新使用 startTransition（rerender-transitions）
• 保持 UI 事件处理函数为普通函数；仅将 Effect Events 用于由 effect 触发的逻辑（rerender-useeffect-function-calls）
• 绝不使用 useEffect 重置 state；应提升判别值并重新挂载该分支（rerender-no-useeffect-state-reset）
• 绝不添加 useMemo 或 useCallback；记忆化决策应交由有 profiler 证据支持的开发者决定（rerender-no-usememo-usecallback）
• 绝不在渲染期间或 useEffect 内调用 setState；应在渲染期间派生，或将 state 归属移至中间组件（rerender-no-setstate-in-render-or-effect）

组件结构：

• 每个文件只包含一个领域组件/hook，且各自只负责一项职责；拆分臃肿的组件（structure-single-responsibility）
• 保持组件、hook、函数和工具函数的 API 精简：将过大的 props、参数和返回对象拆分为聚焦的单元，并在组件层组合；把相同的值包装进一个对象并不是解决方案（structure-narrow-apis）
• 返回 JSX 的辅助函数使用 PascalCase 命名的组件；非 JSX 值的辅助函数保持小写命名（structure-component-naming）
• 对于可由其他参数计算得出的值，应派生 props/参数，而不是单独接收（structure-derive-dont-duplicate）
• 将复杂的派生逻辑提取为具名局部变量，并配合谓词或带提前返回的纯辅助函数：过长的条件、嵌套三元表达式、用于计算而非选择的三元表达式（多行分支，或用 as 断言重复条件已检查的内容）、回退链以及基于 let 的渲染准备代码，都属于代码坏味道；无论是在渲染准备、hook 选项、请求构建器、配置映射还是 reducer 中均是如此（structure-complex-derived-logic）
• 使用提前 if 守卫来选择视图，但将布局包装器保留在一处：拆分出 body 组件进行分支，不要使用三元表达式或重复外壳（structure-early-return-render-branches）
• 对于固定的一组项目，为每个项目编写一个具有明确 props 的组件，由其负责自身的数据与加载状态；不要将配置对象数组映射到组件结构上（structure-composition-over-config）
• 当领域组件获取数据时，通过一个负责定位插槽的纯布局组件进行渲染，并在骨架屏与已解析的子领域组件之间分支切换插槽内容（structure-data-fetching-layout）

测试：

• BDD 测试应驱动真实的 @mastra/client-js + React Query 技术栈，且只模拟网络；绝不对我们自己的 hooks/服务/认证门控或 SDK 使用 vi.mock（testing-bdd-no-mocks）
• 避免对视觉行为进行 class 名断言；优先使用计算样式、用户可见行为或浏览器验证，宁可不写测试，也不要编写仅依赖 className 的实现镜像测试（testing-no-classname-assertions）

类型安全：

• 任何地方都不使用 as 类型断言，无论是生产代码还是测试代码；应使用真实的类型守卫、查询泛型（querySelector<T>、getByRole<T>）、带类型的 fixture 工厂，或对 mock 使用 implements 来收窄类型。as const 是唯一允许的形式。不要用仅检查 typeof value === 'object' 的领域类型谓词来替代断言；应将其称为 isRecord 辅助函数，或校验所使用的字段（types-no-type-assertions）
• 使用 undefined 和可选的 ? 表示缺失值，而不是 null；在边界处转换外部的 null，并保持叶子组件的 props 严格，使调用方自行负责缺失值与回退渲染（types-no-null）

渲染模式

• 对 SVG 外层包装元素做动画，而不是直接对 SVG 元素做动画（rendering-animate-svg-wrapper）
• 对长列表使用 content-visibility: auto（rendering-content-visibility）

JavaScript 模式

• 对重复查找使用 Set/Map（js-set-map-lookups）
• 为保证不可变性，使用 toSorted() 替代 sort()（js-tosorted-immutable）
• 比较数组前先检查长度（js-length-check-first）

参考资料

规则文件是详细指导和示例的权威来源：

• references/react-best-practices-reference.md - 规则目录，包含分类顺序和规则文件路径
• references/rules/ - 按分类组织的独立规则权威文件

仅在实现或审查特定模式时加载相关规则文件。使用目录选择合适的规则，无需加载所有示例。

要查找特定模式，请在规则目录中搜索：

grep -l "Promise.all" references/rules/
grep -l "barrel" references/rules/
grep -l "Tanstack" references/rules/

references/rules/ 中的规则分类

• async-* - 消除瀑布请求（1 条规则）
• bundle-* - 包体积优化（2 条规则）
• client-* - 客户端数据获取（1 条规则）
• rerender-* - 重新渲染优化（6 条规则）
• rendering-* - DOM 渲染性能（2 条规则）
• js-* - JavaScript 微优化（3 条规则）
• types-* - 类型安全 / 禁止 as 类型断言和禁止 null 规则（2 条规则）
• structure-* - 组件/Hook/函数/工具函数结构（8 条规则）
• testing-* - BDD 测试 + 仅模拟网络的策略 + 禁止基于 className 的实现镜像断言（2 条规则）