前端规范制定
2023-12-05 21:08:03 0 举报AI智能生成
一个前端Leader是如何制定前端协作规范的？前端协作规范并不单单指‘编码规范’，这个规范涉及到前端开发活动的方方面面，例如代码库的管理、前后端协作、代码规范、兼容性规范
作者其他创作
大纲/内容
规范是实现自动化的基础
规范是一个团队知识沉淀的直接输出
为什么需要规范？
主版本号：当你做了不兼容的 API 修改，
次版本号：当你做了向下兼容的功能性新增，
修订号：当你做了向下兼容的问题修正。
语义化版本规范
1.1.1 版本规范
git-flow
集中式工作流
功能分支工作流
Fork工作流
参考
制定git分支模型/工作流
1.1.2 版本控制系统规范
格式统一的提交信息有助于自动化生成CHANGELOG
规范化提交信息可以促进提交者提交有意义的、粒度合适的'提交'. 提交者要想好要怎么描述这个提交，这样被动促进了他们去把控提交的粒度
优点
Atom
Angular
Eslint
JQuery
规范
从项目的提交信息中生成CHANGELOG和发布信息
conventional-changelog
检验提交信息
commitlint
🔥简单的提交规范和提交帮助工具，推荐
commitizen
angular风格的提交命令行工具
standard-changelog
工具
1.1.3 提交信息规范
1.1 开发
统一的构建工具链，应该强调\"约定大于配置\"，让开发者更专注于业务的开发
vue-cli3抽离了cli service层，可以独立更新工具链
约定大于配置，开箱即用
灵活的插件机制，实现独立的更新
要求
强约定，体现团队的规范，暴露最小化的配置接口
集成代码检查、测试等功能
方便升级
特点
🔥零配置开始React开发
create-react-app
🔥零配置、渐进增强的项目构建CLI
vue-cli
零配置的Web应用打包工具
parcel
高速易用的打包工具
Fusebox
microbundle
1.2 构建规范
代码变更
提交代码变更到远程版本库
程序通过CI测试(例如Travis变绿)
提升package.json中的版本
生成CHANGELOG
提交package.json和CHANGELOG.md文件
打上Tag
推送
流程
conventional-changelog-cli
conventional-github-releaser
举例
1.3 发布工作流规范
本质上就是把传统瀑布式的软件开发流程打碎，形成一个个更小的开发闭环，持续地输出产品，同时产品也持续地给上游反馈和纠正。
可以理解为'频繁'或者‘连续性’. 不管是持续集成还是敏捷开发思维、看板，都认为‘持续’是它们的基础。
比如代码检查，‘持续的’的代码检查就是代码一变动(如保存，或者IDE实时检查、或者提交到版本库时)就马上检查代码，而‘非持续’的代码检查就是在完成所有编码后，再进行检查
持续(Continuous)
狭义的集成可以简单认为是‘集成测试’
广义的持续集成服务，不仅仅是测试，它还衍生出很多概念，例如持续交付、持续部署
集成
概念
尽早发现错误，快速试错。越早发现错误，处理错误的成本越低
执行的环境. 比如容器、Node版本、操作系统等等
触发的条件。比如定时触发、在哪个分支触发、会触发什么任务等等
执行的任务
检查：包括单元测试和代码lint. 所有push到版本库的代码都会跑这个阶段. 一般可以在提交title中包含[ci skip]来跳过这个阶段
构建: 对前端项目进行构建. 只有打上版本tag的提交或release分支会跑构建任务
发布: 将前端的构建结果进行交付/发布. 只有打上版本tag的提交或者release分支在构建成功后会跑发布任务
划分持续集成的阶段.
定义持续集成脚本模板
Travis CI
CircleCI
完整列表
Github
GitLab: Gitlab-CI
Jenkins
通用
cli服务
持续集成更详细解释
1.4 持续集成
看板是目前最为流行的任务管理工具，它可以帮助我们了解项目的进度、资源的分配情况、还原开发现场.
基于issue看板 - 可以基于Gitlab或Github的Issue来做任务管理，它们都支持看板。很Geek，推荐
Tower - 专门做看板任务管理的。小团队基本够用。我们现在就使用这款产品
teambition - 和Tower差不多，没有深入使用过
Trello - 颜值高.
阿里云看板
腾讯云看板
1.5 任务管理
1 工作流规范
选择你最熟悉的技术
选择拥有强大生态和社区支撑的开源技术
选择成长期的技术
API的稳定性
基础设施配合
选型需要充分地理解业务，理解用户需求，当下需要解决的首要问题，以及可能的风险有哪些，再将目标进行分解，进行具体的技术选型、模型设计、架构设计
业务考虑
谈谈技术选型
谈谈技术选型的注意事项
参考文档
2.1 技术选型
考虑团队成员的接纳能力。如果成本小于收获的利益，在团队里面推行估计阻力会比较大
学习成本
是否能够解决当前的某些痛点
收益
一般我们不能将一个实验阶段的技术使用的生产环境中
考虑风险
2.2 迎接新技术
编程语言 - Typescript或Javascript
UI框架
路由
状态管理
组件库
国际化
动画
服务端渲染
脚手架、CLI工具
组件测试
样式. 包含了命名规范、预处理器、方法论等等
动画引擎
QA. 包含了测试、Lint、格式化工具、监控
项目构建工具流. 例如webpack、vue-cli
包管理器。npm、yarn
项目管理工具
时间处理。例如Moment.js
模板引擎
开发工具
后端开发框架
工具库
开发/调试工具
规范包括
2 技术栈规范
前端团队应该根据针对应用所面对的用户情况、应用类型、开发成本、浏览器市场统计数据等因素，来制定自己的浏览器兼容规范，并写入应用使用手册中.
有了浏览器兼容规范，前端开发和兼容性测试就有理有据，避免争议; 同时它也是前端团队的一种对外声明，除非特殊要求，不符合浏览器兼容规范的浏览器，前端开发人员可以选择忽略。
渐进增强保证低版本浏览器的体验，对于支持新特性的新浏览器提供稍好的体验
渐进增强
优雅降级则是相反的，为现代浏览器提供最好的体验，而旧浏览器则退而求之次，保证大概的功能.
优雅降级
3.1 确定兼容策略
浏览器兼容文档示例
完全兼容: 保证百分百功能正常
部分兼容: 只能保证功能、样式与需求大致一致。对于一些不影响主体需求和功能的bug，会做降低优先级处理或者不处理。
不兼容: 不考虑兼容性
3.2 确定浏览器分级
百度统计
友盟
Google Analytics 需要kx上网
大厂支持的监控平台
百度流量研究院：主要提供国内浏览器统计
statcounter: 国际浏览器统计
浏览器发布年份统计
通用的浏览器数据统计
caniuse
MDN
html5test
获取浏览器支持特性网站
3.3 获取统计数据
3 浏览器兼容规范
简要描述、项目主要特性
运行环境/依赖、安装和构建、测试指南
简单示例代码
联系方式、讨论群
许可、贡献/开发指南
package.json: 前端项目必须. 描述当前的版本、可用的命令、包名、依赖、环境约束、项目配置等信息.
.gitignore: 忽略不必要的文件，避免将自动生成的文件提交到版本库
.gitattributes: git配置，有一些跨平台差异的行为可能需要在这里配置一下，如换行规则
examples/: 项目的示例代码，可选.
build: 项目工具类脚本放置在这里，非必须。如果使用统一构建工具，则没有这个目录
dist/: 项目构建结果输出目录
src/: 源代码目录
tests: 全局的测试目录，通常放应用的集成测试或E2E测试等用例
.env 通用的环境变量
.env.development 开发环境的环境变量
.env.production 生成环境的环境变量
.env.*.local 本地覆盖以上配置
.env*: 项目中我们通常会使用环境变量来影响应用在不同运行环境下的行为. 可以通过dotEnv来从文件中读取环境变量.
（开源）LICENSE: 说明项目许可
CODE_OF_CONDUCT: 行为准则
COMMIT_CONVENTION: 提交信息规范，上文已经提及
ISSUE_TEMPLATE: Issue的模板，github可以自动识别这个模板
PULL_REQUEST_TEMPLATE: PR模板
（开源）.github: 开源贡献规范和指南
4.1 通用的项目组织规范
按照文件的类型划分为不同的目录
Rails-style
按照一个功能特性或业务创建单独的目录，这个目录就近包含多种类型的文件或目录
Domain-style
通常将相关联的元素定义在一个文件下
Ducks-style
混合
4.2 目录组织的风格
项目结构规范确定下来后，可以创建自己的脚手架工具或者项目模板，用于快速初始化一个项目或代码模板
yeoman - 老牌的项目脚手架工具
plop - 代码生成辅助CLI
hygen - 类似于plop
babel-code-generator - 利用babel来实现更高级的代码编辑和自动生成
4.3 脚手架和项目模板
4 项目组织规范
ESLint - 🔥目前是社区最流行的、通用的Javascript Lint工具，Lint界的Babel。支持定制插件、preset。如果不想折腾可以选择它的一些预定义配置
Lint工具
JavaScript Standard Style - 🔥 零配置的、‘标准’的Javascript编码规范. 底层基于Eslint。目前不支持Typescript
Airbnb JavaScript Style Guide - Airbnb的编码规范，业界标杆
Typescript - 🔥 Javascript语言的超集，这是一门‘新’的语言，而不是简单的类型检查器. 不过它也支持原生Javascript的类型检查
Flow - Facebook出品的类型检查器，语法和Typescript类似. 个人推荐使用Typescript
类型检查. 暂时将它们归类到这里，因为它们同属于‘静态测试’
5.1 Javascript
HTMLHint
bootlint
Code Guide
5.2 HTML
stylelint - 🔥 通用的CSS编码检查工具，支持最新的CSS语法、CSS-in-js、以及其他类CSS语法(如SCSS、Less). 它也有预定义配置，推荐使用
Airbnb CSS / Sass Styleguide
更多
BEM - 🔥 BEM命名规范
OOCSS
smacss
方法论
5.3 CSS
Prettier
5.4 代码格式化
编程原则、设计思想. 例如符合SOLID原则? 是否足够DRY？接口设计是否简洁易扩展、
模块耦合程度、代码重复
代码健壮性。是否存在内存泄露、是否线程安全、是否有潜在性能问题和异常、错误是否被处理
代码的性能和效率。
是否有没有考虑到的场景？
检查清单
Code Review可以让其他成员都熟悉代码。这样保证其他人都可以较快地接手你的工作，或者帮你解决某些问题
提高代码质量。毫无疑问. 一方面是主动性的代码质量提升，比如你的代码需要被人Review，会自觉尽量的提高代码质量；另一方面，其他成员可以检查提交方的代码质量
好处
提交时. 大部分开源项目采用这种方式。通俗讲就是Pull Request。只有代码通过测试、和其他成员的Review才可以合进正式版本库。这种方式也称为‘阻塞式’代码检查，一般配合GitFlow使用。
方式
是否要做Code Review？与BAT资深架构师争论之后的思考
5.7 Code Review
5 编码规范
石墨文档
腾讯文档
Git+Markdown
6.1 建立文档中心
对于开发者来说，MarkDown是最适合的
6.2 文档格式
接口的索引
接口的版本、变更记录
功能说明
方法名称或者URI
参数和返回值定义
调用示例
注意事项等等
描述具体的接口
举例API文档
6.3 定义文档的模板
设计方案
新功能、新技术引入
重构
性能优化
决策/建议
问题讨论
重大事件
计划或进度跟踪
话题记录示例
标签管理
方便归档组织，索引和查找
issue
像流水一样，一去不复返
IM
6.4 讨论即文档
ESlint是可以对注释进行一定程度的规范
6.5 注释即文档
工具会分析代码的数据类型，自动帮我们生成参数和返回值定义，这也可以减少很多文档编写工作以及出错率
tsdoc Typescript官方的注释文档标准
typedoc 基于tsdoc标准的文档生成器
Typescript
API文档
jsdoc Javascript文档注释标准和生成器
Javascript
Swagger Restful接口文档规范
Easy Mock 一个可视化，并且能快速生成模拟数据的服务
后端接口文档
StoryBook 通用的组件开发、测试、文档工具
Docz
Styleguidist
React
组件文档
vue-styleguidist
Vue
6.6 代码即文档
6 文档规范
提供团队协作效率(产品和开发)
提高组件的复用率. 统一的组件规范可以让组件更好管理
保持产品迭代过程中品牌一致性
意义
7 UI设计规范
UI组件测试: 包括了快照(Snapshot)测试
单元测试: 对独立的软件模块进行测试
集成测试: 在单元测试的基础上，将模块组合起来，测试它们的组合性
E2E测试: 在完整、真实的运行环境下模拟真实用户对应用进行测试。主要测试前端和后端的协调性
兼容性测试: 上面提到了浏览器兼容规范，在将版本提交给测试/发布之前，需要确保能符合兼容性要求
性能测试: 测试和分析是否存在性能问题
安全测试
SEO测试
其他:
整体测试
8.1 测试的流程
单元测试是集成测试的基础
测试即文档。如果文档不能解决你的问题，在你打算看源码之前，可以查看单元测试。通过这些测试用例，开发人员可以直观地理解程序单元的基础API
提升代码质量。易于测试的代码，一般都是好代码
测试覆盖率来量化
比如要求语句覆盖率达到70%；核心模块的语句覆盖率和分支覆盖率都要达到100%. 视团队情况而定
测试指标
puppeteer
Headless Chromium
Headless Browsers: 无头浏览器是网页自动化的重要运行环境。 常用于功能测试、单元测试、网络爬虫
testing-library 🔥
Enzyme
Intern
测试框架
AVA
Jasmine
Mocha
Tape
单元测试
Chai
expect.js
should.js
断言库
sinon.js
Mock/Stubs/Spies
istanbul
代码覆盖率
benchmark.js
jsperf.com
基准测试
8.2 单元测试
8 测试规范
9.1 异常处理
避免重复打印日志
规范（示例）
9.2 日志
浏览器兼容性。
碎片收集(breadcrumbs)。 收集‘灾难’现场的一些线索，这些线索对问题诊断很重要。例如当前用户信息、版本、运行环境、打印的日志、函数调用栈等等
调用栈的转换。通常在浏览器运行的压缩优化过的代码，这种调用栈基本没什么可读性，通常需要通过SourceMap映射到原始代码. 可以使用这个库: source-map
数据的聚合。后端监控系统需要对前端上报的信息进行分析和聚合
处理
9.3 异常监控
9 异常处理、监控和调试规范
典型的工作流程
需求分析。参与者一般有前后端、测试、以及产品. 由产品主持，对需求进行宣贯，接受开发和测试的反馈，确保大家对需求有一致的认知
前后端开发讨论。讨论应用的一些开发设计，沟通技术点、难点、以及分工问题.
设计接口文档。可以由前后端一起设计；或者由后端设计、前端确认是否符合要求
在联调之前，要求后端做好接口测试
真实环境联调。前端将接口请求代理到后端服务，进行真实环境联调。
详细
10.1 协作流程规范
明确数据类型。很多后端写的接口都是string和number不分的，如果妥协的话、前端就需要针对这个属性做特殊处理，这也可能是潜在的bug
明确空值的意义。比如在做更新操作是，空值是表示重置，还是忽略更新？
响应避免冗余的嵌套。
接口版本化，保持向下兼容。就像我们上文的‘语义化版本规范’说的，对于后端来说，API就是公共的接口. 公共暴露的接口应该有一个版本号，来说明当前描述的接口做了什么变动，是否向下兼容。
现在前端代码可能会在客户端被缓存，例如小程序。如果后端做了break change，就会影响这部分用户。
注意的点
JSONRPC 这是一种非常简单、容易理解的接口规范，上手快，简单
GraphQL 🔥更为先进、更有前景的API规范，难度很高
标准定义的接口形式
10.2 接口规范
版本号
文档描述
服务的入口. 例如基本路径
测试服务器. 可选
简单使用示例
安全和认证
方法名称或者URL
方法描述
请求参数及其描述，必须说明类型(数据类型、是否可选等)
可能的异常情况、错误代码、以及描述
请求示例，可选
具体接口定义
包含的信息
10.3 接口文档规范
Mock Server给前端提供模拟数据
Mock Client则辅助后端对它们的接口进行测试.
理想模型
10.4 接口测试与模拟
10 前后端协作规范
介绍公司背景和产品，一般组织的团队结构和产品的架构是相关联的
产品架构与组织架构
介绍产品开发和迭代会涉及到的流程、以及团队之间的协作衔接
产品研发流程
团队成员的职责范围
工作范围
开发需要设计到的资源，比如各种文档地址、研发系统入口(例如gitlab、bug跟踪系统、文件共享、发布平台、开发/测试环境、监控系统)、协作规范等等
建立资源索引
有规范可循，可以让成员以较快的速度入手开发、同时也减少培训成本投入。
规范:
团队新成员培训手册
11.1 新人培训
鼓励成员写技术博客，或者建立自己的团队专栏. 写一篇好的文章不容易
写文
鼓励参与开源项目
组织一起解一些面试题或算法题，加深对知识点的理解
建立面试题库
鼓励团队成员定期进行专题学习和研究，编写技术博客，并将学习的成果分享给其他成员. 这是一种抱团取暖的学习方式，旨在帮助团队成员一起学习和成长。
比如开发老手可以分享自己的经验，研究更深层次的技术；新手则可以研究某些开发技巧、新技术，例如CSS Grid，svg动画等等。推荐团队成员有个明确的研究领域，这样分工合作可以学习到更多东西.
专题请求. 可以请求其他成员完成专题，比如比较深的知识，可以要求团队比较有经验的进行学习分享
学习总结.
项目回顾
难点攻克
项目规范
工具使用
专题怎么来?
定期的专题分享.
. 规范本身就是团队知识沉淀的一种直接输出
落实和完善开发规范
和离散的文章或教程相比，图书的知识会比较系统，另外很多经典的图书是要静下来好好欣赏的。
图书分享.
鼓励重构和持续优化代码
11.2 营造技术氛围
11 培训/知识管理/技术沉淀
前端协作规范制定
收藏
收藏
0 条评论
回复 删除
下一页
