前端开发规范实践

news/2025/10/22 10:41:19/文章来源:https://www.cnblogs.com/pengjiali/p/19157334

前端开发规范实践

本文档总结了前端开发团队在代码规范、质量控制、版本管理和开发流程等方面的一些实践，旨在帮助团队建立统一的开发标准，提高代码质量和开发效率。

1. 前端编码规范管理

1.1 统一编码规范

1.1.1 命名规范

变量命名：使用小驼峰命名法（camelCase），布尔类型使用 is/has/can 前缀，常量使用全大写下划线分隔（UPPER_SNAKE_CASE）
函数命名：使用小驼峰命名法，动词开头（get/set/handle/on/fetch/update/delete/create/validate）
组件命名：使用大驼峰命名法（PascalCase），文件名与组件名保持一致
文件命名：组件文件使用 PascalCase，工具文件使用 camelCase，样式文件使用 kebab-case
禁止使用：单字母变量名（循环除外）、拼音命名、无意义命名（temp/data1/foo）

1.1.2 代码格式规范

工具配置：使用 Prettier 统一格式化，ESLint 进行代码检查，Stylelint 规范样式代码
基本规则：2空格缩进，单行最大100字符，语句结尾使用分号，字符串优先使用单引号，对象/数组尾部添加逗号
代码组织：按功能模块划分目录，避免循环依赖，每个文件只导出一个主要功能

1.1.3 注释规范

文件头注释：必须包含文件功能描述、作者、创建日期

/*** @file 用户管理服务* @author 前端开发团队* @date 2035-11-11*/

函数注释：使用 JSDoc 格式，说明参数、返回值、使用示例

/*** 获取用户信息* @param userId - 员工ID* @returns 员工信息对象*/
function getUserInfo(userId: string): User {}

复杂逻辑注释：关键算法、业务规则、临时方案必须添加注释，使用 TODO/FIXME 标记待优化代码
注释语言：统一使用中文，专业术语可保留英文

1.1.4 日志格式规范

日志级别：ERROR（错误需立即处理）、WARN（警告潜在问题）、INFO（重要操作记录）、DEBUG（调试信息，仅开发环境）
日志格式：[时间戳] [级别] [模块] 日志内容 {上下文数据}

// 示例
console.error('[2035-11-11 10:30:15] [ERROR] [UserLogin] 用户登录失败', { userId: '3456789', reason: 'password error' 
});

日志规范：错误日志必须包含堆栈信息，关键业务操作必须记录，敏感信息（密码/身份证）禁止记录，生产环境禁止使用 console.log

1.1.5 TypeScript 规范

类型定义：禁止使用 any，优先使用接口（interface）定义对象类型，使用类型别名（type）定义联合类型
类型导出：统一在 types/ 目录管理类型定义，公共类型集中导出
类型转换：优先使用 as 进行类型转换，避免过度使用非空断言（!）
空值处理：使用可选链（?.）和空值合并（??）操作符处理可能为空的值，减少运行时错误

1.1.6 代码复杂度控制

函数长度：单个函数不超过 80 行，圈复杂度不超过 10，嵌套层级不超过 4 层
代码可读性：
- 避免魔法数字，使用命名常量代替
- 使用提前返回（early return）模式减少嵌套层级
- 合理使用解构赋值简化代码
- 使用有意义的变量名，避免单字母变量（循环变量除外）
- 将复杂逻辑拆分为多个小型、专注的函数

1.1.7 安全编码规范

输入验证：
- 所有外部输入（用户输入、API 返回数据）必须验证
- 使用白名单方式验证数据格式，不信任任何外部数据
- 对特殊字符进行适当转义，防止 XSS/SQL 注入攻击
禁止使用：eval()、Function 构造函数、innerHTML（优先使用 textContent 或框架提供的安全渲染方法）
敏感数据处理：
- 敏感数据（密码、密钥、token）禁止前端明文存储
- 使用加密算法保护必要的敏感信息
- API 请求使用 HTTPS，敏感接口添加额外验证机制

1.1.8 框架最佳实践

