react-principle-engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Core Team React Principles Best Practices

React核心团队推荐的React开发原则与最佳实践

Comprehensive React development principles extracted from the official React documentation. Contains 52 rules across 8 categories prioritized by impact on code quality and maintainability.

本文整理自React官方文档中的全面开发原则，包含8个分类下的52条规则，按对代码质量和可维护性的影响优先级排序。

When to Apply

适用场景

Reference these guidelines when:

Writing React components with hooks
Managing component and application state
Synchronizing with external systems (APIs, browser APIs)
Debugging unexpected re-renders or stale state
Structuring state for complex UIs
Deciding between state, refs, context, and reducers

在以下场景中可参考这些指南：

使用Hooks编写React组件时
管理组件与应用状态时
与外部系统（API、浏览器API）同步时
调试意外重渲染或过期状态时
为复杂UI设计状态结构时
在state、refs、context和reducers之间做选择时

Rule Categories by Priority

按优先级排序的规则分类


pure-
state-
share-
effect-
ref-
reducer-
context-
event-

Priority	Category	Impact	Prefix
1	Component Purity	HIGH	`pure-`
2	State Structure	HIGH	`state-`
3	State Sharing	HIGH	`share-`
4	Effect Patterns	HIGH	`effect-`
5	Refs Usage	MEDIUM	`ref-`
6	Reducer Patterns	MEDIUM	`reducer-`
7	Context Patterns	MEDIUM	`context-`
8	Event Handling	MEDIUM	`event-`


pure-
state-
share-
effect-
ref-
reducer-
context-
event-

优先级	分类	影响程度	前缀
1	组件纯净性	高	`pure-`
2	状态结构	高	`state-`
3	状态共享	高	`share-`
4	Effect模式	高	`effect-`
5	Refs用法	中	`ref-`
6	Reducer模式	中	`reducer-`
7	Context模式	中	`context-`
8	事件处理	中	`event-`

Quick Reference

快速参考

1. Component Purity (HIGH)

1. 组件纯净性（高优先级）

```
pure-no-external-mutations
```
- Never mutate external variables during render
```
pure-same-inputs-same-outputs
```
- Same props/state always produce same JSX
```
pure-local-mutation-allowed
```
- Local mutation during render is fine
```
pure-strict-mode-detection
```
- Use StrictMode to catch purity violations
```
pure-side-effects-in-handlers
```
- Put side effects in event handlers
```
pure-props-as-readonly
```
- Treat props as immutable snapshots
```
pure-render-independence
```
- Render order shouldn't matter
```
pure-use-effect-last-resort
```
- Effects are escape hatches, not primary pattern
```
pure-why-purity-matters
```
- Pure components enable React's features

```
pure-no-external-mutations
```
- 渲染期间绝不要修改外部变量
```
pure-same-inputs-same-outputs
```
- 相同的props/state必须生成相同的JSX
```
pure-local-mutation-allowed
```
- 渲染期间的本地修改是允许的
```
pure-strict-mode-detection
```
- 使用StrictMode检测纯净性违规问题
```
pure-side-effects-in-handlers
```
- 将副作用放在事件处理函数中
```
pure-props-as-readonly
```
- 将props视为不可变快照
```
pure-render-independence
```
- 渲染顺序不应影响结果
```
pure-use-effect-last-resort
```
- Effects是兜底方案，而非主要模式
```
pure-why-purity-matters
```
- 纯净组件是React特性的基础

2. State Structure (HIGH)

2. 状态结构（高优先级）

```
state-group-related
```
- Group related state variables together
```
state-avoid-contradictions
```
- Avoid contradictory state (use enums)
```
state-avoid-redundant
```
- Don't store values that can be derived
```
state-avoid-duplication
```
- Store IDs, not duplicate objects
```
state-flatten-nested
```
- Flatten deeply nested state
```
state-no-mirror-props
```
- Don't initialize state from props
```
state-immutable-updates
```
- Always create new objects/arrays
```
state-snapshot-behavior
```
- State is a snapshot at render time
```
state-updater-functions
```
- Use updaters for sequential updates
```
state-keys-reset
```
- Use key to reset component state

```
state-group-related
```
- 将相关的状态变量分组
```
state-avoid-contradictions
```
- 避免矛盾状态（使用枚举）
```
state-avoid-redundant
```
- 不要存储可推导的值
```
state-avoid-duplication
```
- 存储ID，而非重复对象
```
state-flatten-nested
```
- 扁平化深层嵌套的状态
```
state-no-mirror-props
```
- 不要从props初始化状态
```
state-immutable-updates
```
- 始终创建新的对象/数组
```
state-snapshot-behavior
```
- 状态是渲染时的快照
```
state-updater-functions
```
- 对于连续更新使用更新器函数
```
state-keys-reset
```
- 使用key重置组件状态

3. State Sharing (HIGH)

3. 状态共享（高优先级）

