重庆市网站建设_网站建设公司_SSG_seo优化

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

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（正文）

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

Footer（页脚）

必须关联需求：关联需求: #需求编号

示例：关联需求: #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 # 未关联需求