从 0 到 1 搭建一个企业级前端开发规范

发表于 3年以前  | 总阅读数:343 次

前端代码规范对于团队而言至关重要,既可以提高代码的可维护性,也可以降低代码多人维护的成本

那如何搭建一个规范的前端项目基础呢?接下来让我告诉你

创建一个基础项目

使用 npm init \-y 初始化一个前端项目,这会自动生成package.json 文件。当我们安装项目依赖的时候,这个文件会自动更新

接下来我们创建以下文件目录

└── src/
    ├── index.ts    // 项目入口文件
├── package.json

添加 TypeScript

我们为什么需要 TypeScript 呢?

  • TypeScript 会在编译代码时,进行严格的静态类型检查。意味着可以在编码阶段发现存在的隐患,而不用把隐患带到线上去
  • TypeScript 会包括来自 ES6 和未来提案中的特性,比如异步操作和装饰器,也会从其他语言借鉴特性,比如接口和抽象类
  • TypeScript 编译成 JavaScript 后,可以在任何浏览器/操作系统上运行。无需任何运行时的额外开销
  • TypeScript 接口定义后,可以充分利用 VSCode 的自动补全/自动提示功能.因此可以直接代替文档,同时可以提高开发效率,降低维护成本

接下来我们在 CLI 中安装 TypeScript

yarn add typescript   --dev

然后进行 TypeScript 配置!在项目根目录通过tsc \--init命令来创建 tsconfig.json 文件并替换为以下内容

有关 TypeScript 的详细配置可以查看这篇文章

{
  "compilerOptions": {
    "module": "esnext",
    "target": "esnext",
    "lib": ["esnext", "dom"],
    "baseUrl": ".",
    "jsx": "react-jsx",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "node",
    "forceConsistentCasingInFileNames": true,
    "noImplicitReturns": true,
    "suppressImplicitAnyIndexErrors": true,
    "noUnusedLocals": true,
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "strict": true,
    "paths": {
      "@/*": ["./src/*"]
    },
    "noEmit": true
  },
  "include": [
    "src/**/*",
    "typings/**/*",
    "config/**/*",
    ".eslintrc.js",
    ".stylelintrc.js",
    ".prettierrc.js"
  ],
  "exclude": ["node_modules", "build", "dist"]
}

在我们的React Build项目中, 使用 Webpack 的 Babel 对项目代码进行编译,因此使用 TypeScript 的唯一目的仅仅是对项目代码进行类型检查。

因为 tsconfig.json 中的编译选项仅仅针对代码类型检查,而不是代码编译,因此不需要让 TypeScript 生成编译文件

以下是tsconfig.json中一些设置的解释

  • lib: TS 需要引用的库,即声明文件,ES5 默认 dom,es5,scripthost
  • allowJs: 允许编译 JS 文件(js,jsx)
  • allowSyntheticDefaultImports: 允许从没有设置默认导出的模块中默认导入. 参考文档
  • esModuleInterop: 参考文档
  • skipLibCheck:忽略所有的声明文件( *.d.ts)的类型检查
  • strict:开启所有严格的类型检查.如果 strict=true,则 所有 strict 相关的配置都应该为 true
  • forceConsistentCasingInFileNames:禁止对同一个文件的不一致的引用.例如:引用文件时大小写必须一致
  • moduleResolution:使用哪种模块解析策略.参考文档
  • resolveJsonModule:是否可以导入 JSON 模块.参考文档
  • isolatedModules:每个文件必须是模块.参考文档
  • noEmit:不生成输出文件
  • jsx: 支持 JSX.参考文档
  • include:编译器需要编译的文件或者目录

添加 ESLint 代码规范校验

ESLint 可以帮助我们找出有问题的编码模式或不符合规则的代码

有关 ESLint 的详细讨论可以查看这篇文章

OK!让我们开始安装 ESLint 的相关依赖

yarn add eslint eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/parser @typescript-eslint/eslint-plugin --dev

以下是一些 ESLint 依赖的解释

  • eslint: ESLint 核心库

  • eslint-plugin-react: React 代码规范的校验规则

  • react/jsx-key:用来检查是否声明了 key 属性

  • no-array-index-key:用来检查是否使用了数组索引声明 key 属性

  • ....其他 React 相关规范

  • eslint-plugin-react-hooks:React hooks 代码规范的校验规则

  • rules-of-hooks: 用来检查 Hook 的规则(不能 if/循环中使用 Hooks)

  • exhaustive-deps 规则,此规则会在useEffct添加错误依赖时发出警告并给出修复建议

  • @typescript-eslint/parser:将 TypeScript 代码纳入 ESLint 校验范围

  • @typescript-eslint/eslint-plugin:TypeScript 代码规范的校验规则

