【项目规范】如何从零开始，建立前端项目规范

carry12138
305 阅读6分钟

在多人协作项目中，项目规范是不可或缺的一部分。规范的代码是项目稳固的基础，只有严格遵守代码规范，我们的项目才不会陷入熵增无序的状态。

尽管代码规范如此重要，但是在迭代多，流动性大，工期紧的开发过程中，靠成员自觉维护项目规范难度很大。因此，一套好的代码规范，应该从始至终的贯穿于整个开发过程中。并且利用工具配置，尽可能实现自动化的代码规范。

当前的项目规范主要有一下几个重要节点。

  • 使用 eslint + stylelint + prettier 格式代码规范
  • 使用 vscode 实现自动格式化
  • 使用 commitment 约束提交规范
  • 使用 git hook + lint-staged 实现提交时的再次校验检测
  • 使用 Gitlab flow 分支管理策略

使用eslint + stylelint + prettier 规范代码格式

eslint 用于规范 javascript 和 jsx 语法

首先安装eslint和相关插件

npm install eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-simple-import-sort -D

再安装vscode的eslint插件

image.png

如果vscode右下角有ESlint字样 代表eslint已对当前工作区生效

image.png

prettier 用于格式化代码样式

安装prettier

npm i prettier -D

安装 vscode 的 prettier 插件

image.png

vue项目的 Vetur 插件底层原理也是采用 prettier 实现的，如果本地有prettier配置，vscode会优先采用本地规则。为了防止团队中 prettier 格式化规则冲突，最好在项目中配置一份 prettier 规则文件覆盖默认配置。

可以在项目根目录下新增一个 prettierrc.js 文件

module.exports = {
  // 末尾需要逗号
  trailingComma: 'all',
  // 不使用缩进符，而使用空格
  useTabs: false,
  // tab 用两个空格代替
  tabWidth: 2,
  // 添加分号
  semi: true,
  // 使用单引号
  singleQuote: true,
  // 一行最多 100 字符
  printWidth: 100,
  // 对象的 key 仅在必要时用引号
  quoteProps: 'as-needed',
  // jsx 不使用单引号，而使用双引号
  jsxSingleQuote: false,
  // 大括号内的首尾需要空格
  bracketSpacing: true,
  // jsx 标签的反尖括号需要换行
  jsxBracketSameLine: false,
  // 箭头函数，只有一个参数的时候，也需要括号
  arrowParens: "always",
  // 每个文件格式化的范围是文件的全部内容
  rangeStart: 0,
  rangeEnd: Infinity,
  // 不需要写文件开头的 @prettier
  requirePragma: false,
  // 不需要自动在文件开头插入 @prettier
  insertPragma: false,
  // 使用默认的折行标准
  proseWrap: 'preserve',
  // 换行符使用 lf
  endOfLine: 'lf',
  // 根据显示样式决定 html 要不要折行
  htmlWhitespaceSensitivity: 'css',
  overrides: [
    {
      files: '*.wxss',
      options: { parser: 'css' },
    },
    {
      files: '*.wxml',
      options: { parser: 'html', htmlWhitespaceSensitivity: 'strict' },
    },
    {
      files: '*.wxs',
      options: { parser: 'babel' },
    },
  ],
};

stylelint 用于规范 css 的语法和排序

安装stylelint

npm i stylelint -D

stylelint-order是用于css属性排序的插件，基本原理是影响元素布局的属性排在前面，如height，width等。只影响样式的属性排在后面，如color等。这个插件方便协同开发时更改样式，建议安装。

npm i stylelint-order -D

安装 vscode 插件

image.png

如果stylelint已经生效 则在工作台右下角会有stylelint标识

image.png

vscode 自动格式化配置

vscode提供项目级和本地setting.json 两个配置文件,在项目运行时，会优先使用项目中的配置。

保存自动格式化代码可以在项目的setting.json中配置。如下是一份模板。

{
  "files.eol": "\n",
  "editor.formatOnSave": true,
  "eslint.alwaysShowStatus": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.fixAll.stylelint": true
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "prettier.configPath": ".prettierrc.js",
  "minapp-vscode.wxmlFormatter": "prettier",
  "minapp-vscode.prettier": {
    "parser": "html"
  },
  "stylelint.validate": ["css", "scss", "wxss"],
  "stylelint.autoFixOnSave": true
}

commitment和git-cz 规范项目提交

在多人协作的项目中，如果Git的提交说明精准，在后期协作以及Bug处理时会变得有据可查，项目的开发可以根据规范的提交说明快速生成开发日志，从而方便开发者或用户追踪项目的开发信息和功能特性。

AngularJS提交规范

image.png

上图是AngularJS团队的git记录。相对于自定义message，上图的方案更加方便开发协同。

Angular团队的 Git Commit Guidelines 主要分为三部分：

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

上面是一次Commit后Message格式规范，分成标题，内容详情，结尾三个部分，各有各的用处，没有多余项。

头部即首行，是可以直接在页面中预览的部分，入上面图中所示，一共有三个部分，，，含义分别如下

  • feat：新功能（feature）
  • fix：修补bug
  • docs：文档（documentation）
  • style： 格式（不影响代码运行的变动）
  • refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  • test：增加测试
  • chore：构建过程或辅助工具的变动
Type
  • feat：新功能（feature）
  • fix：修补bug
  • docs：文档（documentation）
  • style： 格式（不影响代码运行的变动）
  • refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  • test：增加测试
  • chore：构建过程或辅助工具的变动
Scope

用来说明本次Commit影响的范围，即简要说明修改会涉及的部分。这个本来是选填项，但从AngularJS实际项目中可以看出基本上也成了必填项了。

Subject

用来简要描述本次改动，概述就好了，因为后面还会在Body里给出具体信息。并且最好遵循下面三条:

  • 以动词开头，使用第一人称现在时，比如change，而不是changed或changes
  • 首字母不要大写
  • 结尾不用句号(.)
Body
里的内容是对上面subject里内容的展开，在此做更加详尽的描述，内容里应该包含修改动机和修改前后的对比。
Footer

footer里的主要放置不兼容变更和Issue关闭的信息

此外如果需要撤销之前的Commit，那么本次Commit Message中必须以revert：开头，后面紧跟前面描述的Header部分，格式不变。并且，Body部分的格式也是固定的，必须要记录撤销前Commit的SHA值

Commitizen和git-cz 工具辅助实现git message格式化

commitizen/cz-cli是一个可以实现规范的提交说明的工具

Gitlab flow策略协助分支管理

协同开发过程中，必须有一个好的分支管理策略，项目才能井井有条不断推动下去。当前的分支管理策略主要有 git flow， github flow, gitlab flow这三种。关于工作流的具体介绍可以参考阮一峰老师的微博 Git工作流程

我们采用的是 Gitlab flow 分支管理策略，主要有以下特点：

  • 功能驱动开发。需求是开发的起点，先有需求再有功能分支（feature branch）或者补丁分支（hotfix branch）。完成开发后，该分支就合并到主分支，然后被删除。
  • 对于"持续发布"的项目，它建议在master分支以外，再建立不同的环境分支。比如，"开发环境"的分支是master，"预发环境"的分支是pre-production，"生产环境"的分支是production。
  • 开发分支是预发分支的"上游"，预发分支又是生产分支的"上游"。代码的变化，必须由"上游"向"下游"发展。
  • 功能分支合并进master分支，必须通过Merge Request。通知所有协同者。
  • master分支应该受到保护，不是每个人都可以修改这个分支，以及拥有审批 Pull Request 的权力
avatar
文章
阅读
粉丝