前端开发规范

目的
研发流程
- 2.1 整体研发流程
- 2.2 开发流程
项目评估
- 3.1 项目评审
- 3.2 技术方案设计
- 3.3 任务管理
项目开发
- 4.1 项目代码管理
- 4.2 分支规范
- 4.3 环境说明
- 4.4 代码组织规范
- 4.5 代码质量
- 4.6 联调
- 4.7 代码提交
- 4.8 资源引用
- 4.9 Web安全
- 4.10 性能
- 4.11 统计上报
项目测试
- 5.1 自测
- 5.2 提测
- 5.3 跟测
项目发布
- 6.1 发布顺序
- 6.2 发布UAT
- 6.3 发布LIVE
线上问题跟进

1. 目的

本规范旨在汇集团队最佳开发实践经验，以更好地满足业务需求、避免研发事故、保证研发质量、保障业务安全、提高工作效率、提升用户体验。

2. 研发流程

2.1 整体研发流程

整体研发流程包括需求分析、技术方案设计、开发实施、测试验证、发布上线等阶段。

2.2 开发流程

开发流程包括：需求评审 → 技术方案设计 → 任务分解 → 代码开发 → 自测 → 提测 → 测试跟进 → 发布上线。

3. 项目评估

3.1 项目评审

需求评审：开发前产品会组织前后端和测试进行 PRD（产品需求文档）评审。
设计评审：如果需求有设计参与，PRD 确定后开发和设计人员会进行 UI/UX 评审。
确定技术方案：超过 5 天的需求需要技术负责人参加评审，复杂的技术需求需要输出技术方案文档。
评估工期：评估工期需要进行多方沟通，如果有需求变更，需要及时反馈给负责人，以评估并规避相关风险。

3.2 技术方案设计

3.2.1 技术选型

开发框架（前端框架提供 Vue、React 两种选择，遵循以下原则）

现有大型项目维持当前技术栈不变
新项目根据实际项目需要及团队情况，选择更合适的框架
内部项目鼓励尝试新技术，在达成目标的前提下可多样化选择
所有新项目建议结合 TypeScript 使用

组件库

React 项目和 Vue 项目都会各自长期维护一套公共基础组件库，项目应优先使用公共组件库进行开发。

组件库每次升级需遵循以下步骤：

新增 / 修改需求需出具含组件功能、影响范围的说明文档，提交团队技术委员会评审通过
需求评审通过后，出具技术方案并提交技术委员会评审通过
开发完成后提交 MR，通过技术委员会 Code Review，同步输出自测报告、版本升级说明（含修改明细、影响范围）
开发方出具本次升级的整体执行结果文档，整合上述三步的执行结果

使用方升级组件库版本，需要对升级可能影响到的所有功能代码负责：

告知整个项目组
明确升级影响范围，告知 QA
回归自测涉及到的功能点

基础库

基础库封装了与业务无关的基础公共方法，项目优先使用公共基础库进行开发。由整个团队共同维护构建。

3.2.2 评审

复杂技术方案，需和技术负责人沟通确认
项目组公共模块修改，必须通过项目组内评审
团队公共模块修改，必须通过团队技术委员会评审

3.3 任务管理

任务创建流程：

产品经理完成 PRD 后，为主任务（task）建立相应的任务单（默认指派给后端），相关人员信息填入任务单
技术负责人对任务进行评估分解，拆分成一个或多个子任务（subTask），进行工作量评估，指派给开发者

工作量评估

技术负责人通过任务单工作量字段开展评估，该字段最短 0.2 天、原则上最长不超过 3 天
所有产生工作量的任务均需建立主任务单并下设子任务（仅统计已完成状态子任务的工作量）
需求提测后产生的 bug，需建立 Bug 单跟进

开发流程

开发者从项目的前端仓库的 release 分支新建一个 feature 分支
将"任务 / 子任务"状态从"待处理 / 待办"修改为"开发中 / 进行中"
开发者在 feature 分支上进行代码开发，如果存在单个功能分支由多人开发，需要从 feature 分支再分出个人分支进行开发
根据后端提供的接口文档 mock 接口数据进行前端功能开发
如果项目代码有国际化要求，将新增翻译字段对应的 key 录入到翻译平台
开发者完成开发，将"任务 / 子任务"状态修改为"测试中 / 已完成"，将主任务（task）指派给 QA

管理工具

任务管理系统作为工作任务跟踪的工具
文档管理系统用于管理需求文档和开发文档等
需求文档会与对应的任务单链接，研发过程中需要及时维护任务状态，需求文档将自动同步更新状态

