前端规范

🔵代码编辑器: 使用 vscode

编辑器使用vscode，代码的规范基本都要依赖于 vscode的插件

这里需要使用的插件有:

  • ESLint
  • koroFileHeader
  • Prettier - Code formatter

可选插件

  • Chinese (Simplified) Language Pack for Visual Studio Code (中文插件)
  • GitLens — Git supercharged
  • One Dark Pro
  • vscode-icons

🔵包管理器：使用 Yarn 替代NPM

yarn 优点:

1.缓存

Yarn 缓存了每个下载过的包，所以再次使用时无需重复下载。 同时利用并行下载以最大化资源利用率，因此安装速度更快。

2.安全性

在执行代码之前，Yarn 会通过算法校验每个安装包的完整性。

3.可靠性

使用详细、简洁的锁文件格式和明确的安装算法，Yarn 能够保证在不同系统上无差异的工作。

使用

中文文档: https://yarn.bootcss.com/docs/usage/

初始化一个新项目:

1
yarn init

添加依赖包

1
2
3
yarn add [package]
yarn add [package]@[version]
yarn add [package]@[tag]

将依赖项添加到不同依赖项类别中

1
2
3
yarn add [package] --dev
yarn add [package] --peer
yarn add [package] --optional

升级依赖包

1
2
3
yarn upgrade [package]
yarn upgrade [package]@[version]
yarn upgrade [package]@[tag]

移除依赖包

1
yarn remove [package]

安装项目的全部依赖

1
2
yarn
或者 yarn install

🔵静态代码分析工具：ESLint

ESLint 是在 ECMAScript/JavaScript 代码中识别和报告模式匹配的工具，它的目标是保证代码的一致性和避免错误。

在 TypeScript 中直使用 tslint 来对代码质量进行保障。但是 tslint 是 eslint 的子集。tslint 大概提供了 151 条基础规则，eslint 却有 249 条，更不用说 eslint 发达的生态了，提供了更多的规范代码。

例如：

ESLint 的标准里面禁止使用var ，需要使用let 或者 const 替代。

1.安装 Eslint:

1
yarn add eslint --dev

2.使用umi中的eslint 规则 umi-fabric:

文档: https://pro.ant.design/blog/use-eslint-typescript-cn

🌟🌟umi-fabric 🌟🌟, 这个库提供了 eslint ，stylelint 和 prettier 的一些预设。

安装 umi-fabric

1
yarn add @umijs/fabric --dev

并且在根目录 .eslintrc.js 中做如下配置

1
2
const fabric = require('@umijs/fabric');
module.exports = fabric.eslint;

在 vscode 中 eslint 的插件并不会默认的去 lint .ts 文件，我们需要在 settings.json 中设置

1
2
3
4
5
6
"eslint.validate": [
 "javascript",
 "javascriptreact",
 "typescript",
 "typescriptreact"
],

3.安装vscode 中的Eslint 插件

Eslint 扩展使用安装在打开的工作区文件夹中的ESLint库。写代码的时候可以静态检测代码。

eslint可以按照使用情况来自己定义哪些规则需要使用，哪些不需要使用。这里给出一个项目中的配置文件参考

.eslintrc.js 配置文件参考：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
module.exports = {
 extends: [require.resolve('@umijs/fabric/dist/eslint')],
 globals: {
  ANT_DESIGN_PRO_ONLY_DO_NOT_USE_IN_YOUR_PRODUCTION: true,
  page: true,
  REACT_APP_ENV: true,
 },
 rules: {
  'no-param-reassign': 0,
  'no-restricted-syntax': 0,
  'no-underscore-dangle': 0,
  'import/no-unresolved': 0,
  '@typescript-eslint/naming-convention': 0,
 },
};

🔵代码格式化工具：Prettier - Code formatter

Prettier 是一个“有主见”的代码格式化工具，支持列表如下： JavaScript，包括 ES2017 JSX Flow TypeScript CSS、LESS 和 SCSS

安装 Prettier 包

1
yarn add prettier --dev

安装vscode 中的Prettier 插件

使用方法:

快捷键 : shift + alt +F

或者 参考官方文档中 的方法:

1
2
3
4
\1. CMD + Shift + P -> Format Document
OR
\1. Select the text you want to Prettify
\2. CMD + Shift + P -> Format Selection

配置文件参考

这里同样也引入了umi中的规则 🌟🌟umi-fabric 🌟🌟

.prettierrc.js

1
2
3
4
const fabric = require('@umijs/fabric');
module.exports = {
 ...fabric.prettier,
};

🔵注释插件: koroFileHeader

不一定所有的函数都需要写注释，一般是比较关键的函数需要注释。文件头部的注释在安装插件后在创建的时候会默认加上。

1.文件头部添加注释:

  • 在文件开头添加注释，记录文件信息/文件的传参/出参等
  • 支持用户高度自定义注释选项, 适配各种需求和注释。
  • 保存文件的时候，自动更新最后的编辑时间和编辑人
  • 快捷键：window：ctrl+alt+i,mac：ctrl+cmd+i, linux: ctrl+meta+I

2.在光标处添加函数注释:

  • 在光标处自动生成一个注释模板, 自动解析函数参数，生成函数参数注释。
  • 支持用户高度自定义注释选项
  • 快捷键：window：ctrl+alt+t,mac：ctrl+cmd+t,linux: ctrl+meta+t
  • 快捷键不可用很可能是被占用了,参考这里

函数注释配置参考:

1
2
3
4
5
6
"fileheader.cursorMode": {
  // 函数注释
  "description": "",
  "param": "",
  "return": ""
 },

文件头部注释配置参考:

1
2
3
4
5
6
"fileheader.customMade": {
  // 头部注释
  "Author": "linkenzone", // 文件编辑者
  "Date": "Do not edit", // 文件创建时间
  "Descripttion": "Do not edit", // 文件描述
 },

🔵页面代码结构推荐

参考: https://beta-pro.ant.design/docs/folder-cn

为了让项目代码组织更加规范，让开发能够更方便的定位到相关页面组件代码，我们定义了一套规范，该规范当前只作为推荐的指导，并非强制。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
src
├── components
└── pages
    ├── Welcome        // 路由组件下不应该再包含其他路由组件，基于这个约定就能清楚的区分路由组件和非路由组件了
    |   ├── components // 对于复杂的页面可以再自己做更深层次的组织，但建议不要超过三层
    |   ├── Form.tsx
    |   ├── index.tsx  // 页面组件的代码
    |   └── index.less // 页面样式
    ├── Order          // 路由组件下不应该再包含其他路由组件，基于这个约定就能清楚的区分路由组件和非路由组件了
    |   ├── index.tsx
    |   └── index.less
    ├── user           // 一系列页面推荐通过小写的单一字母做 group 目录
    |   ├── components // group 下公用的组件集合
    |   ├── Login      // group 下的页面 Login
    |   ├── Register   // group 下的页面 Register
    |   └── util.ts    // 这里可以有一些共用方法之类，不做推荐和约束，看业务场景自行做组织
    └── *              // 其它页面组件代码

所有路由组件（会配置在路由配置中的组件）我们推荐以大驼峰命名打平到 pages 下面第一级（复杂的项目可以增加 group 层级，在 group 下放置 pages）。不建议在路由组件内部再嵌套路由组件 - 不方便分辨一个组件是否是路由组件，而且不方便快速从全局定位到路由组件。

我们推荐尽可能的拆分路由组件为更细粒度的组件，对于多个页面可能会用到的组件我们推荐放到 src/components 中，对于只是被单个页面依赖的（区块）组件，我们推荐就近维护到路由组件文件夹下即可。

🔵其他的规范参考

Isobar 前端代码规范 及 最佳实践:

http://coderlmn.github.io/code-standards/#_javascript_libraries

使用 stylelint 来约束样式文件

https://stylelint.io/

TypeScript 规范参考

https://beta-pro.ant.design/docs/type-script-cn

antd pro v5 参考

https://beta-pro.ant.design/

antd pro v4 参考

https://pro.ant.design/index-cn

…