前端开发规范

2021-07-09 by uino 279 编码规范

NPM镜像

请先设置NPM的Registry为公司NPM镜像的地址https://npm.uino.cn

JavaScript 编码规范

  • UTF-8编码格式
  • 推荐使用ES6+TypeScript作为开发语言
  • 不要声明多余不使用的变量
  • 多用letconst,不用var
  • 使用单引号'而不要使用双引号"
  • 访问对象属性用obj.name,除非属性名不能通过点的方式来访问,如:obj['a-b hello']
  • 少用递归,因为递归过多会引起内存堆栈异常
  • 文件拆分要合理,不要把所有场景的业务逻辑都写在一个 js 文件里,打包时我们会合并
  • ifforwhile内不要再创建function
  • 驼峰命名变量名, 如 saveView
  • 常量大写下划线,如SAVE_VIEW
  • Class 需大写开头,如Person
  • 缩进推荐2空格,也可以4空格
  • 使用全等于===和全部不等于==!
  • 请使用localStorage,放弃Cookie
  • 推荐使用fetch或者框架自带 http 库,放弃XMLHttpRequest
  • 数组遍历使用for (let i=0, len=arr.length; i<len; i += 1)或者arr.forEach(),不要使用for...in
  • i++改成i += 1
  • 对象遍历使用Object.keys(obj)
  • 判断是不是数组用Array.isArray(something)
  • setInterval()必须有变量保存 ID,用于clearInterval(),不可泛滥使用
  • 异步编写可以多用awaitasync
  • 不要使用delete关键字删除某个字段,如:delete obj.name,而是:obj.name = null
  • 末尾分号推荐加,也可以不添加
  • ifforwhile即使只有一行代码也必须添加{}花括号
  • 从服务器端去数据必须有catch捕获错误,避免服务器端返回数据异常导致页面脚本报错
  • 打包时,必须把所有debugger关键字都删除
  • 尽量使用封闭或者单一入口变量,避免全局变量命名污染
  • 不能使用eval()函数
  • 使用JSON.stringify()必须用try...catch捕获异常
  • isPass = obj.age === 18 ? true : false 可以写成 isPass = obj.age === 18
  • 必须看!必须看!必须看! Airbnb JavaScript Style Guide
  • 代码风格检测工具 ESLint
  • 代码风格检测工具 JSLint

Prettier

Prettier 跟 ESLint 走不一样的路线,ESLint 是一个最低标准的检测工具,只要检测出不合格项就会提示,你还需要手动修复。Prettier 是一个自动格式化代码的工具

假如你已经写了很多代码,需要格式化之前的代码可以这么干

prettier --write "src/**/*.{js,ts,tsx,json,html}"

如果你使用的是 VSCode 编辑器,那么恭喜你,VSCode 非常容易支持 Prettier

  • 安装 Prettier 的扩展,搜索 Prettier 并安装
  • 再设置里添加"editor.formatOnSave": true即可

当然,Prettier 也可以跟很多 IDE 集成,请看这里Editor Integration

Prettier 官网

注释规范

注释我们以 JSDoc 规范为标准

目录规范

以下列出了一个项目下必须的目录结构,实际可能会更多,但不能比以下列出的更少

├── README.md # 此项目的详细阐述
├── dist  # 打包后临时存放目录
├── docs  # 文档
├── node_modules # npm包目录, GIT不要提交这个目录
├── package.json # 项目必须的文件,整体性描述项目信息以及依赖
├── src # 源码目录
├── .gitignore # Git忽略提交配置文件
├── .gitlab-ci.yml # CI配置文件
├── .editorconfig # 编辑器统一配置文件 详细请看 http://editorconfig.org
├── test # 自动化测试代码配置以及编码都放在这里

构建工具与包管理

我们强制规定使用 NodeJS 生态链 npm 来构建项目,项目根目录下必须要有package.json文件来定义项目描述与依赖

