你需要知道的前端代码规范化基础知识

高尚的尚
965 阅读9分钟

前言：这是一篇在草稿箱落灰很久的文章

一、初始化项目

创建项目

mkdir xxx
cd xxx

初始化git仓库

git init

yarn初始化

# 可根据个人喜好使用npm或者yarn作为包管理
yarn init

二、代码规范化

这里我们采用 EditorConfig + Prettier + ESLint + StyleLint 来约束代码规范化。

好处：

  • 约束团队成员代码不规范导致的可读性、可维护性问题。
  • 解决不同编辑器导致的编码规范不一致问题。
  • 提前发现代码风格问题，并给出对应规范提示，及时修复。
  • 减少代码审查过程中反反复复的修改过程，节约时间。
  • 自动格式化，统一编码风格。

EditorConfig 配置

EditorConfig 解决了不同 IDE 编辑器编码风格不统一问题。editorconfig官网

在项目根目录下增加 .editorconfig 文件，内容如下：

# Editor configuration, see http://editorconfig.org

# 表示是最顶层的 EditorConfig 配置文件
root = true

[*] # 表示所有文件适用
charset = utf-8 # 设置文件字符集为 utf-8
indent_style = space # 缩进风格（tab | space）
indent_size = 2 # 缩进大小
end_of_line = lf # 控制换行类型(lf | cr | crlf)
trim_trailing_whitespace = true # 去除行首的任意空白字符
insert_final_newline = true # 始终在文件末尾插入一个新行

[*.md] # 表示仅 md 文件适用以下规则
max_line_length = off
trim_trailing_whitespace = false

Prettier 配置

Prettier支持 JS、TS、CSS、SCSS、Less、JSX、TSX、React、Angular、Vue、GraphQL、JSON、Markdown 等多种语言，是一款十分强大的代码格式化工具，prettier官网

1.安装prettier

yarn add prettier -D

2.根目录下创建 Prettier 配置文件

本项目采用.prettierrc 文件（Prettier 支持多种格式的配置文件，如 .json、.yml、.yaml、.js等），内容如下:

{
  "useTabs": false,
  "tabWidth": 2,
  "printWidth": 100,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "semi": true,
  "arrowParens": "avoid",
  "jsxBracketSameLine": false
}

3.至此Prettier 已经安装配置完成，你可以使用下面命令来格式化你的代码

# 格式化所有文件（. 表示所有文件）
npx prettier --write .

ESLint 配置

ESLint想必大家都不陌生，其核心是通过对解析得到的 AST（Abstract Syntax Tree 抽象语法树）进行模式匹配，分析代码、检查代码质量并提供修复能力。

1.安装 ESLint

yarn add eslint -D

2.配置 ESLint 执行 npx eslint --init，根据终端操作提示来创建配置文件。

  • How would you like to use ESLint?

16204529801434.jpg

  • What type of modules does your project use?

16204528765910.jpg

  • Which framework does your project use?

16204529221185.jpg

  • Does your project use TypeScript?

16204531409144.jpg

  • Where does your code run?

16204532262290.jpg

  • How would you like to define a style for your project?

16204533112733.jpg

  • Which style guide do you want to follow?

16204533840606.jpg

  • What format do you want your config file to be in?

16204534683666.jpg

  • Would you like to install them now with npm?

16204535434178.jpg

3.下载 TypeScript 上述操作选择了TypeScript作为模板，我们还需要加入TypeScript依赖

yarn add typescript -D

4.配置 .eslintrc.js 操作完成后会在项目根目录下自动生成 .eslintrc.js 配置文件，个人可根据项目需要配置：

module.exports = {
  env: {
    browser: true,
    es6: true,
  },
  extends: ['plugin:react/recommended', 'airbnb'],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 12,
    sourceType: 'module',
  },
  plugins: ['react', '@typescript-eslint'],
  rules: {
    'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
    'import/extensions': 'off',
    'import/no-unresolved': 'off',
    'react/jsx-filename-extension': 'off',
    'no-use-before-define': 'off',
    '@typescript-eslint/no-use-before-define': 'off',
  },
};

解决 Prettier 和 ESLint 的冲突， Prettier 配置规则 > ESLint 配置规则

ESLint 和 Prettier 可能存在规则冲突情况，解决两者冲突需要用到 eslint-plugin-prettier 和 eslint-config-prettier两个插件，这样，我们在执行 eslint --fix 命令时，ESLint 就会按照 Prettier 的配置规则来格式化代码，轻松解决二者冲突问题。

  • eslint-plugin-prettier 将 Prettier 的规则设置到 ESLint 的规则中。

  • eslint-config-prettier 关闭 ESLint 中与 Prettier 中会发生冲突的规则。

