本文档是一套经过实践验证的前端团队协作规范涵盖代码风格、开发流程、质量门禁和文档管理适用于 3-20 人规模的前端团队。1 设计初衷1.1 解决的问题问题传统方式本规范方案代码风格不统一口头约定执行不一文档化规范 自动检查新人上手慢师徒口传效率低结构化文档自主学习代码质量参差Code Review 主观判断量化标准客观评估文档滞后事后补写与代码脱节同步更新文档即入口重构无章法凭经验风险高分层规范渐进收敛1.2 核心目标可执行规范必须可自动化检查不依赖人工记忆可追溯文档记录最终状态不保留中间过程可收敛代码持续向规范靠拢不因历史问题放任新增可扩展规范分层维护新增规则有明确归属2 规范体系架构2.1 文档结构project-root/ ├── docs/# 正式文档│ ├── README.md# 文档总入口│ ├── code-style/# 代码规范│ │ ├── README.md# 规范入口│ │ ├── directories.md# 目录规范│ │ ├── api.md# API 层规范│ │ ├── services.md# 业务流程层规范│ │ ├── stores.md# 状态层规范│ │ ├── models.md# 模型层规范│ │ ├── components.md# 组件规范│ │ ├── pages.md# 页面规范│ │ ├── styles.md# 样式规范│ │ ├── unit-tests.md# 单元测试规范│ │ └── docs.md# 文档规范│ │ │ ├── design/# 功能设计│ │ ├── pages/# 页面设计│ │ └── models/# 模型设计│ │ │ ├── global-design/# 全局能力设计│ ├── components/# 公共组件说明│ └── quality/# 质量问题记录│ ├── src/# 业务代码├── mock/# Mock 服务└── __tests__/# 单元测试2.2 规范层级层级文档职责L1 总则README.md总原则、适用范围、执行约束L2 分层规范code-style/*.md各层代码组织和风格要求L3 设计文档design/页面和模型的最终状态L4 质量记录quality/待跟进问题和改进项3 核心设计原则3.1 Source Of Truth单一真相源原则每个规则只有一个主维护位置其他文档通过链接引用。# ✅ 正确引用主维护位置 API 请求层规范详见 [API 规范](./code-style/api.md)。 # ❌ 错误多处重复维护 API 请求层规范...重复内容优势避免规范不一致修改一处全局生效降低维护成本3.2 代码向规范收敛原则所有新增代码必须遵守规范改动旧代码时新增区域和修改区域也要符合规范。适用范围 - ✅ 新增代码严格遵守 - ✅ 改动区域必须符合 - ✅ 重组代码向规范收敛 - ⚠️ 未触碰代码不顺手扩大改造执行策略# 小范围修复只调整本次触达区域gitdiff--name-only# 只看改动文件# 较大改动先评估是否需要重构# 1. 检查是否涉及旧实现迁移# 2. 确认是否按分层规范重构# 3. 获得确认后再执行3.3 业务分层原则原则代码按职责分层依赖方向单向不跨层调用。┌─────────────────────────────────────────────────────────┐ │ Pages页面层 │ │ - 组合组件、hooks、状态 │ │ - 调用 services 和 stores │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Components组件层 │ │ - 纯 UI 渲染 │ │ - 通过 props 接收数据 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Services业务流程层 │ │ - 编排业务逻辑 │ │ - 调用 API 和 stores │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Stores状态层 │ │ - 管理应用状态 │ │ - 提供 selector 和 action │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ API请求层 │ │ - 封装 HTTP 请求 │ │ - 处理响应转换 │ └─────────────────────────────────────────────────────────┘依赖规则✅ Pages → Components, Services, Stores, API✅ Services → Stores, API✅ Stores → API❌ API → Services, Stores禁止反向依赖❌ Components → Services, Stores禁止直接调用3.4 优先靠近使用场景原则页面专属代码默认放在页面目录内只有形成稳定复用关系后才上提到共享目录。// ✅ 正确页面专属 hook 放在页面目录src/pages/dashboard/hooks/use-dashboard-data.ts// ❌ 错误尚未复用就提到共享目录src/hooks/use-dashboard-data.ts判断标准场景位置仅单页面使用src/pages/page/hooks/2-3 个页面稳定复用src/hooks/全局通用src/hooks/或src/lib/3.5 信任后端接口原则后端接口返回数据按接口定义信任不堆叠额外兜底判断。// ✅ 正确信任接口定义interfaceUser{id:string;// 必填name:string;// 必填email?:string;// 可选}functionrenderUser(user:User){return${user.name}(${user.id});}// ❌ 错误过度兜底functionrenderUser(user:User){constiduser?.id??unknown;constnameuser?.name??Anonymous;return${name}(${id});}4 开发流程规范4.1 较大任务处理流程┌─────────────────────────────────────────────────────────┐ │1. 确认入口文档 │ │ - 页面文档、组件文档、全局能力文档 │ │ - 涉及的模型和功能点编号 │ │ - 相关的单元测试入口 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │2. 给出处理方案 │ │ - 改动范围评估 │ │ - 分层归属判断 │ │ - 是否涉及旧实现迁移 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │3. 用户确认后执行 │ │ - 实现代码 │ │ - 自动修复和格式化 │ │ - 定向测试验证 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │4. 更新文档 │ │ - 更新设计文档最终状态 │ │ - 更新入口文档索引如需 │ │ - 记录质量问题到 quality/ │ └─────────────────────────────────────────────────────────┘4.2 边界控制原则原则只处理本次任务边界内的问题发现边界外问题只记录不修复。## 本次边界 - 修改范围src/pages/dashboard/ - 涉及模型docs/design/models/analytics.md M3.1 - 不处理src/pages/settings/ 的历史问题 ## 发现的边界外问题 - [ ] src/pages/settings/ 组件超过 800 行 - [ ] src/stores/user.ts 缺少类型定义4.3 角色分离原则原则实现、review 和校验角色分离不混在同一轮处理。实现阶段 - 编写代码 - 运行自动修复 - 补充测试 Review 阶段 - 检查行为回归 - 检查测试缺口 - 检查规则偏离 校验阶段 - typecheck - lint - 定向测试5 质量门禁5.1 自动检查流程# 1. 自动修复npmrun lint:fix --修改的文件npmrunformat--修改的文件# 2. 格式检查npmrun format:check --修改的文件# 3. 类型检查npmrun typecheck# 4. 代码检查npmrun lint# 5. 定向测试npmrun test:unit:boundaries# 静态边界基线npmrun test:unit:module --模块名# 功能模块测试5.2 测试覆盖原则测试分类类型用途适用对象功能行为测试验证业务功能公共组件、API、services、stores静态边界测试验证代码规范目录、依赖、命名、样式归属覆盖范围必须测试 - ✅ 公共组件的稳定契约 - ✅ API 请求层的能力 - ✅ Services 的业务流程 - ✅ Stores 的状态管理 不测试 - ❌ 页面入口和页面内部组件 - ❌ 布局入口和布局内部组件 - ❌ Mock 服务实现 - ❌ 单纯文档调整5.3 测试组织规范__tests__/ ├── boundaries/# 静态边界测试所有 src/ 改动的基线├── api-request/# API 请求层测试├── global-user/# 用户能力测试├── reference-data/# 参考数据测试└──module-name/# 功能模块测试├── feature-a.test.ts └── feature-b.test.ts执行规则最小执行单位是功能模块目录不是单个测试文件boundaries/是所有src/改动的固定基线同时涉及多个模块时分别执行所有相关目录6 文档管理规范6.1 文档结构规范# 文档标题 一句话说明本文档的职责和适用范围。 最终校订时间YYYY-MM-DD 最终状态当前已生效状态。 ## 1 总章节说明 说明本文档内各章节的功能与作用。 ## 2 正文章节 正文内容。6.2 文档更新规则场景操作页面功能调整更新docs/design/pages/对应文档模型字段变更更新docs/design/models/对应文档组件能力变更更新docs/components/对应文档全局能力变更更新docs/global-design/对应文档发现质量问题记录到docs/quality/6.3 文档入口维护原则新增或调整正式文档时必须同步更新对应入口文档。# docs/design/pages/README.md | 页面 | 文档路径 | 源码目录 | 当前状态 | |------|----------|----------|----------| | 首页 | [home.md](./home.md) | src/pages/home/ | 已实现 | | 设置 | [settings.md](./settings.md) | src/pages/settings/ | 已实现 |7 代码组织规范7.1 目录职责目录职责内容src/pages/页面入口页面组件、页面 hooks、页面 storessrc/components/公共组件跨页面复用的 UI 组件src/hooks/共享 hooks跨模块复用的 React hookssrc/services/业务流程编排 API、stores 和业务逻辑src/stores/状态管理全局状态、selector、actionsrc/api/请求层HTTP 请求封装、响应转换src/models/数据模型业务对象、DTO、类型定义src/lib/工具库通用工具函数、浏览器能力src/constants/常量全局常量、配置项7.2 文件拆分策略场景拆分方式页面文件过大拆为components/、hooks/、view.ts、actions.tsStore 文件过大拆为state.ts、selectors.ts、actions.ts、persistence.ts样式文件过大按页面或组件就近放入模块目录7.3 命名规范类型规范示例目录名kebab-caseuser-profile/、api-request/文件名kebab-caseuse-current-user.ts、request-client.ts组件名PascalCaseUserProfile、DashboardPanelHook 名camelCase use 前缀useCurrentUser、useDashboardData类型名PascalCaseUserProfile、ApiResponse常量名UPPER_SNAKE_CASEAPI_BASE_URL、MAX_RETRY_COUNT8 执行约束8.1 适用范围强制执行 - ✅ 所有新增代码 - ✅ 改动区域的新增代码 - ✅ 被重组的相邻代码 渐进收敛 - ⚠️ 历史遗留问题分阶段治理 - ⚠️ 未触碰的旧代码不顺手扩大 豁免 - ❌ 第三方运行时代码 - ❌ 明确记录的临时例外8.2 例外处理## 临时例外记录 - 文件src/legacy/old-module.ts - 原因第三方库要求特定格式 - 影响范围仅该文件 - 后续计划2026-Q4 重构时迁移8.3 评审检查清单## Code Review 检查项 - [ ] 新增代码是否符合分层规范 - [ ] 是否存在跨层依赖 - [ ] 是否有过度兜底判断 - [ ] 页面专属代码是否放在页面目录 - [ ] 共享代码是否有稳定复用关系 - [ ] 是否同步更新相关文档 - [ ] 是否补充必要的单元测试9 最佳实践9.1 函数设计单一职责// ✅ 正确每个函数只做一件事functionvalidateInput(input:Input):ValidationResult{...}functionbuildCommand(input:Input):Command{...}asyncfunctionsubmitCommand(command:Command):PromiseResult{...}// ❌ 错误一个函数做多件事asyncfunctionhandleSubmit(input:Input){// 验证if(!input.name)returnerror(Name required);// 转换constcommand{...input,timestamp:Date.now()};// 提交constresultawaitapi.submit(command);// 处理结果if(result.success)navigate(/success);}参数对象化// ✅ 正确参数对象有明确类型typeCreateUserInput{name:string;email:string;role:UserRole;};functioncreateUser(input:CreateUserInput):PromiseUser{...}// ❌ 错误参数过多或类型模糊functioncreateUser(name:string,email:string,role:string,...){...}9.2 状态管理Store 设计// ✅ 正确清晰的状态结构typeUserStore{// 状态currentUser:User|null;isLoading:boolean;error:string|null;// Actionslogin:(credentials:Credentials)Promisevoid;logout:()void;// SelectorsisLoggedIn:()boolean;displayName:()string;};9.3 组件设计Props 设计// ✅ 正确Props 有明确类型和文档typeUserCardProps{/** 用户数据 */user:User;/** 是否显示邮箱 */showEmail?:boolean;/** 点击回调 */onUserClick?:(userId:string)void;};// ❌ 错误Props 类型模糊typeUserCardProps{data:any;options?:Recordstring,unknown;};10 适用场景10.1 适用3-20 人前端团队项目周期 3 个月以上使用 React TypeScript有 Code Review 流程追求代码质量一致性10.2 不适用1-2 人小项目规范成本过高快速原型开发优先速度纯静态页面无复杂逻辑10.3 可裁剪项规范可选/必选裁剪条件文档体系可选小团队可简化单元测试可选快速原型可省略分层规范必选保证代码质量命名规范必选保证一致性11 总结本规范的核心价值标准化统一的代码风格和组织方式可执行自动化检查不依赖人工可追溯文档记录最终状态可收敛代码持续向规范靠拢可扩展规范分层维护易于扩展适用团队追求代码质量和协作效率的前端团队。预期收益新人上手时间减少 50%Code Review 效率提升 30%代码质量问题减少 40%