必须使用npm或者yarn做为包管理工具,所有的依赖必须保存在package.json文件内

公司搭建有 npmjs 私有镜像,提升依赖安装速度并在上面发布内部包,所以必须使用公司的私有镜像设置为 npm 的registry

package.json内必须定义几个固定的scripts

  • build 打包项目,打包完的代码写到根目录dist文件夹内
  • unit 运行单元测试
  • e2e 运行 e2e 测试
  • lint 代码格式检测
  • dev 启动开发

如果你是自行搭建项目,以下是参考

CSS 样式编写

  • UTF-8编码
  • 2空格缩进
  • 颜色统一用十六进制格式,带有 alpha 的颜色信息可以使用rgba()
  • z-index要合理定义,要分级
  • class名使用小写,采用-号分隔,如app-left
  • 能用class就不要用id
  • 尽量少用important
  • 少用empx,多用rem
  • 多用flex
  • 不要直接引入第三方在线资源,如字体、图片
  • 不要使用hack的写法,这些在打包的时候会自动添加前缀
  • 如果可以,必须使用 CSS 预处理器
    • Stylus 强烈推荐使用它,因为 Win 安装 Sass 总是失败
    • Sass

编辑器

  • Visual Studio Code 我们推荐使用微软的 Visual Studio Code
  • WebStorm 有点重,打开大文件会卡
  • vi 百分之九十九的高手都会这个编辑器

文档编写

我们推荐在 Gitlab 上使用 Markdown 格式编写 Wiki 文档

测试

单元测试

我们要求所有项目产品线的项目都要有搭建单元测试,所有开发人员都要编写前端的单元测试代码

推荐使用 Jest,当然每个项目不一样可以看实际情况配置

因为所有单元测试都会自动化执行,为了能准确抓到单元测试代码覆盖率,我们要求所有单元测试都必须要输出单元测试代码覆盖率,并且格式以text-summary(NodeJS)输出,如

=============================== Coverage summary ===============================
Statements   : 85.54% ( 633/740 )
Branches     : 64.99% ( 271/417 )
Functions    : 90.09% ( 100/111 )
Lines        : 85.93% ( 629/732 )
================================================================================

Jest 配置text-summary

请在执行 jest 命令后边加上--coverage参数

jest --coverage

并在配置文件,如jest.config.js里加上:

coverageReporters: ["text-summary"]

一个例子

module.exports = {
  roots: ["./test/unit"],
  globals: {
    "ts-jest": {
      useBabelrc: true
    }
  },

  collectCoverageFrom: ["**/dist/**/*.{js}", "!**/node_modules/**"],

  // preset: 'ts-jest',

  coverageReporters: ["text-summary"]
};

Karma 配置text-summary

coverageReporter: {
  reporters: [
    {
      type: 'text-summary'
    }
  ]
},

Mocha 配置text-summary

如果你用 Mocha,可以配置nyc输出测试报告

npm i nyc --save-dev
yarn add nyc -D

然后在执行 Mocha 测试命令时加入 nyc 命令

nyc --reporter=text-summary mocha

Badge

并要求在仓库下的 README.md 文件头添加代码覆盖率的 Badge 小图标

E2E 测试

我们要求所有项目产品线的项目都要有搭建 E2E 测试,所有开发人员都要编写测试代码

这里统一推荐使用 Nightwatch.js

国际化语言包维护平台

为了更好的支持国际化多语言,提供了一个国际化语言维护平台供国际化项目使用

权限说明:

  • 管理员: Git 平台管理员或者是 i18n 组成员,管理员可以增删改任何人的记录
  • 普通用户: 非管理员即是普通用户,普通用户只能新增,删改自己的记录

公共库

Docker

我们推荐所有服务都尽量容器化,公司内网搭建有集群用于跑 Docker 容器服务,并且有分布式存储支持容器持久化挂载

Docker 仓库

Docker使用Git账号登陆,不需要额外开通

Docker 镜像自动构建