前端项目规范基础

马小飞
400 阅读8分钟

主要针对市面上比较流行的几种项目规范/约束（规范即约束），集成到项目中去

本篇文章只阐述 基本用法，在基本用法之外，更精细颗粒度的控制和拓展，可参考对应技术官网做更多配置

文章技术关键词：prettier、Eslint、Husky、link-staged、git提交规范、文件注释、自定义规范

集成Demo源码: github.com/mapengfei47…

DSC05091.JPG

1. Prettier

一句话介绍：one team one style. At least one project one style

定义

Prettier官网：What is Prettier? 

It removes all original styling *****  and ensures that all outputted code conforms to a consistent style. 

简单说就是，按照一定的配置规范，格式化输出我们的所有代码，使整体项目保持格式一致

配置

安装： 项目根目录执行 npm i prettier -D 命令

配置

即格式化规范，一般包含两个文件 .prettierrc.json 和 .prettierignore，分别进行格式规范的配置和指定需要忽略的文件配置，可参考 Prettier官网：Options，也可以通过 Prettier官网：图形化配置页面 进行配置演示，配置OK之后直接拷贝配置粘贴到项目的 .prettierrc.json 即可

.prettierrc.json

{
	"trailingComma": "es5",
	"tabWidth": 4,
	"semi": false,
	"singleQuote": true,
	"end_of_line": "lf",
	"insert_final_newline": true,
	"max_line_length": 80
}

.prettierignore

# Ignore artifacts:
build
publiv
node_modules
coverage

# Ignore all HTML files:
**/*.html

应用

Vscode保存自动格式化

安装插件：Prettier - Code formatter

开启保存自动格式化

git-commit提交自动格式化

git commit 自动格式化，需要借助 husky（commit 钩子工具），在执行 commit 之前执行一系列命令

安装

有两种安装方式，手动逐步安装 和 一键安装

  • 手动逐步安装
npm i husky lint-staged -D
husky install
npx husky add .husky/pre-commit "npx lint-staged"

配置

"lint-staged": {
    "**/*": "prettier --write --ignore-unknown"
}

最后执行 git commit -m 'xxx' 匹配到的文件即会自动格式化

  • 一键安装
npx husky-init && npm install

该命令做了如下几件事情

    • 安装 husky，即执行了 npm i husky -D
    • 在 package.json 的 scripts下增加了 prepare: "husky install" 命令
    • 在项目根目录创建了 .husky 文件夹，生成了默认的 pre-commit 配置

2. Husky & lint-staged 

一句话介绍：将规范/约束交给工具去执行

定义

Husky： 提供一系列的 git 钩子函数 Husky官网

我们来看看官网怎么说

Ultra-fast modern native git hooks

Husky enhances your commits and more 🐶 woof!

Automatically lint your commit messages, code, and run tests upon committing or pushing.

lint-staged： 配合 husky 在钩子函数执行之前，按照一定的条件筛选出对应的文件类型进行执行，搭配 linters 使用，比如 Eslint、Prettier等  Github: lint-staged

看看官网怎么说

Run linters against staged git files and don't let 💩 slip into your code base!

husky 和 lint-staged 一般是配合一起使用的，husky 负责触发 git 生命周期钩子，lint-staged 负责匹配对应的内容然后执行相关的命令

两者搭配可在代码提交之前，铸起一道规范的城墙，保障提交到远程的代码风格都是一致的

配置

详细配置参考 Husky官网 、Github: lint-staged

以下是基础配置

  1. 安装
npx husky-init && npm install
npm i lint-stated prettier -D

2. 配置

.husky/pre-commit

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm lint-staged

package.json

"lint-staged": {
		"*": "your command",
	  "*.{js,jsx,ts,tsx,html,css,vue}": "prettier --write"
}

prettier配置见文档上方 Prettier 部分

此时执行 git commit 即可对匹配到的所有文件执行 prettier 配置对应的格式化