Vue 3 项目：必须参考 Vue 3 官方风格指南和 Vue 3 最佳实践
React 项目：必须参考 React 官方文档最佳实践和 React TypeScript 最佳实践
组件设计：遵循单一职责原则，合理拆分组件，使用 Composition API（Vue）或 Hooks（React）
性能优化：避免不必要的重渲染，合理使用 memo/computed/watch，懒加载路由和组件

1.1.9 依赖管理规范

包管理器：强制使用 pnpm，禁止使用 yarn
依赖安装：区分 dependencies 和 devDependencies，避免安装未使用的依赖
版本管理：锁定主要依赖版本，定期更新依赖并测试兼容性

1.2 编码规范工具配置

1.2.1 工具配置要求

必须安装的工具

所有前端项目必须配置以下三个工具，缺一不可：

ESLint：代码质量检查，发现潜在 Bug 和不规范代码
Prettier：代码格式化，统一代码风格
Stylelint：样式代码规范检查（CSS/SCSS/Less）

配置文件清单

项目根目录必须包含以下配置文件：

.eslintrc.js / .eslintrc.cjs: ESLint 配置
.prettierrc.json: Prettier 配置
.stylelintrc.json: Stylelint 配置
.eslintignore: ESLint 忽略文件
.prettierignore: Prettier 忽略文件

1.2.2 工具配置规范

ESLint 配置要求

推荐使用阿里@iceworks/eslint-config-ali（Airbnb 规范变体）。可继承业界成熟规范（二选一，团队统一）。

框架特定配置：

Vue 项目：必须继承 plugin:vue/vue3-recommended + @typescript-eslint/recommended
React 项目：必须继承 plugin:react/recommended + plugin:react-hooks/recommended + @typescript-eslint/recommended

核心规则要求（不可豁免）：

禁止使用 any 类型（@typescript-eslint/no-explicit-any: error）
圈复杂度不超过 10（complexity: ['error', 10]）
嵌套层级不超过 4（max-depth: ['error', 4]）
单函数最大行数 80 行（max-lines-per-function: ['warn', 80]）
生产环境禁止 console 和 debugger（no-console: ['error', { allow: ['error'] }]）

Prettier 配置要求

参考业界主流配置，必须遵循以下统一格式：

使用分号（semi: true）
使用单引号（singleQuote: true）
每行最大 100 字符（printWidth: 100）
缩进 2 个空格（tabWidth: 2）
对象/数组尾部添加逗号（trailingComma: 'all'）

Stylelint 配置要求

推荐配置：

继承 stylelint-config-standard （Stylelint 官方推荐）
继承 stylelint-config-prettier （避免与 Prettier 冲突）
使用 stylelint-order 插件强制 CSS 属性排序

核心规则：

禁止使用颜色名称，必须使用十六进制（color-named: 'never'）
类名使用 BEM 规范或小驼峰命名（团队统一）
禁止使用 !important（特殊情况需注释说明）

1.2.3 工具集成与执行

Git Hooks 强制检查

参考字节跳动、美团等大厂实践，必须安装 husky + lint-staged：

// package.json
{"lint-staged": {"*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"],"*.{css,scss,less}": ["stylelint --fix", "prettier --write"]}
}

IDE 集成配置

强制要求团队成员配置 IDE（参考阿里、腾讯团队规范）：

安装 ESLint、Prettier、Stylelint 插件
开启"保存时自动格式化"功能
使用项目配置文件，禁止使用个人自定义配置
推荐使用 VS Code 并共享团队 .vscode/settings.json

CI/CD 流程检查

参考大厂 DevOps 实践，在持续集成流程中必须执行：

pnpm run lint        # 运行 ESLint 检查
pnpm run format      # 运行 Prettier 检查
pnpm run lint:style  # 运行 Stylelint 检查

检查失败处理：

CI/CD 构建失败，禁止合并代码
必须修复所有 Error 级别问题
Warning 级别问题记录在案，限期修复（48小时内）

1.2.4 违规处理

检查结果分级

Error（错误）：必须立即修复，阻断代码提交和合并
Warning（警告）：建议修复，不阻断提交但需在代码审查时说明
Off（关闭）：特殊场景可关闭某些规则，需注释说明原因

豁免机制

