多年总结的软性编码规范-前端

工程相关

常用工具

• JS 相关：eslint、prettier、@typescript-eslint/eslint-plugin
• Git 相关：lint-staged、husky、commitlint
• 其他：.npmrc、.yarnrc

文件名

• 常用文件名（也可用作文件夹名）
  index.js - 入口文件；
  constants.js - 常量；
  services.js - 网络请求；
  utils.js - 工具函数；
  routes.js - 路由；
  style.css - 样式；
• 只有 React 组件（实际上是 class 文件）以大驼峰命名，其他文件首字母都要小写（小驼峰或 - 连接）

// GOOD
import MyComponent from './MyComponent';

// BAD
import MyComponent from './myComponent';
import MyComponent from './my-component';

目录结构

.
├── config # 工程配置文件
│   └── webpack.config.js
├── public # 不需要编译的文件
│   ├── favicon.ico
│   ├── manifest.json
│   └── robots.txt
├── scripts # 工程脚本文件
│   ├── build.js
│   └── deploy.js
├── src
│   ├── assets # 静态文件
│   │   ├── iconfont
│   │   └── sprite.png
│   ├── components # 组件
│   │   ├── MyComponent1
│   │   │   ├── index.tsx
│   │   │   └── style.css
│   │   └── MyComponent2.tsx
│   ├── locales # 国际化
│   │   ├── en-US.json
│   │   └── zh-CN.json
│   ├── pages # 页面
│   │   └── Home
│   │       ├── components
│   │       ├── index.tsx
│   │       ├── services.ts
│   │       ├── style.css
│   │       └── utils.ts
│   ├── constants.ts
│   ├── index.tsx
│   ├── routes.ts
│   ├── style.css
│   └── utils.ts
├── .gitignore
├── .npmrc
├── .yarnrc
├── README.md
└── package.json

代码相关

变量命名

• 常量名全大写并用下划线连接多单词

// GOOD
const DEFAULT_PAGE_SIZE = 10;

// BAD
const defaultPageSize = 10;

• boolean 类型的变量名建议：isXXX、shouldXXX、canXXX、hasXXX、XXXable

// GOOD
const { isModalShow, shouldShowModal, canRun, hasReaded, closeable } = { true, false, true, false, false }

// BAD
const { showModal, modalClose } = { true, false }

函数命名

• 函数名统一用动词开头；

// GOOD
function showModal() {}
function changeStatus() {}

// BAD
function modalShow() {}
function statusChange() {}

• API 请求函数建议根据请求 Method 统一前缀，避免与外层函数混淆。另：get 请求建议用 fetch 做前缀，避免其他常用冲突

// GOOD
function submitForm() {
	postSubmitForm(values); // API 请求
}

function getUserInfo() {
	fetchUser(); // API 请求
}

// BAD
function submit() {
	submitForm(values); // API 请求
}
function getUserInfo() {
	getUser(); // API 请求
}

• 组件内声明的回调函数，推荐以 handleXXX 格式命名，而不是 onXXX。避免与 props 传入的回调函数混淆

// GOOD
function handleSubmit() {
	props.onSubmit();
}
<button onClick={handleSubmit}>Submit</button>

// BAD
function onSubmit() {
	props.onSubmit();
}
<button onClick={onSubmit}>Submit</button>

可读性

• 类型转换推荐用显示声明

// GOOD
Boolean(a); Number(b); String(c);

// BAD
!!a; +b; `${c}`; '' + c;

• 码表保证语义化

// GOOD
enum yesOrNo { no, yes } // ts
const status = { disabled: 0; active: 1; running: 2; }
if (status === status.active) // code

// BAD
if (status === 2) // code

性能

• switch 优于 if else；虽然 object 优于 switch，但要考虑代码可读性
• 删除不必要的 console，否则会造成内存泄漏
• 及时销毁监听事件，防止内存泄漏。比如在 componentWillUnmount 或 useEffect 的 return 中 removeEventListener（React）
• 首选 PureComponent，发现不能满足需求时再用别的（React 16.8-）
• 只有「传入组件的回调函数」需要用 useCallback 包裹，否则反而造成性能下降（React 16.8+）

业务相关

表单

• 输入项要有字符长度校验
• 明确是否需要 trim 操作
• textarea 输入的内容，展示时要保留格式，如缩进、换行等
• 提交操作要做频控，推荐用 loading 控制按钮的二次点击

API 格式

• ID 类，推荐用 string 类型，不推荐 number，超过 17 位的整数 js 会有精度丢失
• 时间类，推荐用毫秒时间戳，不推荐 string，避免时区造成的麻烦
• API URL 都以 /api/xxx 开头，其他地址留给前端页面，也方便批量代理
• Response 格式最外层要统一，方便前端封装；
• 列表类 API 统一基本 request 和 response 格式。例（可根据实际情况调整）：

// REQUEST
{
	"offset": 0, // 起始是 0
	"limit": 10,
}

// RESPONSE
{
	"code": 0, // 错误码，方便统一封装异常处理
	"data": { // 一定要是 object，不可以直接 array
		"list": [],
		"total": 100,
	},
	"message": "Success", // 后端控制的返回信息
}

其他

1. 缩进建议用 space 而不是 tab，避免不同解析器解析效果的差异
2. 缩进建议用 2 空格，一是代码显得更紧凑；二是当同时有「每行最大字数」限制时，auto format 之后的总行数会有较大差异，html、jsx 代码尤其明显
3. lint 规则理论上越严格越好。开始也许会觉得很痛苦，习惯之后，会养成非常良好的编码习惯。这点会贯穿你的整个职业生涯，是 ROI 特别高的一件事
4. 理解函数式编程的思想，并努力实践它。相信你的代码质量会上一个台阶