【工程化】规范化

相关文章

• 模块化
• 组件化
• 规范化
• 自动化

规范化

---

一、什么叫前端规范化

前端工程化中的规范化是指通过制定统一的规范和标准，对项目的开发、构建、部署等环节进行规范化管理，以提高项目的可维护性、可扩展性和团队协作效率。规范化通常涉及代码风格、命名规范、目录结构、代码组织、代码提交规范等方面。

二、前端规范化的主要特点

• 代码风格规范：制定统一的代码风格规范，包括缩进、空格、换行、命名规范等。可以使用工具如ESLint、Prettier等进行代码风格检查和自动格式化。

• 命名规范：规定统一的命名规范，包括变量、函数、组件、文件等的命名方式，以提高代码的可读性和可维护性。

• 目录结构规范：定义项目的目录结构，包括src、public、assets等目录的划分和命名，以及模块化、组件化的目录组织方式。

• 代码组织规范：规定模块化、组件化的代码组织方式，包括文件的拆分、组件的划分、模块的引入等，以便于代码的复用和维护。

• 代码提交规范：制定统一的代码提交规范，包括提交信息的格式、提交代码的内容、提交频率等，以便于团队成员之间的代码协作和版本管理。

• 文档规范：规范项目文档的编写方式，包括README.md、API文档、组件文档等，以提高项目的可理解性和可维护性。

• 依赖管理规范：规范项目依赖的管理方式，包括依赖的安装、版本控制、依赖关系的管理等，以确保项目的稳定性和安全性。

• 部署规范：规范项目的部署流程和环境，包括开发环境、测试环境、生产环境的配置和部署方式，以确保项目能够顺利上线并保持稳定运行。

三、代码风格规范

使用ESLint

安装 ESLint

npm install eslint --save-dev

创建配置文件

npx eslint --init

创建检查脚本

"scripts": {
  "lint": "eslint ."
}

运行 ESLint

npm run lint

ESLint基础配置内容

// 导出 ESLint 配置对象
module.exports = {
  // 根目录为 ESLint 配置文件所在目录
  root: true,
  // 指定代码运行的环境
  env: {
    // 在 Node.js 环境中运行
    node: true,
    // 支持 ES6 语法
    es6: true,
    // 在浏览器环境中运行
    browser: true
  },
  // 继承其他规则配置
  extends: [
    // 使用 eslint 推荐的规则
    'eslint:recommended',
    // 使用 Vue.js 推荐的规则
    'plugin:vue/recommended' // 使用 Vue.js 推荐的规则
  ],
  // 配置解析器选项
  parserOptions: {
    // 使用 ECMAScript 2021 语法
    ecmaVersion: 2021,
    // 使用 ES6 模块语法
    sourceType: 'module',
    // 使用 Babel 解析器
    parser: 'babel-eslint'
  },
  // 启用的插件
  plugins: [
    // 启用 Vue.js 插件
    'vue'
  ],
  // 自定义规则
  rules: {
    // 允许使用 console
    'no-console': 'off',
    // 警告未使用的变量
    'no-unused-vars': 'warn',
    // HTML 缩进为 2 个空格
    'vue/html-indent': ['error', 2],
    // 更多规则...
  },
  // 忽略检查的文件或目录
  ignorePatterns: ['node_modules/', 'dist/']
};

使用Prettier

安装 Prettier

npm install prettier --save-dev

创建 .prettierrc 文件

在项目根目录下创建一个 .prettierrc 文件

创建检查脚本

"scripts": {
  "format": "prettier --write ."
}

运行 Prettier

npm run format

Prettier基础配置内容

{
  // 指定一行的最大长度
  "printWidth": 80,
  
  // 指定一个 tab 缩进的空格数
  "tabWidth": 2,
  
  // 指定是否使用制表符进行缩进
  "useTabs": false,
  
  // 指定是否在语句末尾添加分号
  "semi": true,
  
  // 指定是否使用单引号替代双引号
  "singleQuote": false,
  
  // 指定是否为对象字面量的属性添加引号
  "quoteProps": "as-needed",
  
  // 指定是否在 JSX 中使用单引号
  "jsxSingleQuote": false,
  
  // 指定对象或数组最后一个元素的尾逗号
  "trailingComma": "none",
  
  // 指定是否在对象字面量的括号内添加空格
  "bracketSpacing": true,
  
  // 指定 JSX 的尖括号是否单独放在一行
  "jsxBracketSameLine": false,
  
  // 指定箭头函数的参数是否使用括号包裹
  "arrowParens": "avoid"
}

四、命名规范

命名规范和约定可参考

• JavaScript Standard Style：JavaScript Standard Style 是一个通用的 JavaScript 代码风格规范，提供了一组关于代码格式、命名风格和最佳实践的建议。它的设计目标是简洁、一致和易于理解。它包含了许多命名规范的建议。