应用

Github: lint-staged#Example

3. Eslint 配置

一句话介绍：在开发和提交阶段做代码约束，开发阶段通过 warning 或 error 提示，git commit 阶段限制提交

定义

Eslint: eslint 是一个代码约束工具，在代码运行和提交之时，提供一定的检测和提示

看看官网怎么说

ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. In many ways, it is similar to JSLint and JSHint with a few exceptions:

  • ESLint uses Espree for JavaScript parsing.
  • ESLint uses an AST to evaluate patterns in code.
  • ESLint is completely pluggable, every single rule is a plugin and you can add more at runtime.

配置

  1. 安装初始化（执行命令后会有一系列交互式答问配置，按照需求选择即可）
npm init @eslint/config@latest

初始化完成之后，会在项目根目录生成 eslint.config.js 配置文件

  1. 配置 eslint.config.jsEslint官网配置
export default [
	{
		files: ['**/*.{js,mjs,cjs,ts,vue}'],
		rules: {
			'no-unused-vars': 'error',
			'no-console': 'error',
		},
	},
]

3. 手动执行检测 npx eslint ./src/xxx.vue

应用

git-commit 提交检测

执行 git commit 提交的时候，如果 eslint 检测不通过，则会提交失败，需修改代码之后重新提交

"lint-staged": {
	"*.{js,jsx,ts,tsx}": [
		"npx eslint src --fix",
		"prettier --write"
	],
	"*.json": [
		"prettier --write"
	],
	"*.vue": [
		"npx eslint --ext src --fix",
		"prettier --write"
	],
	"*.{scss,less,html}": [
		"prettier --write"
	],
	"*.md": [
		"prettier --write"
	]
}

报错示例

开发环境集成检测

安装：npm i eslint-plugin-vue @antfu/eslint-config -D

配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import eslintPlugin from 'vite-plugin-eslint'

// https://vitejs.dev/config/
export default defineConfig({
	plugins: [
		vue(),
		eslintPlugin({ include: ['src/**/*.vue', 'src/**/*.ts'] }),
	],
})

启动项目即可看到对应的报错提示

4. git提交规范

一句话介绍：我希望当我回忆我的过去的时候，它能看起来跟我的未来一样清晰且有方向感

定义：什么是合适的 git 提交规范

当不知道规范的时候，看看最热门的项目是怎么做的准没错

话不多说，接下来看下 Vuejs 的提交格式是什么样的

整合了一下信息，大概结构如下

<type>(<scope>): <subject>
空行
<body>
空行
<footer>

# 看不懂没关系，伪代码如下

提交类型（影响范围）：简短描述
空行
详细描述（非必填）
空行
关联的issue，PR，需求或bug来源等

即最终结构如下

  • type： 提交类型
    • feat： 新功能
    • fix： 修复bug
    • docs： 文档变更
    • style： 代码格式(不影响代码运行的变动，如格式化)
    • refactor： 代码重构(既不是新功能也不是修bug)
    • test： 增加或修改测试
    • chore： 构建过程或辅助工具的变动
  • scope(可选)： 影响范围
    • 指此次改动的影响范围，比如文件名、模块等
  • subject： 简短描述
  • body： 详细描述
  • footer： 一些元数据，比如关联的 issue、PR 等

配置

需要配合 husky 一起使用，可参考上方 husky 部分配置

  1. 增加 husky 的commit-msg 配置,并修改默认命令

hooks初始化

npx husky add .husky/commit-msg ""

hooks配置

npx --no -- commitlint --edit ${1}

2. 安装 @commitlint/cli、@commitlint/config-conventional

npm i -D @commitlint/cli @commitlint/config-conventional

3. 增加 commit-lint 配置

