JavaScript代码风格指南：Formatter配置与使用 – wiki基地

作者： /

JavaScript 代码风格指南：Formatter 配置与使用

在现代 JavaScript 开发中，保持代码风格的一致性至关重要。它不仅能提高代码的可读性和可维护性，还能减少团队协作中的摩擦，降低出错的可能性。代码格式化工具（Formatter）在实现这一目标方面发挥着核心作用。本文将深入探讨 JavaScript 代码风格指南中 Formatter 的配置与使用，涵盖 Prettier 和 ESLint 两个主流工具，并提供详细的配置示例和最佳实践。

1. 为什么需要代码格式化工具（Formatter）？

在深入配置细节之前，我们首先要明确为什么 Formatter 如此重要。以下是几个关键原因：

  • 一致性： 团队成员可能来自不同的背景，拥有各自的编码习惯。Formatter 强制执行统一的代码风格，消除个人偏好带来的差异，确保整个项目代码库的一致性。
  • 可读性： 格式良好的代码更易于阅读和理解。合理的缩进、空格、换行等，能够清晰地展现代码的结构和逻辑，降低阅读障碍。
  • 可维护性： 一致且可读的代码更容易维护。当需要修改或调试代码时，清晰的格式可以帮助开发者快速定位问题，减少出错的风险。
  • 减少争议： 关于代码风格的争论往往是浪费时间的。通过使用 Formatter 并达成共识，团队可以避免此类争论，将精力集中在更重要的业务逻辑上。
  • 自动化： Formatter 可以集成到开发流程中，实现代码格式化的自动化。无需手动调整格式，节省时间和精力。
  • 减少代码审查负担：通过工具自动处理格式问题，可以将代码审查的重点放在代码逻辑，架构和安全性等问题上。

2. 主流 JavaScript Formatter：Prettier vs. ESLint

在 JavaScript 生态中，Prettier 和 ESLint 是最受欢迎的代码格式化和代码检查工具。它们各有侧重，通常会结合使用以达到最佳效果。

2.1 Prettier：专注于代码格式化

Prettier 是一个“有主见”的代码格式化工具。它会接管你所有的代码格式化工作，并按照它自己的一套规则进行格式化。这意味着你无需花费大量时间去配置各种格式化选项，只需信任 Prettier 的默认设置即可。

Prettier 的主要特点：

  • 易于使用： 安装和配置非常简单，几乎无需任何自定义配置即可开始使用。
  • “有主见”： 遵循一套固定的格式化规则，减少配置的复杂性。
  • 支持多种语言： 不仅支持 JavaScript，还支持 HTML、CSS、JSON、Markdown 等多种语言。
  • 集成广泛： 可以与各种编辑器、IDE 和构建工具集成。

2.2 ESLint：代码检查与格式化

ESLint 最初是一个 JavaScript 代码检查工具（Linter），用于发现代码中的潜在问题（例如未使用的变量、语法错误等）。后来，ESLint 也加入了代码格式化功能。与 Prettier 不同，ESLint 的格式化规则更加灵活可配置。

ESLint 的主要特点：

  • 代码检查： 除了格式化，ESLint 的主要功能是发现代码中的潜在问题。
  • 高度可配置： 可以通过配置文件详细控制各种格式化规则和代码检查规则。
  • 插件丰富： 拥有庞大的插件生态系统，可以扩展其功能以支持各种框架和库（例如 React、Vue、TypeScript 等）。
  • 与 Prettier 集成： 可以通过插件（eslint-config-prettier 和 eslint-plugin-prettier）与 Prettier 集成，充分利用两者的优势。

2.3 Prettier vs. ESLint：如何选择？

Prettier 和 ESLint 并非相互排斥，而是可以互补的。通常的最佳实践是将两者结合使用：

  • 使用 Prettier 进行代码格式化： 利用 Prettier 的“有主见”特性，快速、一致地格式化代码。
  • 使用 ESLint 进行代码检查和补充格式化规则： 利用 ESLint 的代码检查功能发现潜在问题，并使用 ESLint 的格式化规则对 Prettier 未覆盖的方面进行补充。

这种组合可以充分发挥两者的优势，既能保证代码格式的一致性，又能及时发现代码中的潜在问题。

3. Prettier 的配置与使用

3.1 安装

通过 npm 或 yarn 安装 Prettier：

“`bash
npm install –save-dev prettier

或者

yarn add –dev prettier
“`

3.2 配置文件