特殊情况可临时禁用规则，但必须添加注释说明：

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const data: any = legacyApiResponse; // 理由：对接旧系统，类型复杂暂不定义

豁免审批要求：

单文件豁免超过 3 处，需技术负责人审批
禁止全局关闭规则（除非配置文件中明确说明理由）

1.2.5 配置维护

配置更新流程

工具配置由技术负责人统一维护
配置变更需团队评审通过
更新配置后需通知全员，并提供迁移指南
每半年评审一次配置合理性，对标业界最新实践

配置版本管理

配置文件纳入 Git 版本控制
禁止个人随意修改配置
不同项目可适度调整，但核心规则必须一致
定期关注业界动态，及时更新规范库版本

2. 前端代码质量管理

代码质量是项目成功的关键因素，直接影响系统的稳定性、可维护性和性能。本章介绍如何通过一系列工具和流程，建立完善的代码质量管理体系，确保团队交付高质量的前端产品。

2.1 代码质量标准与指标体系

2.1.1 质量目标

我们设定了明确的质量目标，作为团队代码质量的基本要求：

单元测试覆盖率 ≥ 80%
代码重复率 < 5%
圈复杂度平均值 < 10
严重漏洞数量 = 0

2.1.2 质量指标

从多个维度评估代码质量，确保全方位控制：

可靠性：Bug密度 < 5个/千行，无严重漏洞和崩溃风险
可维护性：代码重复率 < 5%，单函数 < 80行，文档完善
测试覆盖：行覆盖率 ≥ 80%，分支覆盖率 ≥ 75%，核心业务逻辑 100%
性能效率：关键操作响应时间 < 300ms，页面加载时间符合性能指标
安全性：无高危安全漏洞，敏感数据得到有效保护

2.1.3 质量评级

根据综合表现对代码质量进行评级：

A级（优秀）：所有指标达标，测试覆盖率 > 90%，无任何警告或错误
B级（良好）：主要指标达标，测试覆盖率 80%-90%，少量警告但无错误
C级（合格）：基本指标达标，测试覆盖率 ≥ 80%，无严重问题
D级（不合格）：存在严重问题（如安全漏洞、高Bug率、低测试覆盖率），禁止合并

2.2 强制代码静态扫描管理（SonarQube）

所有前端项目必须接入 SonarQube 平台。扫描范围覆盖所有源代码，排除构建产物和依赖库。

扫描范围

覆盖所有 src/ 目录下的源代码
排除 node_modules/、dist/、build/ 等构建产物
包含测试代码（*.test.ts、*.spec.ts）

必检规则

Bug 规则：空指针引用、资源未关闭、死代码、类型错误
漏洞规则：XSS 漏洞、敏感数据泄露、不安全的依赖
代码异味：代码重复、函数过长、圈复杂度过高、嵌套过深
安全热点：硬编码密钥、弱加密算法、不安全的 HTTP 请求

新增代码门禁（强制）

Bug 数量：0
漏洞数量：0
代码异味：< 3个/千行代码
测试覆盖率：≥ 80%
代码重复率：< 3%

整体代码门禁

严重 Bug（Blocker/Critical）：0 个
严重漏洞（Blocker/Critical）：0 个
技术债务比率：< 5%
整体覆盖率：≥ 80%

门禁策略：

新代码必须 100% 达标（A 级标准）
存量代码允许适当降低标准，但严重问题必须为 0
核心业务模块执行更严格的门禁标准

触发时机

代码提交：每次 Push 到远程仓库自动触发
Pull Request：创建 PR/MR 时自动扫描
定时扫描：每日凌晨 2:00 全量扫描
发布前扫描：版本发布前必须执行扫描

强制执行机制

CI/CD 集成：代码提交、PR 创建时自动触发扫描
门禁阻断：未通过质量门禁，禁止合并代码
自动通知：扫描失败自动通知提交者和技术负责人
发布前检查：版本发布前必须通过扫描

扫描结果管理

问题处理流程:

自动通知：扫描完成后自动发送报告给提交者
问题分类：按严重级别分类，标记责任人
修复跟踪：在项目管理系统中创建任务，跟踪修复进度
复查验证：修复后重新扫描验证

扫描报告:

报告内容：质量门禁状态、问题统计、趋势分析、重点问题列表
报告发布：自动生成报告并发送给项目负责人
报告归档：保留所有历史扫描记录，支持趋势对比

2.3 单元测试管理（覆盖率≥80%）

单元测试是保障代码质量的第一道防线，不仅能帮助我们发现潜在问题，还能确保代码在重构和迭代过程中保持稳定。良好的单元测试可以显著降低生产环境中的Bug数量，提高代码的可维护性。

2.3.1 测试覆盖率强制要求

行覆盖率：≥ 80%
分支覆盖率：≥ 75%
函数覆盖率：≥ 85%
核心业务逻辑：100% 覆盖

特殊要求：

新增代码覆盖率必须 ≥ 80%，不允许降低整体覆盖率
工具函数、业务逻辑层、数据处理层必须 100% 覆盖
UI 组件覆盖率可适当降低至 ≥ 70%

2.3.2 测试框架与工具

Vue 项目：Vitest + Vue Test Utils
React 项目：Jest + React Testing Library
覆盖率工具：Istanbul (c8)
测试文件命名：*.test.ts 或 *.spec.ts

2.3.3 测试用例编写规范

文件组织：每个源文件对应一个测试文件，放置在同一目录，命名为 [原文件名].test.[ts/js]
测试结构：使用 AAA 模式（Arrange-Act-Assert）编写测试
- Arrange（准备）：设置测试环境和数据
- Act（执行）：调用被测试函数或组件
- Assert（断言）：验证结果是否符合预期
测试覆盖：
- 正常场景：确保功能正常工作
- 边界值：测试输入的边界条件
- 异常处理：验证错误处理机制
- 异步操作：正确处理 Promise、回调等
依赖管理：
- Mock 所有外部依赖（API 调用、第三方库、时间函数）
- 使用工具如 Jest 的 mock 功能或 Mock Service Worker
测试命名：使用描述性名称，如 should return correct value when input is valid

2.3.4 测试执行与门禁

本地执行：代码提交前必须通过测试，Git Hooks 自动运行
CI/CD 执行：每次代码提交自动运行全量测试
门禁标准：所有测试用例通过 + 覆盖率达标，否则禁止合并代码
报告生成：自动生成覆盖率报告，发布到项目看板

2.4 代码审查管理

代码审查是确保代码质量的重要环节，不仅能发现潜在问题，还能促进团队知识共享和技术交流。通过严格的代码审查流程，可以有效提升整体代码质量和团队编码水平。

2.4.1 代码审查强制要求

所有代码必须通过审查后方可合并，禁止直接提交到主干分支
每个 Pull Request 至少 2 人审查（其中 1 人为资深开发或技术负责人）
审查时效：一般 PR 2 个工作日内完成，紧急 PR 4 小时内完成
审查者需确保充分理解需求和实现方案，再进行代码审查

2.4.2 审查标准

代码审查应从以下几个维度全面评估：

功能性：代码实现是否符合需求，业务逻辑是否正确
代码质量：是否符合编码规范，可读性、复杂度是否合理
安全性：是否存在安全漏洞，输入验证是否完善
测试完整性：是否包含单元测试，覆盖率是否达标
性能合理性：是否存在明显性能问题，是否有优化空间
可维护性：代码结构是否清晰，命名是否规范，注释是否完善

2.4.3 审查流程

开发人员创建 Pull Request，填写变更说明和需求关联
自动触发 CI/CD 检查（ESLint、SonarQube、单元测试）
分配审查人员（至少 2 人）
审查人员检查代码并提出意见
开发人员修改并回复审查意见
所有审查人员批准 + CI/CD 通过后合并代码

2.4.4 审查结果处理

通过：所有审查人员批准 + 自动化检查通过
需修改：存在问题需修改后重新审查
拒绝：存在严重问题（安全漏洞、严重 Bug、严重违反规范）

2.5 代码质量门禁与度量

2.5.1 质量门禁机制

代码必须通过以下所有门禁检查方可合并：

编码规范检查：ESLint/Prettier/Stylelint 全部通过
静态扫描检查：SonarQube 质量门禁通过（无严重 Bug 和漏洞）
单元测试检查：所有测试通过 + 覆盖率 ≥ 80%
代码审查检查：至少 2 人审查通过

