工具

ESLint

我们使用 ESLint 来封装和执行前端代码标准。我们的配置可在 gitlab-eslint-config 项目中找到。

Yarn 脚本

本节描述了可用的 yarn 脚本，用于使用 ESLint 验证文件并应用自动修复。

要使用 ESLint 检查所有暂存文件（基于 git diff），请运行以下脚本：

yarn run lint:eslint:staged

发现的问题列表会记录到控制台。

要对所有暂存文件（基于 git diff）应用自动 ESLint 修复，请运行以下脚本：

yarn run lint:eslint:staged:fix

如果需要手动更改，更改列表会发送到控制台。

要使用 ESLINT 检查仓库中的特定文件，请运行以下脚本（将 $PATH_TO_FILE 替换为实际路径）：

yarn run lint:eslint $PATH_TO_FILE

要使用 ESLint 检查仓库中的 所有 文件，请运行以下脚本：

yarn run lint:eslint:all

发现的问题列表会记录到控制台。

要对仓库中的 所有 文件应用自动 ESLint 修复，请运行以下脚本：

yarn run lint:eslint:all:fix

如果需要手动更改，更改列表会发送到控制台。

新文件中禁用 ESLint

创建新文件时不要禁用 ESLint。现有文件可能由于遗留兼容性原因而禁用了某些现有规则，但这些规则正在重构中。

不要禁用特定的 ESLint 规则。为了避免引入技术债务，只有在调用/实例化现有代码模块时，才可以禁用以下规则。

• no-new
• class-method-use-this

逐行禁用这些规则。这样将来重构时会更轻松。例如，使用 eslint-disable-next-line 或 eslint-disable-line。

针对单个违规禁用 ESLint

如果确实需要为单个违规禁用规则，请禁用最少量的必要代码：

// bad
/* eslint-disable no-new */

import Foo from 'foo';

new Foo();

// better
import Foo from 'foo';

// eslint-disable-next-line no-new
new Foo();

生成待办文件

当启用一个新的 ESLint 规则会发现代码库中存在大量违规时，生成一个待办文件来暂时忽略这些违规可能会更容易。这种方法有一些优缺点：

Pros：

• 特定规则的所有违规文件的单一真实来源。这可以更容易地跟踪偿还已产生技术债务所需的工作。
• 初始启用规则时，更改集更小，因为不需要修改每个违规文件。

Cons：

• 为整个文件禁用规则意味着可以在这些文件中引入更多同类型的违规。
• 在修复多个并发合并请求中的违规时，待办文件中经常会出现冲突，需要 MR 作者变基其分支。

要生成待办文件，请运行 scripts/frontend/generate_eslint_todo_list.mjs 脚本：

node scripts/frontend/generate_eslint_todo_list.mjs <rule_name>

例如，为 vue/no-unused-properties 规则生成待办文件：

node scripts/frontend/generate_eslint_todo_list.mjs vue/no-unused-properties

这会在 .eslint_todo/vue-no-unused-properties.mjs 中创建一个 ESLint 配置，该配置会自动添加到全局配置中。

为特定规则创建待办文件后，请务必规划解决这些违规所需的工作。待办文件应尽可能短暂。如果某些违规无法解决，请通过针对单个违规禁用 ESLint切换到内联忽略。

当所有违规文件都已修复后，应删除待办文件以及 .eslint_todo/index.mjs 中的 export 语句。

no-undef 规则和声明全局变量

永远不要禁用 no-undef 规则。应使用 /* global Foo */ 声明全局变量。

声明多个全局变量时，始终每个变量使用一行 /* global [name] */。

// bad
/* globals Flash, Cookies, jQuery */

// good
/* global Flash */
/* global Cookies */
/* global jQuery */

使用 import/no-deprecated 弃用函数

我们的 @gitlab/eslint-plugin Node 模块包含 eslint-plugin-import 包。

我们可以使用 import/no-deprecated 规则，通过带有 @deprecated 标签的 JSDoc 块来弃用函数：