• Airbnb JavaScript Style Guide：Airbnb JavaScript Style Guide 是 Airbnb 公司发布的一套 JavaScript 代码风格指南，它提供了详细的代码规范和最佳实践建议，包括命名规范、代码结构、格式化等方面。这个指南也包含了一些命名规范的建议。

• Google JavaScript Style Guide：Google JavaScript Style Guide 是 Google 公司发布的一套 JavaScript 代码风格指南，它包含了一系列关于命名、格式化、注释等方面的建议。虽然它主要针对 Google 内部的开发者，但其中的许多建议也适用于其他项目。

五、目录结构规范

常见的约定和最佳实践，可以作为参考：

• 分层结构：通常，项目的目录结构可以按照不同的功能或模块进行分层组织，例如将代码按照业务逻辑划分为不同的模块或功能模块。

• 主目录：项目的主目录应该包含项目的核心文件和配置文件，例如 package.json、.gitignore、README.md 等。

• 源码目录：源码通常位于一个名为 src 或 app 的目录中，其中包含了项目的主要代码文件。

• 静态资源目录：通常，静态资源（例如图片、样式表、字体等）会被放置在一个名为 assets 或 static 的目录中。

• 测试目录：测试文件通常位于一个名为 tests、tests 或 spec 的目录中，用于存放项目的单元测试、集成测试等测试文件。

• 配置文件：配置文件（例如 ESLint、Prettier、Webpack 等）通常被放置在项目的根目录中，以便于项目的管理和维护。

• 构建产物目录：构建产物（例如打包后的文件、编译后的代码等）通常被放置在一个名为 dist、build 或 out 的目录中。

六、代码提交规范

代码提交规范是指在团队协作开发中约定统一的代码提交格式和规范，以便于团队成员之间更好地协作、沟通和追踪代码变更。下面是一个常见的代码提交规范，通常采用约定式提交（Conventional Commits）规范：

• 类型（type）：用于指定本次提交的类型，常见的类型包括：

  • feat：新增功能（feature）
  • fix：修复 bug
  • docs：文档更新
  • style：代码样式调整，不影响功能的变动（例如空格、格式化等）
  • refactor：代码重构，既不修复 bug 也不添加新功能的代码修改
  • perf：性能优化
  • test：新增或更新测试代码
  • chore：构建过程或辅助工具的变动

• 范围（scope）：可选项，用于指定本次提交影响的范围，例如模块、文件等。

• 描述（description）：对本次提交进行简要描述，清晰明了地说明本次提交的目的和内容。

• 主体（body）：可选项，用于进一步详细描述本次提交的内容，可以包括解决的问题、实现的功能、影响的范围等。

• 页脚（footer）：可选项，用于添加一些额外的元信息，例如关联的 issue、关闭的 issue 等。

一个符合约定式提交规范的示例提交消息可能如下所示：

feat: 添加用户登录功能

为项目添加了用户登录功能，包括用户登录页面、验证逻辑和用户信息存储。

BREAKING CHANGE: 用户信息存储方式发生了变化，原先的 localStorage 存储方式被替换为 sessionStorage 存储方式。

使用husky

Husky 是一个可以在 Git hooks 中运行脚本的工具，通常用于在提交代码前执行一些检查或操作，比如格式化代码、运行测试等。下面是使用 Husky 的配置方法：

• 安装 Husky

首先，需要在项目中安装 Husky。可以使用 npm 或 yarn 进行安装，例如：

npm install husky --save-dev

• 配置 package.json

配置 package.json：在项目的 package.json 文件中添加 Husky 的配置。在 scripts 字段下添加 precommit 钩子的配置，示例如下：

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.js": "eslint --fix"
  }
}

上面的配置表示在提交代码前会先运行 lint-staged 命令，lint-staged 会对暂存区中的文件进行 lint 检查，此处配置的是对所有 .js 文件运行 eslint –fix 命令。

• 使用 Husky 提供的命令安装 Git hooks

执行以下命令可以将 Husky 配置为 Git hooks：

npx husky install

• 添加 Git hook

在执行上述命令后，Husky 会自动在 .git/hooks 目录下创建对应的 Git hook，并在其中调用 package.json 中配置的脚本。例如，对应 precommit 钩子的脚本会被添加到 .git/hooks/pre-commit 文件中。

七、文档规范

文档规范是指在软件开发过程中，对文档的编写、格式、组织、命名等方面进行规范化的约定。良好的文档规范能够提高团队成员之间的沟通效率，降低沟通成本，促进项目的顺利开展和维护。下面是一些常见的文档规范内容：

• 文档结构与组织

  • 文档应该按照一定的层次结构进行组织，使得各部分内容清晰明了、逻辑合理。
  • 常见的文档组织结构包括：封面、目录、引言、概述、详细内容、附录、参考资料等。