任一门禁未通过，CI/CD 构建失败，禁止合并代码。

2.5.2 代码质量度量指标

代码重复率：< 5%（工具：SonarQube、jscpd）
圈复杂度：平均 < 10，单函数 ≤ 10（工具：ESLint complexity）
函数长度：单函数 < 80 行（工具：ESLint max-lines-per-function）
嵌套深度：≤ 4 层（工具：ESLint max-depth）
技术债务：技术债务比率 < 5%，定期还债

2.5.3 质量数据统计与通报

统计维度：按人员、项目、时间统计代码质量指标
通报频率：每月通报一次
通报内容：质量门禁通过率、测试覆盖率、代码质量评分、常见问题总结
持续改进：每季度评审质量标准，针对高频问题完善规范和培训

3. 前端代码版本控制管理

规范的版本控制是现代软件开发的基础，对于前端团队尤为重要。良好的版本控制实践能够确保代码变更可追溯、可回滚，减少团队协作中的冲突，并为持续集成/持续部署提供可靠支持。本章介绍代码提交规范、分支管理策略和发布流程等最佳实践。

3.1 代码提交规范（Commit Message、变更说明、需求关联）

3.1.1 Commit Message 格式规范

标准格式

<type>(<scope>): <subject>
<body>
<footer>

Type（提交类型）

feat：新功能
fix：Bug 修复
docs：文档变更
style：代码格式调整（不影响功能）
refactor：重构（既不是新功能也不是 Bug 修复）
perf：性能优化
test：测试相关
chore：构建工具或辅助工具变更

Subject（主题）

简明扼要描述变更内容，不超过 50 个字符
使用祈使句，首字母小写，结尾不加句号
示例：feat(user): 添加用户登录功能

Body（正文）

详细描述变更内容、原因和影响（可选，复杂变更必填）

必须关联需求：关联需求: #需求编号
示例：关联需求: #1234

3.1.2 变更说明强制要求

每次代码提交必须清楚说明：

做了什么变更（What）：具体修改了哪些功能或代码
为什么变更（Why）：变更的原因和目的
影响范围（Impact）：对现有功能的影响

禁止的提交信息：

无意义信息（如"update"、"fix"、"修改"）
过于简单的描述
包含敏感信息（密码、密钥等）

3.1.3 需求关联强制要求

所有功能类提交（feat、fix）必须关联需求编号
格式：关联需求: #需求编号，多个需求用逗号分隔
需求编号来源：项目管理系统或 Issue 编号
Git Hooks 自动检查，未关联需求禁止提交
特殊情况豁免：docs、chore 类型可不关联需求

3.1.4 提交粒度控制

单次提交原则：一次提交只做一件事，功能完整且可运行
提交大小限制：单次提交变更文件 ≤ 20 个，代码行数 ≤ 1000 行
禁止行为：
- 多个不相关变更合并提交
- 提交未完成或无法运行的代码
- 提交包含调试代码（console.log、debugger）
- 提交临时文件或敏感配置

3.1.5 提交检查与执行

Git Hooks 检查：提交前自动检查 Commit Message 格式和需求关联
CI/CD 验证：代码推送后验证提交信息规范性
违规处理：提交信息不规范或未关联需求，禁止提交，需修改后重新提交

示例：

# 正确示例
feat(user): 添加用户登录功能- 实现用户名密码登录
- 添加验证码验证
- 集成登录状态管理关联需求: #1234# 错误示例（禁止）
update  # 无意义
修改了一些代码  # 过于简单
fix bug  # 未关联需求

3.2 代码分支管理策略（Git Flow）

3.2.1 分支模型规范

采用 Git Flow 分支模型，分支类型如下：

main/master：生产环境分支，只允许合并，禁止直接提交
develop：开发环境分支，只允许合并，禁止直接提交
feature/：功能开发分支，从 develop 创建，完成后合并回 develop
release/：发布准备分支，从 develop 创建，合并到 main 和 develop
hotfix/：紧急修复分支，从 main 创建，合并到 main 和 develop

3.2.2 分支命名规范