```
share-lift-state-up
```
- Lift state to nearest common ancestor
```
share-single-source-truth
```
- One source of truth for each piece
```
share-controlled-uncontrolled
```
- Controlled vs uncontrolled patterns
```
share-props-down-events-up
```
- Props flow down, events bubble up
```
share-composition-over-drilling
```
- Use composition to avoid drilling
```
share-preserve-reset-identity
```
- Component identity affects state

```
share-lift-state-up
```
- 将状态提升到最近的共同祖先组件
```
share-single-source-truth
```
- 每个数据片段只有单一数据源
```
share-controlled-uncontrolled
```
- 受控与非受控组件模式
```
share-props-down-events-up
```
- Props向下传递，事件向上冒泡
```
share-composition-over-drilling
```
- 使用组合避免props透传
```
share-preserve-reset-identity
```
- 组件标识会影响状态

4. Effect Patterns (HIGH)

4. Effect模式（高优先级）

```
effect-synchronization
```
- Effects sync with external systems
```
effect-cleanup
```
- Always provide cleanup functions
```
effect-dependencies
```
- Include all dependencies in array
```
effect-separate-concerns
```
- Separate independent synchronizations
```
effect-think-sync-not-lifecycle
```
- Think sync/unsync, not mount/unmount
```
effect-not-for-derived-state
```
- Don't use effects for derived state
```
effect-not-for-events
```
- Don't use effects for event responses
```
effect-data-fetching
```
- Proper patterns for data fetching
```
effect-never-suppress-linter
```
- Never suppress dependency warnings
```
effect-remove-unnecessary
```
- Remove effects that don't need to be effects

```
effect-synchronization
```
- Effects用于与外部系统同步
```
effect-cleanup
```
- 始终提供清理函数
```
effect-dependencies
```
- 依赖数组中包含所有相关依赖
```
effect-separate-concerns
```
- 分离独立的同步逻辑
```
effect-think-sync-not-lifecycle
```
- 思考同步/取消同步，而非挂载/卸载
```
effect-not-for-derived-state
```
- 不要用Effects处理派生状态
```
effect-not-for-events
```
- 不要用Effects响应事件
```
effect-data-fetching
```
- 数据获取的正确模式
```
effect-never-suppress-linter
```
- 绝不要禁用依赖项警告
```
effect-remove-unnecessary
```
- 移除不需要作为Effects的逻辑

5. Refs Usage (MEDIUM)

5. Refs用法（中优先级）

```
ref-escape-hatch
```
- Refs are escape hatches from React
```
ref-no-render-access
```
- Don't read/write refs during render
```
ref-dom-manipulation
```
- Use refs for DOM manipulation
```
ref-mutable-values
```
- Refs for mutable values like timers
```
ref-best-practices
```
- When to use refs vs state

```
ref-escape-hatch
```
- Refs是React的兜底方案
```
ref-no-render-access
```
- 不要在渲染期间读写refs
```
ref-dom-manipulation
```
- 使用refs操作DOM
```
ref-mutable-values
```
- Refs用于存储计时器等可变值
```
ref-best-practices
```
- 何时使用refs而非state

6. Reducer Patterns (MEDIUM)

6. Reducer模式（中优先级）

```
reducer-when-to-use
```
- When to use reducers over useState
```
reducer-actions
```
- Actions describe what happened
```
reducer-pure-functions
```
- Reducers must be pure
```
reducer-structure
```
- Standard reducer structure patterns
```
reducer-extract-from-component
```
- Extract reducers to separate files

```
reducer-when-to-use
```
- 何时用reducers替代useState
```
reducer-actions
```
- 动作描述发生的事件
```
reducer-pure-functions
```
- Reducers必须是纯函数
```
reducer-structure
```
- 标准的reducer结构模式
```
reducer-extract-from-component
```
- 将reducers提取到单独文件

7. Context Patterns (MEDIUM)

7. Context模式（中优先级）

```
context-when-to-use
```
- When to use context vs props
```
context-create-use-provide
```
- Create, use, provide pattern
```
context-with-reducer
```
- Combine context with reducers
```
context-default-values
```
- Meaningful default values

```
context-when-to-use
```
- 何时用context而非props
```
context-create-use-provide
```
- 创建、使用、提供的模式
```
context-with-reducer
```
- 将context与reducers结合使用
```
context-default-values
```
- 有意义的默认值

8. Event Handling (MEDIUM)

8. 事件处理（中优先级）

```
event-pass-handlers
```
- Pass handlers, don't call them inline
```
event-side-effects
```
- Side effects belong in handlers
```
event-propagation
```
- Event propagation and stopPropagation
```
event-naming
```
- Handler naming conventions (handle/on)

```
event-pass-handlers
```
- 传递处理函数，不要内联调用
```
event-side-effects
```
- 副作用属于处理函数
```
event-propagation
```
- 事件冒泡与stopPropagation
```
event-naming
```
- 处理函数命名规范（handle/on前缀）

How to Use

使用方式

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Example rules: pure-no-external-mutations, effect-synchronization

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 分类结构与影响级别
示例规则：pure-no-external-mutations, effect-synchronization

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded: AGENTS.md

包含所有规则扩展说明的完整指南：AGENTS.md