/**
 * Convert search query into an object
 *
 * @param {String} query from "document.location.search"
 * @param {Object} options
 * @param {Boolean} options.gatherArrays - gather array values into an Array
 * @returns {Object}
 *
 *For example: "?one=1&two=2" into {one: 1, two: 2}
 * @deprecated Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information
 */
export function queryToObject(query, options = {}) {
  ...
}

强烈建议您：

• 为希望使用此函数的开发者提供替代路径。
• 提供跟踪迁移过程的问题链接。

运行此命令后 $ yarn eslint 会给我们弃用用法的列表：

$ yarn eslint

./app/assets/javascripts/issuable_form.js
   9:10  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
  33:23  error  Deprecated: Please use `queryToObject` instead. See https://gitlab.com/gitlab-org/gitlab/-/issues/283982 for more information  import/no-deprecated
...

搜索此规则被禁用的情况，以生成工作列表来创建问题，这样您就可以跟踪移除弃用用法的努力：

$ grep "eslint-disable.*import/no-deprecated" -r .

./app/assets/javascripts/issuable_form.js:import { queryToObject, objectToQuery } from './lib/utils/url_utility'; // eslint-disable-line import/no-deprecate
./app/assets/javascripts/issuable_form.js:  // eslint-disable-next-line import/no-deprecated

我的文件中禁用了 vue/multi-word-component-names

Vue 风格指南 不鼓励使用单名称组件。

它们有问题，因为可能会与其他 HTML 组件混淆：我们可以将组件命名为 <table>，这样就会停止渲染 HTML <table>。

要解决这个问题，您应该重命名 .vue 文件及其引用，使用至少两个单词，例如：

• user/table.vue 可以重命名为 user/users_table.vue，并作为 UsersTable 导入，使用 <users-table />。

GraphQL schema 和操作验证

我们使用 @graphql-eslint/eslint-plugin 来 lint GraphQL schema 和操作。此插件需要完整的 schema 才能正常工作。 因此，建议在本地运行 ESLint 时生成最新的 schema 转储。 您可以通过运行 ./scripts/dump_graphql_schema 脚本来实现。

使用 Prettier 格式化

我们的代码使用 Prettier 自动格式化以遵循我们的风格指南。Prettier 根据标准的 prettier 规则负责格式化 .js、.vue、.graphql 和 .scss 文件。您可以在 .prettierrc 中找到 Prettier 的所有设置。

编辑器

将 Prettier 包含在工作流程中的推荐方法是相应地设置您 的首选编辑器（支持所有主要编辑器）。我们建议 设置 Prettier 在每个文件保存时运行。有关在首选编辑器中使用 Prettier 的说明，请参见 Prettier 文档。

确保只让 Prettier 格式化与全局 Yarn 脚本相同的文件类型（.js、.vue、.graphql 和 .scss）。例如，您可以在 Visual Studio Code 设置文件中排除文件格式：

  "prettier.disableLanguages": [
      "json",
      "markdown"
  ]

Yarn 脚本

以下 yarn 脚本可用于全局格式化：

yarn run lint:prettier:staged:fix

使用 Prettier 更新所有暂存文件（基于 git diff）并保存所需的更改。

yarn run lint:prettier:staged

使用 Prettier 检查所有暂存文件（基于 git diff）并将需要手动更新的文件记录到控制台。

yarn run lint:prettier

使用 Prettier 检查所有文件，并将需要手动更新的文件记录到控制台。

yarn run lint:prettier:fix

使用 Prettier 格式化仓库中的所有文件。

VS Code 设置

选择 Prettier 作为默认格式化程序

要将 Prettier 选择为格式化程序，请将以下属性添加到您的用户或工作区设置：

{
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[graphql]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

保存时格式化

要使用 Prettier 自动格式化您的文件，请将以下属性添加到您的用户或工作区设置：

{
  "[html]": {
    "editor.formatOnSave": true
  },
  "[javascript]": {
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.formatOnSave": true
  },
  "[graphql]": {
    "editor.formatOnSave": true
  },
}