任务单必填字段

Fix Version: 版本号
Assignee: 指派人
Reporter: 一般为任务创建者
Developer: 开发人员
Dev Effort (days): 子任务中必填，记录工作量
Dev Start Date: 开发开始时间
Dev Due Date: 开发结束时间，如果不需要联调，这就是提测时间
QA Due Date：联调完成，提测时间
Due Date: 主任务中必填，部署UAT时间

4. 项目开发

4.1 项目代码管理

前端 Git 仓库，按照功能，划分为：

业务项目集合 - 业务项目集合
内部项目集合 - 团队内部项目集合

仓库组织规范：

业务项目按业务组划分至对应业务组顶层目录，内部项目存放至内部项目目录
新仓库按功能归入上述两个子目录，各项目组在其中搭建自有文件夹
内部项目在对应目录下以项目名建立分组，相关项目统一纳入，子项目命名需准确明晰

注意：公共项目改动前必须通过团队技术委员会评审、各项目公共模块改动必须技术负责人评审通过后，才可进行，修改完成需要严格进行 code review 和单元测试。

4.2 分支规范

基准分支

[强制] 新分支须从 release 分支 checkout 出来。 例如：

bash 复制代码

git checkout -b xxx/branch origin/release

命名规范

分支命名规范： feature/{jira}/{username}-{description}

username 为开发者姓名的小写缩写
jira 为该任务的任务单号，保留大写格式
description 为该任务简单描述，符合短横线命名规则

保护分支

每个项目包含 test、uat、版本分支（发版前技术负责人基于 release 分支切出版本分支）、master、release 等5个保护分支，任何人不能直接 push 代码到这几个分支
往保护分支发 MR 的时候要注意看自己 commit 的修改，不要引入别的不该部署的代码
所有环境（test 环境、uat 环境、staging 环境、live 环境）都由 QA 进行部署

4.3 环境说明

环境类型：

test 环境：面向群体为测试工程师，不会面向真实客户，作用是让测试工程师检验项目开发质量
uat 环境：面向群体为业务人员，属于外部环境，作用是在项目发布前让业务人员先体验项目功能，如果业务人员验收不合格，项目将会打回重新修改
staging 环境：面向群体为测试工程师，主要作用是让测试工程师在发布前做进一步回归测试，发布前的最后一道质量保障
live 环境：面向群体为所有真实用户，可以理解为真实的线上环境

环境与 Git 分支对应关系：

test 环境部署的是 test 分支的代码
uat 环境部署的是 uat 分支的代码
staging 环境部署的是 version 分支的代码
live 环境部署的是 release 分支的代码

4.4 代码组织规范

遵循编码规范
项目根目录下需增加 .gitignore 文件，.gitignore 文件中必须包含 node_modules
$建议\] 项目可参考团队提供的模板工程，通过统一脚手架生成$
开发遵循不信任原则：调用的 API / 后台接口必须处理错误与异常，引用对象及其属性前需进行正确性校验
组件建议测试覆盖率达到 80%
业务代码无覆盖率要求

4.6 联调

前后端共同制定接口协议，由后端同步至接口文档平台，并将文档地址粘贴到对应任务单描述中
提前确定好联调时间，严格按时间交付保证联调环境可用
联调期间若接口协议有修改或变更，需及时让后端更新接口说明文档

4.7 代码提交

每次向远端 Git 仓库推送代码的时候，都应该对本地代码进行相应检测。包括但不限于：

遵循 CommitLint 规范，要求推送的 Git message 符合要求
EsLint / TsLint
$建议\] StyleLint 根据项目需求，看是否需要进行样式相关的 Lint$

4.8 资源引用

代码中外链静态资源 URL 需采用相对协议 + 相对域名（此方式可由页面统一控制协议与域名，后续协议 / 域名变更时，仅修改页面网址即可，内部资源无需改动）；项目内资源使用项目相对路径
项目中的 js、css、图片等静态资源因启用长缓存，修改后必须重命名以彻底解决缓存问题（构建工具项目需开启文件 md5 重命名，手工维护的静态文件需手动修改文件名）

4.9 Web安全

前端请求统一使用公共基础库的请求模块发送，该模块已封装并为所有请求自动携带安全令牌
遵循不信任原则，对 URL 参数、后端返回内容、本地 Cookie 及 localStorage 等需插入页面 DOM 的内容，均需进行 XSS 输出过滤与充分转义
所有页面开启 CSP（内容安全策略），限制非法外联 / 内联脚本执行并及时上报
对不允许前端访问和修改的 Cookie 设置 HttpOnly 属性