功能分支：feature/需求编号-功能描述，示例：feature/1234-user-login
发布分支：release/版本号，示例：release/1.2.0
修复分支：hotfix/bug编号-bug描述，示例：hotfix/5678-login-error

命名使用小写字母和连字符，禁止使用中文、空格或特殊字符。

3.2.3 分支保护策略

main/develop 分支保护：

禁止直接提交，必须通过 Pull Request 合并
必须通过代码审查（至少 2 人批准）
必须通过 CI/CD 检查（编码规范、SonarQube、单元测试）
禁止强制推送（git push -f）

3.2.4 分支生命周期管理

分支创建：从指定源分支创建，遵循命名规范
开发过程：定期从源分支同步代码，避免长期分离
分支合并：合并前同步最新代码，解决冲突，通过所有检查
分支删除：合并后及时删除远程分支和本地分支
分支清理：定期清理超过 30 天未活动的分支

3.3 代码合并与冲突处理

3.3.1 分支合并规范

合并方式：
- feature → develop：使用 Squash Merge（合并为单个提交）
- release/hotfix → main：使用 Merge Commit（保留合并记录）
- 禁止使用 Fast-Forward Merge
合并前检查：
- 同步最新代码，解决所有冲突
- 本地测试通过
- CI/CD 检查通过
- 代码审查通过

3.3.2 冲突处理规范

预防冲突：及时同步主干代码，频繁提交小变更
解决原则：保留正确代码，与冲突方沟通确认
复杂冲突：超过 10 个文件冲突或核心模块冲突，需技术负责人参与
测试验证：冲突解决后必须本地测试验证

3.4 版本发布管理

3.4.1 版本号管理规范

采用语义化版本（Semantic Versioning）：主版本号.次版本号.修订号

主版本号（MAJOR）：不兼容的 API 变更
次版本号（MINOR）：向后兼容的功能新增
修订号（PATCH）：向后兼容的 Bug 修复

示例：1.2.3

预发布版本：

1.2.3-alpha.1：内部测试版
1.2.3-beta.1：公开测试版
1.2.3-rc.1：发布候选版

3.4.2 版本发布流程

从 develop 创建 release 分支
更新版本号（package.json）
生成 CHANGELOG（变更日志）
测试验证
合并到 main 分支并打 Tag
部署到生产环境
合并回 develop 分支

3.4.3 Tag 标签管理

命名格式：v + 版本号，示例：v1.2.3
创建时机：版本发布时创建，指向 main 分支
Tag 说明：包含发布说明（Release Notes）
管理要求：Tag 一旦创建不可修改或删除

3.4.4 变更日志（CHANGELOG）

每次发布必须更新 CHANGELOG.md，内容包括：

新增功能列表
Bug 修复列表
破坏性变更说明
升级注意事项
已知问题

格式示例：

