modern-best-practice-react-components

编写 React 组件

我们使用现代 React（19+），并遵循以清晰、正确和易维护为目标的通用最佳实践。

组件结构与风格

• 优先使用小巧、专注且只承担单一职责的组件
• 优先使用命名的 function 组件，而不是箭头函数
  • 例外：匿名回调、内联渲染属性和闭包
• 优先在适用时显式声明返回类型和 props 类型（TypeScript）
• 保持组件扁平、易读；避免 JSX 深度嵌套
• 将相关逻辑归在一起（事件处理器、派生值、辅助函数）

状态管理

• 避免使用 useEffect()
  • 详细指南请参阅 "You Might Not Need An Effect" guide
  • 优先在渲染期间派生值，而不是同步状态
  • 通过 TanStack Query（@tanstack/react-query）获取数据
• 避免不必要地使用 useState() 或 useReducer()
  • 尽可能从 props 或其他状态派生状态
  • 将状态放在尽可能低层的组件中
• 不要将 props 镜像到状态中，除非绝对必要
• 相较于同步非受控状态，优先使用受控组件

渲染与派生

• 优先在行内或通过辅助函数计算派生值
• 谨慎使用 useMemo()，且仅用于已证实的性能问题
• 避免过早优化
• 保持渲染逻辑具有确定性且无副作用

事件处理

• 避免在 JSX 中使用行内事件处理器

  • 优先：

    function handleClick() {
      // ...
    }
    
    <button onClick={handleClick} />;
    

  • 而不是：

    <button
      onClick={() => {
        /* ... */
      }}
    />
    

• 为处理器使用清晰的名称（handleSubmit、handleChange、handleClose）

• 保持处理器简洁；将复杂逻辑提取到辅助函数中

副作用、数据与副作用处理

• 避免将副作用用于：
  • 派生状态
  • 数据转换
  • 可放在处理器中的事件逻辑
• 如果无法避免副作用，请保持其精简、隔离且有完善文档
• 优先使用框架级或外部抽象（路由器、数据库），而不是原始副作用

Props 与组合

• 优先使用组合，而不是配置
• 避免过多的布尔 props；优先采用表达力更强的 API
• 有意使用 children，并说明预期结构
• 保持 prop 名称语义清晰且可预测

性能与稳定性

• 优先仅在需要时保持引用稳定（而非默认如此）
• 避免不必要的记忆化（memo、useCallback），除非绝对必要
• 渲染列表时，保持 key 稳定且有意义

通用原则

• 首先为人编写代码，其次才是编译器
• 优先明确表达，而不是炫技
• 以可读性和长期维护为优化目标
• 如果某种模式显得复杂，请重新考虑组件边界