1.安装插件

eslint-plugin-prettier eslint-config-prettier -D

2.在 .eslintrc.js 添加 prettier 插件

module.exports = {
  ...
  extends: [
    "plugin:react/recommended",
    "airbnb",
    "plugin:prettier/recommended",
  ],
  ...
}

StyleLint 配置

StyleLint 是一个强大的、现代化CSS代码检测工具，通过一系列代码风格帮助我们避免样式错误。

1.安装 StyleLint 依赖
yarn add stylelint stylelint-config-standard stylelint-scss stylelint-order stylelint-config-recess-order -D

stylelint-scss

scss 拓展，增加支持 scss 语法

stylelint-config-standard

官方的代码风格 ：stylelint-config-standard。该风格是 Stylelint 的维护者汲取了 GitHub、Google、Airbnb 多家之长生成的。

stylelint-order

该插件的作用是强制你按照某个顺序编写 css。如：先写定位，再写盒模型，再写内容区样式，最后写 CSS3 相关属性。这样可以极大的保证我们代码的可读性，具体如下:

a. 定位属性：position display float left top right bottom overflow clear z-index

b. 自身属性：width height padding border margin background

c. 文字样式：font-family font-size font-style font-weight font-varient color

d. 文本属性：text-align vertical-align text-wrap text-transform text-indent text-decoration letter-spacing word-spacing white-space text-overflow

e. css3中新增属性：content box-shadow border-radius transform

stylelint-config-recess-order

stylelint-order 插件的第三方配置

2.配置StyleLint文件

在根目录创建 .stylelintrc.js 配置文件，内容如下：

module.exports = {
  extends: ['stylelint-config-standard', 'stylelint-config-recess-order'],
  plugins: ['stylelint-scss', 'stylelint-order'],
  ignoreFiles: ['**/*.js', '**/*.ts'],
  rules: {
    'at-rule-no-unknown': [true, { ignoreAtRules: ['mixin', 'extend', 'content', 'include'] }],
    'scss/at-rule-no-unknown': true,
  },
};

集成 husky 和 lint-staged

至此项目已经集成 ESLint 和 Prettier，但在编码过程中还是会有部分开发人员对上述规范视而不见，提交格式不规范的代码至远程仓库，所以我们还需要再加一点限制，从而让没通过检测、修复的代码禁止提交，保证仓库代码都是符合规范的。这就用到了 Git Hook, 通过对应hook来进一步约束规范，我们采用 husky 和 lint-staged 完成

1.配置 husky

使用 husky-init 命令可以快速初始化husky 配置（这里不再展开讲述husky-init 具体做了啥）。

npx husky-init && yarn

husky 包含了很多 hook（钩子），比较常用的有：pre-commit、commit-msg、pre-push。这里，我们使用 pre-commit 来触发 ESLint 命令。

2.配置 lint-staged

Lint-staged 可以让 husky 的 hook 触发的命令只作用于 git 暂存区的文件（即 git add 的文件），而不影响到其他文件。

1.安装

yarn add lint-staged -D

2.在 package.json 加入 lint-staged 配置项 （由于本项目采用TypeScript编码，且旨在打包 React 组件，所以会对JS、TS、JSX、TSX进行约束）

"lint-staged": {
    "**/*.{js,ts,jsx,tsx}": [
      "eslint --fix"
    ],
    "**/*.{css,scss}": [
      "stylelint --fix"
    ]
}

3.修改 .husky/pre-commit hook 的触发命令为：npx lint-staged

16205590507374.jpg

三、提交规范化

我们已经通过上述操作统一了代码规范，并且约束了代码提交来保证仓库质量，但在团队协作时还会存在部分开发者提交代码的时候，提交信息不够具体、紊乱、风格不一致的情况。规范 git commit 提交信息，会让后期维护和 Bug 处理变得有据可查，还可以根据规范的提交信息快速生成开发日志，从而方便我们追踪项目和把控进度。这里我们采取社区主流规范：Angular 团队提交规范。

1、commit message 规范

commit message 由 Header、Body、Footer 组成。

Header

Header 部分包括三个字段 type（必需）、scope（可选）和 subject（必需）。

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

type 表示 commit 的提交类型（必须是以下几种之一）。

scope

scope 表示本次 commit 影响的范围，实际可根据项目来定，比如：按功能模块划分、菜单划分，这里开发的是组件库，可根据组件划分

subject

subject 简要描述本次 commit 内容，长度约定在 50 个字符以内，通常遵循以下几个规范：

  • 动词开头，第一人称现在时表述
  • 第一个字母小写
  • 结尾不加句号（.）