在根目录创建.eslintrc.json文件并加入以下内容

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2018,
    "sourceType": "module"
  },
  "plugins": ["@typescript-eslint", "react-hooks"],
  "extends": [
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
    "react/prop-types": "off",
    "@typescript-eslint/explicit-module-boundary-types": "off"
  }
}

我们在 ESLint 配置文件中做了下面的事情

  • @typescript-eslint/parser 作为ESLint 解析器
  • 使用plugin:react/recommended/plugin:@typescript-eslint/recommended作为基本规则集
  • 添加了两个 React Hooks 规则,并取消了 react/prop-types 规则,因为 prop 类型与 React 和 TypeScript 项目无关。
  • 关闭了explicit-module-boundary-types,Typescript 中,必须明确指定函数的返回值类型。并且函数中的return后的类型必须与指定的类型一致 参考文档

下面是一个 "explicit-module-boundary-types" 规则的栗子

// 会出现 explicit-module-boundary-types警告
export default function () {
  return 1;
}

// 下面的函数不会出现警告
export var fn = function (): number {
  return 1;
};

TS 中可以通过类型推断判断出函数的返回值类型,因此可以关闭此 Lint

添加 NPM 脚本

{
  "script": {
    "lint-staged:js": "eslint --ext .js,.jsx,.ts,.tsx ",
    "lint:js": "eslint --cache --ext .js,.jsx,.ts,.tsx ./src",
    "lint:fix": "eslint --fix --cache --ext .js,.jsx,.ts,.tsx"
  }
}
  • lint-staged:js: 只校验后缀名为".js,.jsx,.ts,.tsx"的文件
  • lint:js: 只校验src目录下,后缀名为".js,.jsx,.ts,.tsx"的文件中,被修改过的文件。这会生成一个.eslintcache文件用来缓存已校验过的文件
  • lint:fix: 根据 .eslintcache文件,校验被修改过的文件。并且自动修复

如果需要屏蔽不需要检测的文件或目录,可以在项目根目录添加 .eslintignore

.DS_Store
node_modules
dist
build
public

添加 Prettier 代码自动格式化工具

Prettier 是一个代码格式化的工具.某些与代码校验有关的规则(例如,语句末尾是否加分号)就可以由 Prettier 自动处理。

有关 Prettier 的详细讨论可以查看这篇文章

接下来我们在 CLI 中安装 Prettier

yarn add prettier  --dev

在项目根目录新建.prettierrc 并加入以下内容

{
  "printWidth": 80,
  "singleQuote": true,
  "semi": true,
  "tabWidth": 2,
  "trailingComma": "all"
}

VSCode 安装 Prettier 插件

通过在“设置”中勾选“保存时进行格式化”选项, 就可以在文件保存时使用 Prettier 进行自动格式化

如果需要屏蔽不必要的文件,可以在项目根目录添加 .prettierignore并加入以下内容

*.svg
package.json
.DS_Store
.eslintignore
*.png
*.toml
.editorconfig
.gitignore
.prettierignore
LICENSE
.eslintcache
*.lock
yarn-error.log
/build
/public

添加 npm 脚本

"script":{
  "lint:prettier": "prettier --check \"src/**/*\" --end-of-line auto",
  "prettier": "prettier -c --write \"src/**/*\""
}

解释一下脚本的含义

  • lint:prettier:当想要检查文件是否已被格式化时,则可以使用--check标志(或-c)运行 Prettier。这将输出一条语义化的消息和未格式化文件的列表。上面脚本的意思是格式化src目录下的所有文件
  • prettier:重新格式化所有已被处理过的文件。类似于eslint --fix的工作。上面脚本的意思是重新格式化src目录下的所有文件

添加 EditorConfig 代码风格统一工具

EditorConfig 有助于维护跨多个编辑器和 IDE 从事同一项目的多个开发人员的一致编码风格,团队必备神器。

有关 EditorConfig 的详细讨论可以查看这篇文章

VSCode 安装 EditorConfig 插件

在项目根目录创建.editorconfig并加入以下内容

# http://editorconfig.org
root = true