4.10 性能

性能优化建议：

外链资源：样式表置于，脚本放页面底部；除基础框架外，优先异步按需引入，延迟加载非关键代码
代码压缩：上线源码需压缩混淆，文本类资源至少启用 gzip 压缩，可通过工具移除未使用代码
图片优化：上线图片必须压缩，单张建议不超过 100K，避免不必要下载，小图片优先用 CSS Icon 或 SVG Icon 替代
首屏内容：静态化处理，确保 JS 加载前有可见内容
测速统计：重要页面需上报测速数据，监测 First Contentful Paint、Time to Interactive、First Meaningful Paint、First CPU Idle、Estimated Input Latency、First Input Delay 等相关性能指标

5. 项目测试

5.1 自测

前端需在本地完成接口测试，遇问题及时与后端协商修改
功能开发后必须通过冒烟测试用例，按测试人员提供的用例完成功能自测

5.2 提测

MR 合入前须完成 Code Review，技术负责人、项目负责人参与 CR
将需求分支合入 test 分支的 MR 指派给对应 QA
合代码若有冲突，禁止在 git 上直接解决。需在本地从最新 test 分支切出 temp 分支，合入 feature 分支并在本地解决冲突（解决冲突需谨慎），解决完毕后将 temp 分支推远程后再合入 test 分支
Code Review 完成后，更新任务状态（子任务：进行中→已完成；主任务：开发中→测试中），并将主任务指派给对应 QA
QA 在 test 环境测试，提 Bug 单给开发者；开发者需及时修复所有 Bug，修复后重新提 MR 给 QA，同时将 Bug 单状态改为 "测试中" 并指派对应 QA；需多方配合的在 Bug 单处理人处添加相关人员，并在评论区说明情况

5.3 跟测

跟进测试时需及时处理所有 Bug
处理完一轮 Bug 后，将 Bug 单设为已解决并说明产生原因与解决方案，提交代码后通知测试同步验证；需相关方配合的，在 Bug 单处理人处添加对应人员，并在评论区说明情况

6. 项目发布

6.1 发布顺序

发布前，开发必须明确告知测试人员文件发布顺序；原则上被依赖文件优先发布，且需确认其生效后，再发布其他文件。

6.2 发布UAT

test 环境测试通过后，QA 通知开发者将 feature 分支合入 uat 分支，开发者需提 MR 并指派给技术负责人
合 uat 分支遇冲突时，与合 test 分支的冲突解决方式保持一致
所有分支（test、uat、版本分支、master 分支等）的冲突解决方式均需统一，避免引入新冲突

6.3 发布LIVE

发布流程：

版本发布前，产品提供本次可发版的确认 Jira 需求列表，技术负责人基于 release 分支切出 version 分支
开发者将本版本需求代码合入该 version 分支
QA 将 version 分支代码部署到 staging 环境，并在 staging 环境对功能进行上线前的最后一次完整回归测试
回归通过后，由技术负责人将版本分支合入 release分支

7. 线上问题跟进

新上线业务，业务负责人需密切关注质量监控系统的数据及告警信息，问题需第一时间跟进处理，同步处理结果并告知技术负责人
线上收集的不影响用户使用的非紧急问题，若无需紧急发布，可告知产品，以优化需求形式纳入后续版本开发
线上出现紧急问题需及时修复并走 hotfix 流程
1. 开发者基于 release 分支切出修复分支
2. 修复完成后将该分支分别合入 test、uat，由 QA 分别验证
3. 验证通过后，技术负责人将 feature 分支合入 release 分支

注意：hotfix 流程与普通发布流程不同，hotfix 中修复分支直接合入 release 分支；普通发布流程中需求分支需先合入 version 分支，经由 version 分支再合入 release 分支上线

附录：关键要点总结

开发阶段

✅ 所有新分支从 release 分支创建
✅ 遵循分支命名规范
✅ 代码提交前必须通过 Lint 检查
✅ 遵循不信任原则，做好错误处理和参数校验
✅ 静态资源使用相对路径，修改后需重命名

测试阶段

✅ 必须通过冒烟测试用例
✅ Code Review 后才能提测
✅ 冲突必须在本地解决，不能在线解决
✅ 及时跟进和处理所有 bug

发布阶段

✅ 明确文件发布顺序
✅ 解决冲突的方式保持一致
✅ 发布前进行完整回归测试

线上问题

✅ 密切关注监控系统告警
✅ 紧急问题走 hotfix 流程
✅ 及时反馈处理结果