React 项目工程化规范：从代码质量到团队协作的完整体系

引言

一个 React 项目从「能跑」到「好维护」，中间的鸿沟是工程化规范。规范不是束缚，而是团队协作的「共识契约」：代码风格统一、质量门禁自动、目录结构清晰、文档与代码同步。本文将从工程化的四层体系讲起，系统梳理 React 项目的目录结构设计、代码规范工具链、Git 协作流程、代码评审与持续集成，帮助团队建立可持续的工程文化。

一、工程化的四层体系

React 项目工程化可以拆解为四层：代码层（风格与质量）、协作层（分支与评审）、自动化层（CI/CD）、治理层（监控与规范迭代）。

工程化全景

flowchart TB
  classDef e1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef e2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef e3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[工程化体系] --> B[代码层<br/>风格 质量 结构]
  A --> C[协作层<br/>分支 评审 规范]
  A --> D[自动化层<br/>CI/CD 门禁]
  A --> E[治理层<br/>监控 度量 迭代]

  B --> B1[Prettier + ESLint]
  B --> B2[目录结构约定]
  C --> C1[Git Flow 分支]
  C --> C2[PR 评审清单]
  D --> D1[类型/测试/构建门禁]
  D --> D2[自动部署]
  E --> E1[错误与性能监控]
  E --> E2[规范定期复盘]

  click B1 "https://prettier.io/" "Prettier 文档"
  class A e1
  class B e1
  class C e2
  class D e2
  class E e2
  class B1 e3
  class B2 e3
  class C1 e3
  class C2 e3
  class D1 e3
  class D2 e3
  class E1 e3
  class E2 e3

二、目录结构设计：约定大于配置

React 项目的目录结构直接影响「新成员找到代码的速度」。好的结构应满足：按功能聚合、关注点分离、路径可预测。

推荐目录结构

flowchart TB
  classDef d1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef d2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef d3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[src/] --> B[components/<br/>通用组件]
  A --> C[features/<br/>业务模块]
  A --> D[hooks/<br/>自定义 Hook]
  A --> E[lib/<br/>工具与基础层]
  A --> F[api/<br/>接口封装]
  A --> G[routes/<br/>路由与页面]
  A --> H[styles/<br/>全局样式]
  A --> I[types/<br/>类型定义]

  C --> C1[feature-a/ 组件+逻辑+样式]
  C --> C2[feature-b/ 自包含模块]

  click C "https://martinfowler.com/articles/modularizing-react-apps.html" "模块化 React 应用"
  class A d1
  class B d2
  class C d2
  class D d2
  class E d2
  class F d2
  class G d2
  class H d2
  class I d2
  class C1 d3
  class C2 d3

目录设计原则

flowchart TD
  classDef p1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef p2 fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

  A[目录设计原则] --> B[按功能聚合<br/>组件与逻辑放一起]
  A --> C[路径别名<br/>短路径指向源码]
  A --> D[避免深层嵌套<br/>最多 3-4 层]
  A --> E[公共与业务分离<br/>components vs features]
  A --> F[命名一致<br/>PascalCase 组件]

  click C "https://vite.dev/config/shared-options" "路径别名配置"
  class A p1
  class B p2
  class C p2
  class D p2
  class E p2
  class F p2

三、代码规范工具链

代码规范的本质是「把争议交给机器」：格式化交给 Prettier，质量检查交给 ESLint，类型交给 TypeScript——开发者专注逻辑。

规范工具链

flowchart LR
  classDef t1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef t2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef t3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[代码提交] --> B[Prettier 格式化<br/>风格统一]
  A --> C[ESLint 检查<br/>质量规则]
  A --> D[TypeScript<br/>类型安全]
  B --> E[提交前 pre-commit]
  C --> E
  D --> E
  E --> F[代码入库]

  click C "https://eslint.org/docs/latest/use/getting-started" "ESLint 文档"
  class A t1
  class B t1
  class C t1
  class D t1
  class E t2
  class F t3

规范配置建议

flowchart TD
  classDef s1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef s2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef s3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[规范配置] --> B[ESLint 规则集]
  B --> B1[eslint-plugin-react<br/>组件规则]
  B --> B2[react-hooks<br/>Hooks 规则]
  B --> B3[jsx-a11y<br/>无障碍规则]
  A --> C[Prettier 配置]
  C --> C1[semi 分号]
  C --> C2[printWidth 行宽]
  C --> C3[singleQuote 引号]
  A --> D[Husky 钩子]
  D --> D1[pre-commit 格式检查]
  D --> D2[pre-push 质量门禁]

  click B2 "https://www.npmjs.com/package/eslint-plugin-react-hooks" "react-hooks 插件"
  class A s1
  class B s1
  class B1 s3
  class B2 s3
  class B3 s3
  class C s1
  class C1 s3
  class C2 s3
  class C3 s3
  class D s2
  class D1 s3
  class D2 s3

四、Git 协作流程：分支与提交规范

