一些前端常见规范

发表于 分类于 阅读次数： 本文字数： 1.4k 阅读时长 ≈ 5 分钟

最近花了丢丢时间稍微整理了下前端项目的规范，包括编码格式、提交规范等等，做了个小记录。

代码要求

  1. 使用 VSCode 编辑器请安装 vscode 插件 Prettier 和 ESLint。
  2. 请安装 Code Spell Checker 插件，避免错别字；error lens 插件将错误显示在当前行。
  3. commit 提交请遵守 commit 提交规则，提交类别具体请查看下方 Commitlint 模块

开发要求：

  • 代码中不需要 console.log() 输出
  • 节点尽量不使用内联样式，通过 class 设置样式，less 文件存在同级组件目录中
  • Js 尽量不进行 dom 操作，渲染和数据尽量分离
  • 不允许存在未引用的变量或函数
  • any 类型尽量不用
  • 涉及定量和类型定义可以考虑在同级目录中新建 const.ts 或 types.ts 文件管理
  • 业务组件请存在业务文件下，全局公共组件才允许放入 src/components 文件
  • 组件传入参数类型定义命名以组件名+Props 为准，如：MyComponentProps
  • 合理使用空格行和注释，增加代码可读性

文件名命名规范

  • 项目：全部小写字母命名，中划线分割，如 my-project
  • 目录：全部小驼峰命名，如 firstDir
  • 组件或组件文件：全部大驼峰命名，如 FirstComponent
  • 其他文件：全部小写，下划线连接，如 helper.js
  • class/id：全部小写，中划线连接
  • 常量：全部大写
  • 变量函数：小驼峰命名，且字母打头，如 myFunction
类型 常见分类
UpperCamelCase class / interface / type / enum / decorator / type parameters
lowerCamelCase variable / parameter / function / method / property / module alias
CONSTANT_CASE global constant values, including enum values.

Prettier

引入代码格式化工具 Prettier。它一般不会检查我们的代码质量，但是会对代码的结构风格进行统一管理，通常在执行保存操作的时候生效。能够清除原先代码的结构风格，并替换为项目团队统一制定的代码风格。

优点：

  1. 统一项目代码风格
  2. 减少开发者在代码整理上花费精力
  3. 清理并规范已有代码
  4. 减少潜在 bug 可能性

使用：
安装包：npm install prettier -D；安装 vscode 的 Prettier 插件

在项目根目录下的.Prettierrc 文件中添加 Prettier 应用规则，在.prettierignore 文件中添加 prettier 规则需要忽视的文件。

Prettier 规则具体：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "printWidth": 80,
  "singleQuote": true,
  "trailingComma": "all",
  "proseWrap": "never",
  "overrides": [
    {
      "files": ".prettierrc",
      "options": {
        "parser": "json"
      }
    }
  ],
  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-packagejson"]
}

更多可选配置点击查看

给项目添加 vscode 工作区配置，当然此设置也可以设置为你的 vscode 全局配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "eslint.enable": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.tslint": true,
    "source.fixAll.eslint": true
  },
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "vscode.json-language-features"
  },
  "cSpell.words": ["umijs"]
}

ESLint

ESLint 是一款优秀的代码检测工具，通过配置对应的规则能够实现对代码的格式以及代码质量进行检测，提高项目的质量。

代码检测都是通过 ESLint 包执行的，如果没有安装插件，则错误的信息需要在调用 eslint 检查命令后通过终端来查看；安装了插件，我们可以直接在 vscode 编辑器的代码对应部分看见红色波浪错误提示。

.eslintrc.js 文件

1
2
3
4
5
6
7
8
9
10
11
12
module.exports = {
  extends: require.resolve('@umijs/max/eslint'),
  rules: {
    // 有可能会触发自动fix强制加上deps，暂时屏蔽
    'react-hooks/exhaustive-deps': 'warn',

    // 允许 <a target="_blank"...
    'react/jsx-no-target-blank': 'off',

    'no-underscore-dangle': 'off',
  },
};

强烈推荐安装 ESLint 插件！

具体请前往根目录中的.eslintrc.js 文件进行配置。更多配置

Stylelint

利用 Stylelint 帮助规避 CSS 代码中的错误并保持一致的编码风格。

.stylelintrc.js 文件

1
2
3
module.exports = {
  extends: require.resolve('@umijs/max/stylelint'),
};

husky & lint-staged

husky 本质上是 Git 的钩子，支持 Git 操作进行到某一阶段时，执行开发者希望的操作。比如在提交 commit 前进行代码质量检测。Lint-staged 支持只对更改的文件进行操作，避免了对整个项目进行操作的巨大耗时。

  1. 安装 husky
    npm install husky --save-dev
  2. 启用 husky
    npx husky install 或者通过在 package.json 中添加 prepare script 实现自动启动npm set-script prepare "husky install"
  3. 添加 precommit hook
1
2
3
npx husky add .husky/pre-commit "npm run lint-staged"

git add .husky/pre-commit
  1. 设置 lint-staged 运行
    方式一：配置 json 文件
1
2
3
4
5
6
"lint-staged": {
    "{src,mock}/**/*.{ts,tsx,js,jsx}": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ]
  }

方式二：配置.lintstagedrc 文件(优先)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "*.{md,json}": [
    "prettier --cache --write"
  ],
  "*.{js,jsx}": [
    "max lint --fix --eslint-only",
    "prettier --cache --write"
  ],
  "*.{css,less}": [
    "max lint --fix --stylelint-only",
    "prettier --cache --write"
  ],
  "*.ts?(x)": [
    "max lint --fix --eslint-only",
    "prettier --cache --parser=typescript --write"
  ]
}

Commitlint

通过利用 Husky 的 Git 钩子能力，我们可以在代码的提交阶段对提交 commit 信息进行格式规定。

提交类别：

  • build：项目构建相关变更
  • ci：集成流程变更
  • docs: 文档更新
  • feat：新增功能
  • fix：bug 修复
  • perf：性能优化
  • refactor：代码重构，没新增功能也不是 bug 修复
  • style：代码风格调整
  • test：测试相关
  • revert：回滚
  • chore：不属于以上类型的其他类型提交

安装：npm install --save-dev @commitlint/config-conventional @commitlint/cli

添加 commitlint：npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

.commitlintrc.js 文件

1
2
3
module.exports = {
  extends: ['@commitlint/config-conventional'],
};

项目引用 commitlint 推荐的配置@commitlint/config-conventional。如需添加其他配置请遵守配置规范，如'type':[Level, Applicable, Value]

  • Level: 0-不启用规则、1-视为 warnning、2-视为 error。
  • Applicable：always 或者 never
  • Value：此规则适用的 value

更多配置可参考官网