{
	"extends": ["@commitlint/config-conventional"],
	"rules": {
		"type-empty": [2, "never"],
		"type-enum": [
			2,
			"always",
			[
				"feat",
				"fix",
				"docs",
				"style",
				"refactor",
				"test",
				"revert",
				"chore",
				"perf"
			]
		],
		"body-min-length": [2, "always", 4]
	}
}

4. 修改文件，运行 git commit 提交即可，正常情况下，如果不符合约束规范，会提交失败并提示你重新修改 commit msg，如果遇到以下报错

提示：因为没有将钩子 '.husky/commit-msg' 设置为可执行，钩子被忽略。您可以通过

提示：配置 git config advice.ignoredHook false 来关闭这条警告。

执行 chmod +x .husky/commit-msg 即可

5. 文件注释

一句话介绍：代码也想知道，它是谁，它从哪里来，它要干什么

安装插件

vscode 安装插件：KoroFileHeader

配置

配置文档参考：koroFileHeader配置文档

vscode 设置中搜索 FileHeader，点击编辑 setting.json

增加配置

// 文件注释
	"fileheader.customMade": {
		"custom_string_obkoro1_copyright": "Copyright:xxx提供技术支持",
		"Author": "git config user.name && git config user.email", // 同时获取用户名与邮箱
		"Date": "Do not edit", // 文件创建时间(不变)
		// LastEditors、LastEditTime、FilePath将会自动更新 如果觉得时间更新的太频繁可以使用throttleTime(默认为1分钟)配置更改更新时间。
		"LastEditors": "git config user.name && git config user.email", // 文件最后编辑者 与Author字段一致
		"LastEditTime": "Do not edit", // 文件最后编辑时间
		// 输出相对路径，类似: /文件夹名称/src/index.js
		"FilePath": "Do not edit", // 文件在项目中的相对路径 自动更新
		"Description": "", // 介绍文件的作用、文件的入参、出参。
	},
	// 插件配置项
	"fileheader.configObj": {
		"autoAdd": true, // 检测文件没有头部注释，自动添加文件头部注释
		"autoAlready": true, // 只添加插件支持的语言以及用户通过`language`选项自定义的注释
		"supportAutoLanguage": [], // 设置之后，在数组内的文件才支持自动添加
		// 自动添加头部注释黑名单
		"prohibitAutoAdd": ["json"],
		"folderBlacklist": [ "node_modules" ], // 文件夹或文件名禁止自动添加头部注释
		"dateFormat": "YYYY-MM-DD HH:mm:ss",
		"throttleTime": 60000, // 对同一个文件 需要过1分钟再次修改文件并保存才会更新注释
		// 默认注释  没有匹配到注释符号的时候使用。
		"annotationStr": { 
			"head": "/*",
			"middle": " * @",
			"end": " */",
			"use": false
		},
	}

应用

<!--
* Copyright: xxxx供技术支持
* @Author: 张三 zhangsan@xxx.com
* @Date: 2024-09-24 14:10:39
* @LastEditors: 张三 zhangsan@xxx.com
* @LastEditTime: 2024-09-24 16:18:09
* @FilePath: /xxxx/src/components/HelloWorld.vue
* @Description: 
-->

6. 总结

作者题外话：

从没有规范，到意识规范，于自己，于项目都是一个进步

从有规范，到做好规范，则是一个巨大的跨越和长久的积累

代码的追求是没有止境的，规范的约束也是一样，总有人能从另外的角度，打破现状固有的认知。

我们能做的，无非是在浪潮中找到自己的本心，并坚守本心

真总结：

本文主要针对流行的项目规范做了一个基础的整合，在基本规范的基础上，需要自行查询官方文档做更多私人化的配置，才能用的更好。

Pretter做代码格式化

husky & lint-staged 拦截git 生命周期，做工具化的代码检查

Eslint做代码约束

git-commit-msg，通过提交信息的约束，方便在后续追溯项目的变更

文件注释，清晰文件的来世今生，确保维护的时候一眼就知道文件的功能

avatar
文章
阅读
粉丝