[*]
#缩进风格:空格
indent_style = space
#缩进大小2
indent_size = 2
#换行符lf
end_of_line = lf
#字符集utf-8
charset = utf-8
#是否删除行尾的空格
trim_trailing_whitespace = true
#是否在文件的最后插入一个空行
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

添加 stylelint

[stylelint][https://stylelint.io/user-guide/get-started]是一个 css 规范校验工具,也支持 less 等 css 预处理器

有关 stylelint 的详细讨论可以查看这篇文章

VSCode 安装 stylelint 插件

stylelint

安装依赖

yarn add stylelint stylelint-config-standard --dev

新建 .stylelintrc.js并加入以下内容

module.exports = {
  extends: "stylelint-config-standard",
  rules: {
    // your rules
  },
  // 忽略其他文件,只校验样式相关的文件
  ignoreFiles: [
    "node_modules/**/*",
    "public/**/*",
    "dist/**/*",
    "**/*.js",
    "**/*.jsx",
    "**/*.tsx",
    "**/*.ts",
  ],
};

配置 NPM 脚本

"script":{
 "lint:style": "stylelint --fix \"src/**/*.less\" --syntax less",
}

解释一下脚本的含义: 自动修复src 目录下的所有 less 文件不规范的内容

ESLint/Prettier/stylelint 工具库推荐

推荐一个集成了 ESLint/Prettier/stylelint 的开源库 umijs/fabric. 它把所有的常见规范都集成在了一起,而不需要开发者再去单独维护。引用该库的方式也很简单

让我们安装该依赖

yarn add @umijs/fabric --dev

修改 ESLint/Prettier/stylelint 几个文件的配置

// .prettierrc.js
const fabric = require("@umijs/fabric");

module.exports = {
  ...fabric.prettier,
};
// .stylelintrc.js
const fabric = require("@umijs/fabric");

module.exports = {
  ...fabric.stylelint,
};
// .eslintrc.js
module.exports = {
  extends: [require.resolve("@umijs/fabric/dist/eslint")],
  globals: {
    // 全局变量:在全局中使用 REACT_APP_ENV时  eslint就不会出现警告
    REACT_APP_ENV: true,
  },
};

注: 安装了@umijs/fabric就不能再安装其他 ESLint 解析器如@typescript-eslint/parser,否则会产生冲突


添加 Git Hook

只是单纯引入代码规范校验如果不强制执行就等于没做,总会有人偷懒,所以还可以加一道门槛进行约束。

我们可以通过 lint-staged 实现这道门槛:在 git commit 命令运行时先校验 lint(eslint, stylelint 等)是否通过,未通过则不予提交

  • husky 是一个 gitHook 工具,可以配置 git 的一些钩子,本文主要用来配置 commit 钩子
  • lint-staged 是一个在 git 暂存文件上运行 lint 校验的工具,配合 husky 配置 commit 钩子,用于 git commit 前的强制校验

有关 Git Hook 的讨论可以参考这篇文章

安装依赖

yarn add husky lint-staged --dev
{
  "scripts": {
    "precommit": "lint-staged",
    "lint-staged:js": "eslint --ext .js,.jsx,.ts,.tsx"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "**/*.less": "stylelint --syntax less",
    "**/*.{js,jsx,ts,tsx}": "npm run lint-staged:js",
    "**/*.{js,jsx,tsx,ts,less,md,json}": ["prettier --write"]
  }
}

在每次 git commit 之前会进入工作区文件扫描,自动修复 eslint/stylelint 问题再使用 prettier 自动格式化,最后再提交到工作区。

注:

必选先使用git init 初始化 git 仓库,之后使用 husky 才能生效

如果预提交钩子不生效可以参考stackoverflow:lint-staged not running on precommit

Commit Message 规范

大量的代码提交,必然会产生大量的 Commit log. 每一条都 Commit log 记录着某一阶段所完成的事以及关注点,应该尽可能详细具体;在工作中一份清晰规范的 Commit Message 能让后续代码审查、信息查找、版本回退都更加高效可靠。

Commit message 格式

<type>: <subject> 注意冒号后面有空格。

type

用于说明 commit 的类别,只允许使用下面 7 个标识。

  • feat:新功能(feature)
  • fix:修补 bug
  • docs:文档(documentation)
  • style:格式(不影响代码运行的变动)
  • refactor:重构(即不是新增功能,也不是修改 bug 的代码变动)
  • test:增加测试
  • chore:构建过程或辅助工具的变动

如果 type 为 feat 和 fix,则该 commit 将肯定出现在 Change log 之中。

subject

subject 是 commit 目的的简短描述,不超过 50 个字符,且结尾不加句号(.)。

栗子

git commit -m 'feat:添加了一个用户列表页面'

git commit -m 'fix:修复用户列表页面无法显示的bug'

git commit -m 'refactor:用户列表页面代码重构'

这里多一嘴: 网上有许多教程通过commitizen 实现强制的 Commit Message 格式规范,我是不赞同的。规范应该是每个开发者自发遵循的,如果规范过多记不住,可以通过 ESLint 等强制执行养成习惯。但对于这种简单的规范我们应该自发遵守,更何况还有规范校验的最后一道门槛-团队代码审查(轻则被团队大佬喷的体无完肤,重则卷铺盖走人 )

本文由哈喽比特于3年以前收录,如有侵权请联系我们。
文章来源:https://mp.weixin.qq.com/s/0-mfeSv-JVeQM_CAXeiLMQ

 相关推荐

刘强东夫妇:“移民美国”传言被驳斥

京东创始人刘强东和其妻子章泽天最近成为了互联网舆论关注的焦点。有关他们“移民美国”和在美国购买豪宅的传言在互联网上广泛传播。然而,京东官方通过微博发言人发布的消息澄清了这些传言,称这些言论纯属虚假信息和蓄意捏造。

发布于:6月以前  |  808次阅读  |  详细内容 »

博主曝三大运营商,将集体采购百万台华为Mate60系列

日前,据博主“@超能数码君老周”爆料,国内三大运营商中国移动、中国电信和中国联通预计将集体采购百万台规模的华为Mate60系列手机。

发布于:6月以前  |  770次阅读  |  详细内容 »

ASML CEO警告:出口管制不是可行做法,不要“逼迫中国大陆创新”

据报道,荷兰半导体设备公司ASML正看到美国对华遏制政策的负面影响。阿斯麦(ASML)CEO彼得·温宁克在一档电视节目中分享了他对中国大陆问题以及该公司面临的出口管制和保护主义的看法。彼得曾在多个场合表达了他对出口管制以及中荷经济关系的担忧。

发布于:6月以前  |  756次阅读  |  详细内容 »

抖音中长视频App青桃更名抖音精选,字节再发力对抗B站

今年早些时候,抖音悄然上线了一款名为“青桃”的 App,Slogan 为“看见你的热爱”,根据应用介绍可知,“青桃”是一个属于年轻人的兴趣知识视频平台,由抖音官方出品的中长视频关联版本,整体风格有些类似B站。

发布于:6月以前  |  648次阅读  |  详细内容 »

威马CDO:中国每百户家庭仅17户有车

日前,威马汽车首席数据官梅松林转发了一份“世界各国地区拥车率排行榜”,同时,他发文表示:中国汽车普及率低于非洲国家尼日利亚,每百户家庭仅17户有车。意大利世界排名第一,每十户中九户有车。

发布于:6月以前  |  589次阅读  |  详细内容 »

研究发现维生素 C 等抗氧化剂会刺激癌症生长和转移

近日,一项新的研究发现,维生素 C 和 E 等抗氧化剂会激活一种机制,刺激癌症肿瘤中新血管的生长,帮助它们生长和扩散。

发布于:6月以前  |  449次阅读  |  详细内容 »

苹果据称正引入3D打印技术,用以生产智能手表的钢质底盘

据媒体援引消息人士报道,苹果公司正在测试使用3D打印技术来生产其智能手表的钢质底盘。消息传出后,3D系统一度大涨超10%,不过截至周三收盘,该股涨幅回落至2%以内。

发布于:7月以前  |  446次阅读  |  详细内容 »

千万级抖音网红秀才账号被封禁

9月2日,坐拥千万粉丝的网红主播“秀才”账号被封禁,在社交媒体平台上引发热议。平台相关负责人表示,“秀才”账号违反平台相关规定,已封禁。据知情人士透露,秀才近期被举报存在违法行为,这可能是他被封禁的部分原因。据悉,“秀才”年龄39岁,是安徽省亳州市蒙城县人,抖音网红,粉丝数量超1200万。他曾被称为“中老年...

发布于:6月以前  |  445次阅读  |  详细内容 »

亚马逊股东起诉公司和贝索斯,称其在购买卫星发射服务时忽视了 SpaceX

9月3日消息,亚马逊的一些股东,包括持有该公司股票的一家养老基金,日前对亚马逊、其创始人贝索斯和其董事会提起诉讼,指控他们在为 Project Kuiper 卫星星座项目购买发射服务时“违反了信义义务”。

发布于:6月以前  |  444次阅读  |  详细内容 »

苹果上线AppsbyApple网站,以推广自家应用程序

据消息,为推广自家应用,苹果现推出了一个名为“Apps by Apple”的网站,展示了苹果为旗下产品(如 iPhone、iPad、Apple Watch、Mac 和 Apple TV)开发的各种应用程序。

发布于:6月以前  |  442次阅读  |  详细内容 »

特斯拉美国降价引发投资者不满:“这是短期麻醉剂”

特斯拉本周在美国大幅下调Model S和X售价,引发了该公司一些最坚定支持者的不满。知名特斯拉多头、未来基金(Future Fund)管理合伙人加里·布莱克发帖称,降价是一种“短期麻醉剂”,会让潜在客户等待进一步降价。

发布于:6月以前  |  441次阅读  |  详细内容 »

光刻机巨头阿斯麦:拿到许可,继续对华出口

据外媒9月2日报道,荷兰半导体设备制造商阿斯麦称,尽管荷兰政府颁布的半导体设备出口管制新规9月正式生效,但该公司已获得在2023年底以前向中国运送受限制芯片制造机器的许可。

发布于:6月以前  |  437次阅读  |  详细内容 »

马斯克与库克首次隔空合作:为苹果提供卫星服务

近日,根据美国证券交易委员会的文件显示,苹果卫星服务提供商 Globalstar 近期向马斯克旗下的 SpaceX 支付 6400 万美元(约 4.65 亿元人民币)。用于在 2023-2025 年期间,发射卫星,进一步扩展苹果 iPhone 系列的 SOS 卫星服务。

发布于:6月以前  |  430次阅读  |  详细内容 »

𝕏(推特)调整隐私政策,可拿用户发布的信息训练 AI 模型

据报道,马斯克旗下社交平台𝕏(推特)日前调整了隐私政策,允许 𝕏 使用用户发布的信息来训练其人工智能(AI)模型。新的隐私政策将于 9 月 29 日生效。新政策规定,𝕏可能会使用所收集到的平台信息和公开可用的信息,来帮助训练 𝕏 的机器学习或人工智能模型。

发布于:6月以前  |  428次阅读  |  详细内容 »

荣耀CEO谈华为手机回归:替老同事们高兴,对行业也是好事

9月2日,荣耀CEO赵明在采访中谈及华为手机回归时表示,替老同事们高兴,觉得手机行业,由于华为的回归,让竞争充满了更多的可能性和更多的魅力,对行业来说也是件好事。

发布于:6月以前  |  423次阅读  |  详细内容 »

AI操控无人机能力超越人类冠军

《自然》30日发表的一篇论文报道了一个名为Swift的人工智能(AI)系统,该系统驾驶无人机的能力可在真实世界中一对一冠军赛里战胜人类对手。

发布于:7月以前  |  423次阅读  |  详细内容 »

AI生成的蘑菇科普书存在可致命错误

近日,非营利组织纽约真菌学会(NYMS)发出警告,表示亚马逊为代表的电商平台上,充斥着各种AI生成的蘑菇觅食科普书籍,其中存在诸多错误。

发布于:7月以前  |  420次阅读  |  详细内容 »

社交媒体平台𝕏计划收集用户生物识别数据与工作教育经历

社交媒体平台𝕏(原推特)新隐私政策提到:“在您同意的情况下,我们可能出于安全、安保和身份识别目的收集和使用您的生物识别信息。”

发布于:7月以前  |  411次阅读  |  详细内容 »

国产扫地机器人热销欧洲,国产割草机器人抢占欧洲草坪

2023年德国柏林消费电子展上,各大企业都带来了最新的理念和产品,而高端化、本土化的中国产品正在不断吸引欧洲等国际市场的目光。

发布于:6月以前  |  406次阅读  |  详细内容 »

罗永浩吐槽iPhone15和14不会有区别,除了序列号变了

罗永浩日前在直播中吐槽苹果即将推出的 iPhone 新品,具体内容为:“以我对我‘子公司’的了解,我认为 iPhone 15 跟 iPhone 14 不会有什么区别的,除了序(列)号变了,这个‘不要脸’的东西,这个‘臭厨子’。

发布于:6月以前  |  398次阅读  |  详细内容 »
 相关文章
Android插件化方案 5年以前  |  236812次阅读
vscode超好用的代码书签插件Bookmarks 1年以前  |  6665次阅读
 目录