Body

Body是对本次commit的详细描述，可以分为多行，应该说明本次修改原因以及更改前后的比对（可省略body）

Footer

当本次提交为BREAKING CHANGE的更新，或者解决了重大缺陷，footer为必须的，否则可以省略。

规范：

  • BREAKING CHANGE Footer 以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动的理由。

  • 关闭缺陷 如果当前提交是针对特定的 issue，那么可以在 Footer 部分填写需要关闭的单个 issue 或一系列 issues。

2、Commitizen 集成

上面已经介绍了提交规范，现在我们使用Commitizen 帮助我们自动生成符合规范的commit message

安装 Commitizen 
yarn add commitizen -D
cz-customizable 初始化

通过 cz-customizable 适配器来初始化项目

npx commitizen init cz-customizable -D -E

根目录下创建 .cz-config.js 文件，然后按照官方提供的示例来配置。

module.exports = {
  // type 类型（定义之后，可通过上下键选择）
  types: [
    { value: 'feat', name: 'feat: 新增功能' },
    { value: 'fix', name: 'fix: 修复 bug' },
    { value: 'docs', name: 'docs: 文档变更' },
    { value: 'style', name: 'style: 代码格式（不影响功能，例如空格、分号等格式修正）' },
    { value: 'refactor', name: 'refactor: 代码重构（不包括 bug 修复、功能新增）' },
    { value: 'perf', name: 'perf: 性能优化' },
    { value: 'test', name: 'test:  添加、修改测试用例' },
    { value: 'build', name: 'build: 构建流程、外部依赖变更（如升级 npm 包、修改 webpack 配置等）' },
    { value: 'ci', name: 'ci: 修改 CI 配置、脚本' },
    { value: 'chore', name: 'chore: 对构建过程或辅助工具和库的更改（不影响源文件、测试用例）' },
    { value: 'revert', name: 'revert: 回滚 commit' },
  ],

  // scope 类型（定义之后，可通过上下键选择）
  scopes: [
    ['components', '组件相关'],
    ['hooks', 'hooks 相关'],
    ['utils', 'utils 相关'],
    ['styles', '样式相关'],
    ['cli', '脚手架相关'],
    ['deps', '项目依赖'],
    ['other', '其他修改'],
    ['custom', '以上都不是？我要自定义'],
  ].map(([value, description]) => {
    return {
      value,
      name: `${value.padEnd(30)} (${description})`,
    };
  }),

  // 是否允许自定义填写 scope，在 scope 选择的时候，会有 empty 和 custom 可以选择。
  allowCustomScopes: false,

  // 交互提示信息
  messages: {
    Type: '确保本次提交遵循规范！\n选择你要提交的类型：',
    scope: '\n选择一个 scope（可选）：',
    // 选择 scope: custom 时会出下面的提示
    customScope: '请输入自定义的 scope：',
    Subject: '填写简短精炼的变更描述：\n',
    Body: '填写更加详细的变更描述（可选）。使用 "|" 换行：\n',
    Breaking: '列举非兼容性重大的变更（可选）：\n',
    footer: '列举出所有变更的 ISSUES CLOSED（可选）。 例如: #31, #34：\n',
    confirmCommit: '确认提交？',
  },

  // 设置只有 type 选择了 feat 或 fix，才询问 breaking message
  allowBreakingChanges: ['feat', 'fix'],

  // 跳过要询问的步骤
  skipQuestions: ['body', 'footer'],

  // subject 限制长度
  subjectLimit: 50,
  breaklineChar: '|', // 支持 body 和 footer
  // footerPrefix : 'ISSUES CLOSED:'
  // askForBreakingChangeFirst : true,
};

接下来我们提交代码git commit -m "xxx"就可以通过git cz完成，然后根据终端填入信息就能自动生成规范的 commit message。

carbon -1-.png

commitlint 验证提交规范

借助 @commitlint/config-conventional 和 @commitlint/cli 在提交代码这个环节增加限制

1、安装 @commitlint/config-conventional 和 @commitlint/cli

yarn add @commitlint/config-conventional @commitlint/cli -D

2、创建 commitlint.config.js 文件 在项目根目录下创建commitlint.config.js 文件，并填入以下内容：

module.exports = { extends: ['@commitlint/config-conventional'] }

3、通过husky的commit-msg触发验证 我们使用 husky 命令在 .husky 目录下创建 commit-msg 文件，并在此执行 commit message 的验证命令。

npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

Ending， 感谢阅读！

avatar
文章
阅读
粉丝