Git 流程决定团队协作的节奏。常见方案有 Git Flow（多分支严格）与 Trunk-based（主分支短命分支）。React 团队规模中等时，「主分支 + 特性分支 + PR 评审」是主流。

分支协作模型

flowchart TB
  classDef g1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef g2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef g3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[main 主分支<br/>始终可发布] --> B[feature/a<br/>功能开发]
  A --> C[feature/b<br/>功能开发]
  A --> D[hotfix<br/>紧急修复]
  B --> E[PR 评审合并]
  C --> E
  D --> E
  E --> F[发布版本标签]

  click E "https://docs.github.com/zh/pull-requests" "PR 文档"
  class A g1
  class B g2
  class C g2
  class D g2
  class E g3
  class F g3

提交信息规范（Conventional Commits）

flowchart LR
  classDef m1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef m2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef m3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A["feat: 新增文章列表筛选"] --> B[类型 feat 功能]
  C["fix: 修复移动端滚动卡顿"] --> D[类型 fix 修复]
  E["docs: 补充部署文档"] --> F[类型 docs 文档]
  G["refactor: 重构缓存逻辑"] --> H[类型 refactor 重构]
  I["perf: 优化首屏渲染"] --> J[类型 perf 性能]

  click A "https://www.conventionalcommits.org/zh-hans/" "提交规范文档"
  class A m1
  class B m3
  class C m1
  class D m3
  class E m2
  class F m3
  class G m2
  class H m3
  class I m2
  class J m3

规范收益：提交信息可读 → 变更历史可追溯 → 版本发布可自动生成 changelog。

五、代码评审：质量与传承的仪式

代码评审（PR Review）是团队知识的「汇流点」：评审者把关质量，被评审者传承经验。好的评审依赖清单而非感觉。

PR 评审清单

flowchart TD
  classDef r1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef r2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef r3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[评审清单] --> B[功能正确性<br/>边界与异常]
  A --> C[类型与规范<br/>TS 与 lint]
  A --> D[性能影响<br/>渲染与请求]
  A --> E[无障碍<br/>语义与键盘]
  A --> F[可维护性<br/>命名与结构]
  B --> G[测试覆盖<br/>关键路径有测试]

  click B "https://google.github.io/eng-practices/review/" "Google 评审指南"
  class A r1
  class B r1
  class C r2
  class D r2
  class E r2
  class F r2
  class G r3

评审的高效实践

  1. PR 尽量小（单次变更一个关注点）；
  2. 自动检查先行（lint/test 通过才进人工评审）；
  3. 评审意见「对事不对人」，附建议代码；
  4. 约定评审时限（如 24 小时内响应）；
  5. 文档与代码同步评审。

六、持续集成：把门禁交给机器

CI（持续集成）把「质量门禁」自动化：每次提交自动执行类型检查、测试、构建，不合格即拦截。这是工程化的「地基」。

CI 流水线

flowchart TB
  classDef c1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef c2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef c3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[代码推送到分支] --> B[安装依赖<br/>缓存加速]
  B --> C[类型检查 typecheck]
  C --> D[单元测试 test]
  D --> E[代码检查 lint]
  E --> F{全部通过}
  F -->|是| G[构建产物]
  G --> H{是否主分支}
  H -->|是| I[部署预览/发布]
  H -->|否| J[生成预览链接]
  F -->|否| K[标注失败 阻止合并]

  click G "https://github.com/features/actions" "GitHub Actions"
  class A c1
  class B c1
  class C c2
  class D c2
  class E c2
  class F c2
  class G c3
  class H c2
  class I c3
  class J c3
  class K c3

七、文档与知识沉淀

代码会演进，文档必须跟上。React 项目的文档体系应覆盖：README（快速上手）、架构决策记录（ADR）、组件文档（Storybook）、操作手册（部署/排障）。

文档体系

flowchart LR
  classDef w1 fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
  classDef w2 fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  classDef w3 fill:#e0f7fa,stroke:#00838f,color:#004d40

  A[文档体系] --> B[README<br/>环境搭建与启动]
  A --> C[ARCHITECTURE<br/>架构与决策]
  A --> D[Storybook<br/>组件文档]
  A --> E[Runbook<br/>部署与排障]

  click D "https://storybook.js.org/" "Storybook 文档"
  class A w1
  class B w1
  class C w2
  class D w2
  class E w2
  class F w3

八、总结

React 工程化是一套「共识 → 工具 → 文化」的体系：

  1. 代码层：Prettier + ESLint + TS 三件套，风格交给机器；
  2. 结构层：按功能聚合的目录，路径可预测；
  3. 协作层：特性分支 + PR 评审清单 + 提交规范；
  4. 自动化层：CI 质量门禁 + 自动部署；
  5. 治理层：监控复盘 + 文档沉淀 + 规范迭代。

实践建议：工程化要「先立后破」——先定最小可执行的规范（format + lint + typecheck 进 CI），再逐步扩展；规范的价值在于「所有人遵守同一套规则」，而不在于规则本身有多完美。下一篇我们将深入 TanStack Start 全栈框架与 SSR 的完整实战。