## [1.2.0] - 2035-11-11### 新增
- 用户登录功能 (#1234)
- 权限管理模块 (#1235)### 修复
- 修复登录失败问题 (#5678)### 破坏性变更
- API 接口调整，需更新调用方式

3.3.5 发布检查清单

发布前必须完成以下检查：

所有功能测试通过
单元测试覆盖率 ≥ 80%
SonarQube 扫描通过（无严重问题）
性能测试通过
安全扫描通过
文档更新完成
CHANGELOG 更新完成
版本号更新完成

未通过检查禁止发布。

4. 前端技术栈规范

在快速发展的前端领域，技术选型和规范使用至关重要。统一的技术栈能够避免技术碎片化，降低团队学习和维护成本，提高协作效率。本章定义了项目中应使用的核心技术栈、框架版本和工程化工具，确保团队在技术选择上保持一致性。

4.1 核心框架规范（Vue 3、React 18+、TypeScript）

4.1.1 框架选型要求

前端框架：Vue 3 或 React 18+（项目立项时确定，不得混用）
开发语言：强制使用 TypeScript，禁止使用 JavaScript
构建工具：统一使用 Vite
包管理器：强制使用 pnpm，禁止使用 yarn

4.1.2 Vue 3 项目规范

组合式 API：优先使用 Composition API，禁止使用 Options API
状态管理：使用 Pinia，禁止使用 Vuex
路由管理：使用 Vue Router 4+
UI 组件库：Element Plus 或 Ant Design Vue
工具库：VueUse（组合式函数）

4.1.3 React 项目规范

函数组件：强制使用函数组件 + Hooks，禁止使用 Class 组件
状态管理：使用 Redux Toolkit (RTK) 或 Zustand，禁止使用传统 Redux
路由管理：使用 React Router v6+
UI 组件库：Ant Design 或 Material-UI
工具库：ahooks（React Hooks 库）

4.1.4 TypeScript 规范

严格模式：启用 strict: true
禁止 any：禁止使用 any 类型，使用 unknown 或具体类型
类型定义：公共类型统一在 types/ 目录管理
类型导入：使用 import type 导入类型

4.2 工程化工具规范（Vite、pnpm）

4.2.1 Vite 配置要求

所有项目使用 Vite 作为构建工具
配置文件：vite.config.ts
必须配置：路径别名（@ 指向 src）、环境变量、代理配置

4.2.2 pnpm 使用规范

包管理器：强制使用 pnpm，禁止使用 npm 或 yarn
依赖安装：区分 dependencies 和 devDependencies
锁文件：pnpm-lock.yaml 必须提交到版本库
Workspace：多包项目使用 pnpm workspace 管理

4.2.3 环境变量管理

使用 .env 文件管理环境变量
环境文件：.env.development、.env.production、.env.test
变量命名：VITE_ 前缀（Vite 要求）
敏感配置：禁止提交到版本库，使用 .env.local

4.3 状态管理规范（Pinia、Redux Toolkit/Zustand）

4.3.1 Vue 项目 - Pinia

Store 组织：按业务模块划分 Store（如 useUserStore、useProductStore）
Store 位置：统一在 src/store/modules/ 目录
命名规范：使用 use 前缀，小驼峰命名
持久化：使用 pinia-plugin-persistedstate 插件

4.3.2 React 项目 - Redux Toolkit / Zustand

Redux Toolkit：
- 使用 createSlice 创建 Slice
- 异步逻辑使用 createAsyncThunk
- 禁止手动编写 Action Types 和 Reducers
Zustand（推荐轻量级项目）：
- Store 文件放在 src/store/ 目录
- 使用 create 创建 Store
- 避免过度使用全局状态

4.3.3 状态管理最佳实践

仅管理全局共享状态，局部状态使用组件 State
避免在 Store 中存储可计算的派生数据
异步操作统一在 Store 中处理，组件保持纯净

4.4 UI 组件库规范（Element Plus、Ant Design）

4.4.1 组件库选型

Vue 项目：Element Plus（推荐）或 Ant Design Vue
React 项目：Ant Design（推荐）或 Material-UI
同一项目只能使用一个 UI 组件库，禁止混用

4.4.2 按需引入

使用按需引入，避免全量引入
Vue：使用 unplugin-vue-components 自动导入
React：使用 babel-plugin-import 按需加载

4.4.3 主题定制

统一配置主题色、字体、间距等设计 Token
主题配置文件统一管理（src/styles/theme.scss）
禁止在组件中硬编码颜色和尺寸

4.5 工具库与依赖管理规范

4.5.1 推荐工具库

HTTP 请求：Axios（统一封装在 src/utils/request.ts）
日期处理：Day.js（禁止使用 Moment.js）
工具函数：lodash-es（按需引入）
表单验证：
- Vue：Vuelidate 或组件库自带验证
- React：React Hook Form + Yup

4.5.2 依赖管理要求

版本锁定：主要依赖锁定版本号（如 "vue": "3.3.4"）
定期更新：每季度更新依赖并测试兼容性
安全扫描：使用 pnpm audit 扫描安全漏洞
禁止安装：未使用的依赖、已废弃的包

4.5.3 第三方库引入审批

引入新的第三方库需技术负责人审批
评估标准：
- 是否有维护（最近 6 个月有更新）
- 社区活跃度（GitHub Star > 1000）
- 许可证兼容性（避免 GPL 等强传染性协议）
- 包大小（避免引入过大的库）

4.6 代码规范工具集成

所有项目必须集成以下工具：

ESLint + Prettier + Stylelint
Git Hooks（husky + lint-staged）
EditorConfig（统一编辑器配置）

5. 前端开发流程管理

需要原因：标准化的开发流程能够确保项目按计划推进，需求、设计、开发、测试各环节有序衔接，减少返工和沟通成本，提高交付效率和质量。

5.1 需求评审与技术方案设计

需求评审：

参与人员：产品经理、前端负责人、后端负责人、测试负责人
评审内容：需求合理性、技术可行性、工作量评估、风险识别
输出物：需求文档、原型图、评审意见记录
评审通过标准：技术可行、资源充足、风险可控

技术方案设计：

方案内容：技术选型、架构设计、模块划分、接口定义、性能指标
评审机制：技术负责人评审，复杂方案需技术委员会评审
文档输出：技术方案文档，包含架构图、流程图、接口文档
存档管理：方案文档纳入项目文档库

5.2 开发任务分解与计划管理

任务分解：

按功能模块拆分任务，单个任务工作量 ≤ 3 人天
任务粒度：可独立开发、测试、提交
明确任务依赖关系和优先级

计划管理：

使用项目管理工具（Jira、禅道）管理任务
每日更新任务进度，及时识别风险
每周进行进度评审，调整计划

5.3 本地开发环境规范

开发环境要求：

Node.js 版本：16.x+
包管理器：pnpm 8.x+
IDE：推荐 VS Code
浏览器：Chrome 最新版 + Vue/React DevTools

开发规范：

开发前同步最新代码，创建功能分支
频繁提交代码，避免长时间未提交
提交前运行测试和规范检查
每3日至少同步一次主干分支代码

5.4 联调测试流程

联调准备

前后端接口文档对齐（使用 Swagger 或其他业界工具）
Mock 数据准备，前端先行开发
联调环境部署，确保网络互通

联调流程：

后端提供接口文档和测试环境
前端根据文档调用接口
发现问题记录到项目管理系统
双方协商解决问题
联调通过后进入测试阶段

5.5 上线发布流程

发布流程：

创建 release 分支
更新版本号和 CHANGELOG
提交测试验收
完成发布应急文档
合并到 main 分支并打 Tag
构建生产环境包
部署到生产环境
发布验证
通知相关人员

发布回滚：

发布后发现严重问题，立即根据应急文档进行回滚
回滚操作需技术负责人批准
回滚后分析问题原因，修复后重新发布

发布记录

记录发布时间、版本号、发布人、变更内容
发布记录归档保存，作为追溯依据

6. 前端性能与安全管理

在当今互联网时代，前端应用的性能和安全性直接影响用户体验和业务成功。性能优化能够显著提升用户满意度和转化率，而安全管理则是保护用户数据和系统稳定的关键。本章将介绍前端性能优化的最佳实践和安全防护策略，帮助团队构建高性能、高安全性的前端应用。

6.1 性能优化规范

性能指标要求：

首屏加载时间：< 2 秒（4G 网络）
白屏时间（FCP）：< 1.5 秒
可交互时间（TTI）：< 3.5 秒
Lighthouse 评分：性能评分 > 90 分

性能优化要求：

代码分割：使用路由懒加载，大组件异步加载
资源压缩：图片压缩（WebP 格式优先）、代码压缩（Gzip/Brotli）
缓存策略：合理设置静态资源缓存，使用 CDN 加速
防抖节流：频繁触发的事件（滚动、输入）必须防抖或节流
虚拟列表：长列表（> 100 条）使用虚拟滚动

性能监控：

集成性能监控工具（如 Sentry 等业界推荐工具）
关键页面添加性能埋点
定期生成性能报告并优化

6.2 前端安全管理

6.2.1 安全编码规范

XSS 防护：
- 禁止使用 innerHTML、dangerouslySetInnerHTML
- 用户输入必须转义，使用框架提供的安全方法
- 使用 CSP（内容安全策略）限制资源加载
CSRF 防护：
- 敏感操作使用 CSRF Token
- API 请求验证 Referer 或 Origin
敏感数据保护：
- 密码、密钥等敏感信息禁止前端存储
- LocalStorage/SessionStorage 存储数据需加密
- 禁止在代码中硬编码密钥和配置