前端规约

内含 HTML、CSS、JavaScript、TypeScript、React、Vue、Nodejs 编码规约和工程规约，包括 Git 规约、文档通用规约、更新日志规约、前后端协作规约、安全研发规约、云研发规约，以及配套工具及流程保障。

基本篇

JavaScript 规范

迭代器

请使用高阶函数替代迭代器，尽量保持原数组的不变性（无副作用）

[eslint: no-iterator no-restricted-syntax]

使用 map() / every() / filter() / find() / findIndex() / reduce() / some() / … 遍历数组

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const numbers = [1, 2, 3, 4, 5];

// ❌
let sum = 0
for (let num of numbers) {
    sum += num
}

// NOT BAD
let sum = 0
numbers.forEach(num => {
    sum += num
})

// ✅
const sum = numbers.reduce((total, num) => total + num, 0)

命名篇

变量命名

常规变量

常规变量：1 主体应该是名词，2 不应该携带类型，3 抽象而非具体，否则会导致“抽象泄露”，换言之修改变量类型，所有使用处均需改变。其他命名规则见下方：

规则一：变量主体应该是一个名词，故不应该动词开头

The first word of a variable name should be a noun or adjective (not a verb) to avoid confusion with functions。变量应该是名词或形容词，而非动词避免和函数命名冲突
eslint: variable-name-starts-with-non-verb

Bad
1
2
3
4
/** 目标链接 */
const goPage = 'https://yuque.antfin-inc.com/industryprod-hz/nopbol/sookzo';
const encodeDetailInfo = encodeURIComponent(jsonStringifySafely(detailInfo));
const parseDetailInfo = jsonParseSafely(detailInfo);

违反命名规范，应该是动词开头，doSth 是函数命名规则。

Good
1
2
3
4
/** 目标链接 */
const targetUrl ...;
const encodedDetailInfo ...;
const parsedDetailInfo ...;
规则二：命名不应该携带类型
Bad
1
2
3
interface IResultObj {
	success: boolean;
};
Good
1
2
3
interface IResult {
	success: boolean;
};

特殊模式变量

debounce / throttle timer

建议以 DebounceTimer 或 ThrottleTimer 结尾，和设计模式类名命名一样，一样能看出来其作用是防抖还是节流。

Bad
1
2
3
4
5
6
7
8
9
10
deriveDataFromProps(nextProps) {
  if (nextProps.update !== this.props.update || nextProps.configMode !== this.props.configMode) {
    // 接口刷新慢于update变更导致多次触发
    fetchLockTimer && clearTimeout(fetchLockTimer);

    fetchLockTimer = setTimeout(() => {
      this.initPage(nextProps);
    }, 200);
  }
},
Good

fetchLockTimer => initPageDebounceTimer

1
2
3
4
5
6
7
8
9
10
deriveDataFromProps(nextProps) {
  if (nextProps.update !== this.props.update || nextProps.configMode !== this.props.configMode) {
    // 接口刷新慢于update变更导致多次触发
    initPageDebounceTimer && clearTimeout(initPageDebounceTimer);

    initPageDebounceTimer = setTimeout(() => {
      this.initPage(nextProps);
    }, 200);
  }
},

复数命名

TODO: eslint rule enforce-postfix-to-plural-variables
集合（map、set、array 不包括字面量对象）变量命名规则：

  • 可数名词加 s，比如 cards items
  • 不可数名词加 List，比如 extra => extraList
  • 二维数组怎么命名：可数名词 contactsList 不可数名词 extraLists
Bad
1
const imagelist = ...;
Good
1
const images = ...;
Bad
1
2
3
4
const ActivityStatusEnumArr = [
  'ON',
  'OFF',
 ]

该命名的问题：从后缀 Arr 就定死了底层的数据结构一定是数组（抽象泄露），不具备扩展性。

Good
1
2
3
4
5
6
7
8
9
10
const activityStatusList = [
  'ON',
  'OFF',
]

// 或
enum ActivityStatusEnum {
  'ON',
  'OFF',
}