• 命名规范

  • 文档的文件名、标题、章节名称等应该使用清晰、准确的命名，能够准确反映文档内容。
  • 文件名和目录名建议使用短横线分隔单词（kebab-case）或下划线分隔单词（snake_case），避免使用空格或特殊字符。

• 格式规范

  • 文档内容应该使用统一的格式进行排版，包括字体、字号、段落间距、标题样式等。
  • 推荐使用标记语言（如Markdown、AsciiDoc等）编写文档，以方便版本控制和跨平台查看。

• 文档内容

  • 文档应该包含项目的基本信息、背景介绍、需求分析、设计思路、使用方法、常见问题解答等内容。
  • 对于API文档，需要详细说明每个接口的参数、返回值、使用示例等。

• 注释规范

  • 在代码中应该添加清晰明了的注释，说明代码的作用、用法、注意事项等信息，以提高代码的可读性和可维护性。

• 版本控制

  • 文档也应该进行版本控制，与代码同步更新，确保文档与代码保持一致。
  • 推荐使用Git等版本控制工具管理文档的版本。

• 文档工具

  • 常用的文档编写工具有Markdown编辑器、AsciiDoc编辑器等，选择适合团队的工具进行文档编写和管理。

八、依赖管理规范

依赖管理规范是指在前端工程化中，对项目所需依赖的管理方式进行规范化的约定。良好的依赖管理规范能够保证项目的稳定性、可维护性和可扩展性，提高团队协作效率。下面是一些常见的依赖管理规范内容：

• 依赖声明

  • 在项目根目录下维护一个清晰的依赖声明文件（如package.json），用于记录项目所需的依赖信息，包括名称、版本号、依赖类型等。
  • 对于前端项目，通常使用NPM（Node Package Manager）或Yarn来管理依赖。

• 版本锁定

  • 应该尽量锁定项目依赖的版本，避免出现版本冲突或不兼容的情况。
  • 推荐使用精确的版本号（如^1.2.3或~1.2.3）来锁定主版本号、次版本号和修订版本号。

• 依赖安装

  • 在安装依赖时，应该使用固定的命令（如npm install或yarn install）来确保所有依赖都被正确安装。
  • 避免手动修改依赖文件或直接修改node_modules目录中的文件。

• 依赖更新

  • 定期检查项目依赖的更新情况，及时更新到最新版本，以确保项目的安全性和性能。
  • 在更新依赖时，应该谨慎处理可能引入的兼容性问题，避免影响现有功能。

• 依赖移除

  • 当项目不再需要某个依赖时，应该及时移除该依赖，以减少项目的体积和复杂度。
  • 在移除依赖时，需要确保没有其他模块依赖该依赖，以免影响项目的正常运行。

• 依赖管理工具

  • 选择合适的依赖管理工具（如NPM、Yarn、pnpm等）进行依赖管理，根据团队的实际情况进行选择。

九、部署规范

部署规范是指在前端工程化中，对项目部署流程和规则进行规范化的约定。一个良好的部署规范可以提高项目部署的效率，降低出错的概率，保证项目的稳定运行。下面是一些常见的部署规范内容：

• 环境区分

  • 将不同的部署环境（如开发环境、测试环境、预发布环境和生产环境）进行明确区分，并在部署过程中区分不同环境的配置和操作。

• 版本控制

  • 使用版本控制工具（如Git）对项目代码进行管理，确保代码的版本可追溯性和可回滚性。
  • 在部署时，应该选择特定的代码版本进行部署，避免部署过程中出现意外情况。

• 自动化部署

  • 建立自动化部署流程，通过自动化工具（如Jenkins、Travis CI等）来实现项目的自动构建、测试和部署。
  • 自动化部署可以提高部署的效率和一致性，减少人工操作带来的错误。

• 构建优化

  • 在构建过程中，应该进行资源压缩、代码混淆、图片优化等优化操作，减少项目的体积和加载时间。
  • 针对不同环境，可以配置不同的构建参数，以满足各个环境的需求。

• 备份和回滚

  • 在部署之前，应该进行数据备份，并确保可以随时进行项目的回滚操作，以应对部署过程中可能出现的问题。
  • 对于数据库和静态资源等重要数据，应该定期进行备份，以防止数据丢失。

• 日志记录

  • 在部署过程中，应该记录关键步骤和操作，并生成详细的部署日志，以便排查和分析部署过程中出现的问题。
  • 对于生产环境，应该建立日志监控系统，及时发现和处理异常情况。

• 安全性考虑

  • 在部署过程中，应该考虑项目的安全性，确保部署的系统和环境都是安全可靠的。
  • 对于敏感信息和权限控制等关键问题，应该采取相应的安全策略和措施，防止出现安全漏洞。

• 沟通与协作

  • 在部署过程中，应该加强团队成员之间的沟通与协作，确保每个人都清楚自己的任务和责任，并及时进行沟通和协调。