Prettier 的配置文件可以是以下几种格式之一：

  • .prettierrc: JSON 格式
  • .prettierrc.json: JSON 格式
  • .prettierrc.yml: YAML 格式
  • .prettierrc.yaml: YAML 格式
  • .prettierrc.toml: TOML 格式
  • .prettierrc.js: JavaScript 格式
  • prettier.config.js: JavaScript 格式
  • package.json 中的 prettier 属性

推荐使用 .prettierrc.json 或 .prettierrc.yml 文件。以下是一个 .prettierrc.json 文件的示例：

json
{
"printWidth": 80,
"tabWidth": 2,
"useTabs": false,
"semi": true,
"singleQuote": true,
"trailingComma": "es5",
"bracketSpacing": true,
"arrowParens": "avoid"
}

常见配置选项说明：

  • printWidth: (number) 每行代码的最大字符数，超过会自动换行。
  • tabWidth: (number) 缩进的空格数（当 useTabs 为 false 时）。
  • useTabs: (boolean) 是否使用 Tab 键进行缩进（true）还是使用空格（false）。
  • semi: (boolean) 是否在语句末尾添加分号。
  • singleQuote: (boolean) 是否使用单引号（true）还是双引号（false）。
  • trailingComma: (“none” | “es5” | “all”) 尾随逗号的配置：
    • "none": 不添加尾随逗号。
    • "es5": 在 ES5 中有效的对象和数组中添加尾随逗号。
    • "all": 在所有可能的地方都添加尾随逗号（包括函数参数）。
  • bracketSpacing: (boolean) 是否在对象字面量的括号和属性之间添加空格。
  • arrowParens: (“avoid” | “always”) 箭头函数参数的括号配置：
    • "avoid": 尽可能省略括号（例如 x => x）。
    • "always": 始终添加括号（例如 (x) => x）。

你可以根据自己的喜好调整这些选项。Prettier 的官方文档提供了所有配置选项的详细说明：https://prettier.io/docs/en/options.html

3.3 在编辑器/IDE 中使用

大多数主流编辑器和 IDE 都支持 Prettier 插件。以 VS Code 为例：

  1. 安装 Prettier – Code formatter 插件。
  2. 在 VS Code 的设置中，将 Prettier 设置为默认的格式化工具：
    • 打开设置（File > Preferences > Settings）。
    • 搜索 “Default Formatter”。
    • 选择 “Prettier – Code formatter”。
  3. 可以启用 “Format On Save” 功能，在每次保存文件时自动格式化代码：
    • 搜索 “Format On Save”。
    • 勾选 “Editor: Format On Save”。

3.4 在命令行中使用

可以在命令行中运行 Prettier 来格式化文件：

“`bash

格式化单个文件

prettier –write src/index.js

格式化整个目录

prettier –write src/

检查文件是否已格式化（不修改文件）

prettier –check src/
“`

3.5 与 Git 集成（可选）

为了确保提交到代码仓库的代码都经过格式化，可以将 Prettier 与 Git 集成。推荐使用 husky 和 lint-staged 工具：

  1. 安装 husky 和 lint-staged：

    “`bash
    npm install –save-dev husky lint-staged

    或者

    yarn add –dev husky lint-staged
    “`

  2. 在 package.json 中配置：

    json
    {
    "scripts": {
    "prepare": "husky install"
    },
    "lint-staged": {
    "*.{js,jsx,ts,tsx}": "prettier --write"
    }
    }
    3. 添加 pre-commit 钩子:

    npx husky add .husky/pre-commit "npx lint-staged"

这样，在每次提交代码之前，lint-staged 会自动运行 Prettier 来格式化暂存区中的文件。

4. ESLint 的配置与使用

4.1 安装

通过 npm 或 yarn 安装 ESLint：

“`bash
npm install –save-dev eslint

或者

yarn add –dev eslint
“`

4.2 配置文件

ESLint 的配置文件可以是以下几种格式之一：

  • .eslintrc.js: JavaScript 格式
  • .eslintrc.cjs: CommonJS 格式
  • .eslintrc.json: JSON 格式
  • .eslintrc.yaml: YAML 格式
  • .eslintrc.yml: YAML 格式
  • package.json 中的 eslintConfig 属性

推荐使用 .eslintrc.js 文件，因为它支持注释和更复杂的配置。以下是一个 .eslintrc.js 文件的示例：

javascript
module.exports = {
env: {
browser: true,
es2021: true,
node: true,
},
extends: [
'eslint:recommended',
'plugin:react/recommended', // 如果使用 React
'plugin:prettier/recommended', // 添加 Prettier 插件
],
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module',
ecmaFeatures: {
jsx: true, // 如果使用 React
},
},
rules: {
// 自定义规则
'no-unused-vars': 'warn',
'no-console': 'off',
},
settings: {
react: {
version: 'detect', // 自动检测 React 版本
},
},
};

配置选项说明：

  • env: 指定代码运行的环境。常见的环境包括：
    • browser: 浏览器环境。
    • es2021: 支持 ES2021 语法。
    • node: Node.js 环境。
  • extends: 继承其他配置。常见的配置包括：
    • eslint:recommended: ESLint 的推荐规则。
    • plugin:react/recommended: React 项目的推荐规则（需要安装 eslint-plugin-react）。
    • plugin:prettier/recommended: 将 Prettier 集成到 ESLint 中（需要安装 eslint-plugin-prettier 和 eslint-config-prettier）。
  • parserOptions: 解析器选项。
    • ecmaVersion: 指定 ECMAScript 版本。
    • sourceType: 指定代码类型（'module' 或 'script'）。
    • ecmaFeatures: 启用额外的语言特性（例如 JSX）。
  • rules: 自定义规则。可以覆盖继承的规则或添加新的规则。
    • 'off' 或 0: 关闭规则。
    • 'warn' 或 1: 将规则视为警告。
    • 'error' 或 2: 将规则视为错误。
  • settings: 共享设置，可以被插件使用。

4.3 与 Prettier 集成

为了将 Prettier 集成到 ESLint 中，需要安装以下插件：

“`bash
npm install –save-dev eslint-plugin-prettier eslint-config-prettier

或者

yarn add –dev eslint-plugin-prettier eslint-config-prettier
“`

  • eslint-plugin-prettier: 将 Prettier 作为 ESLint 规则运行。
  • eslint-config-prettier: 关闭 ESLint 中与 Prettier 冲突的规则。

然后在 .eslintrc.js 文件中添加 plugin:prettier/recommended：

javascript
module.exports = {
// ...
extends: [
// ...
'plugin:prettier/recommended', // 确保放在最后
],
// ...
};

plugin:prettier/recommended 做了以下几件事：

  1. 启用 eslint-plugin-prettier。
  2. 将 prettier/prettier 规则设置为 "error"。
  3. 扩展 eslint-config-prettier。

4.4 在编辑器/IDE 中使用

大多数主流编辑器和 IDE 都支持 ESLint 插件。以 VS Code 为例：

  1. 安装 ESLint 插件。
  2. VS Code 会自动检测项目中的 ESLint 配置文件并应用相应的规则。

4.5 在命令行中使用

可以在命令行中运行 ESLint 来检查代码：

“`bash

检查单个文件

npx eslint src/index.js

检查整个目录

npx eslint src/

自动修复可修复的问题

npx eslint src/ –fix
“`

4.6 与 Git 集成

与 Prettier 类似，可以使用 husky 和 lint-staged 将 ESLint 集成到 Git 中：

json
{
"scripts": {
"prepare": "husky install"
},
"lint-staged": {
"*.{js,jsx,ts,tsx}": ["prettier --write", "eslint --fix"]
}
}

npx husky add .husky/pre-commit "npx lint-staged"

这样，在每次提交代码之前，会先运行 Prettier 格式化代码，然后运行 ESLint 进行检查和修复。

5. 最佳实践

  • 尽早引入 Formatter： 在项目初期就引入 Formatter，避免后期大规模格式化代码的痛苦。
  • 团队统一配置： 团队成员使用相同的 Formatter 配置，确保整个项目代码风格的一致性。
  • 编辑器/IDE 集成： 利用编辑器/IDE 的插件，实现代码保存时自动格式化。
  • 与 Git 集成： 使用 husky 和 lint-staged，在提交代码前自动格式化和检查代码。
  • 定期审查配置： 随着项目的发展和团队成员的变化，定期审查 Formatter 配置，确保其仍然符合团队的需求。
  • 不要过度配置： 尽量使用 Formatter 的默认配置，避免过度配置带来的复杂性。
  • 处理遗留代码： 对于已有的，未格式化的代码库，可以考虑分批次，分模块逐步格式化。

6. 总结

代码格式化工具（Formatter）是现代 JavaScript 开发中不可或缺的一部分。Prettier 和 ESLint 是两个主流的 Formatter，它们各有侧重，通常会结合使用。本文详细介绍了 Prettier 和 ESLint 的配置与使用，包括安装、配置文件、编辑器/IDE 集成、命令行使用以及与 Git 集成。通过遵循最佳实践，团队可以充分利用 Formatter 的优势，提高代码质量、可读性和可维护性，减少团队协作中的摩擦，最终提升开发效率。希望这篇文章能帮助你更好地理解和应用 JavaScript 代码风格指南中的 Formatter。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部