ESLint max-classes-per-file 规则详解：限制单文件中的类数量

ESLint max-classes-per-file 规则详解：限制单文件中的类数量

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

导读

max-classes-per-file是 ESLint 内置的一条代码风格（suggestion）规则，用于限制一个文件里允许出现的类（class）数量上限，默认值为 1。本文基于 ESLint 官方文档docs/src/rules/max-classes-per-file.md，结合仓库源码lib/rules/max-classes-per-file.js与测试用例tests/lib/rules/max-classes-per-file.js，从配置方式、选项语义、源码实现到边界行为，给出完整可复用的实战指南。

为什么需要限制单文件的类数量

包含多个类的文件往往意味着文件承担了过多职责。一个文件里塞进多个类，会带来两类实际问题：

• 可导航性下降：阅读代码时需要频繁在多个类之间跳转，文件越长越难定位目标类；
• 结构松散：多个类堆叠在同一文件，通常暗示它们之间缺乏清晰的模块边界，违背了「每个文件单一职责」的最佳实践。

因此最佳实践是把每个文件限定为单一职责。max-classes-per-file正是用一条可配置的硬约束，把这种「最佳实践」变成可自动化检查的规则：它强制每个文件最多只能包含特定数量的类，超过即报错。

该规则的元数据（lib/rules/max-classes-per-file.js）中recommended: false，意味着它不会出现在eslint:recommended预设里，需要开发者按需显式开启；规则类型为suggestion（建议型），不影响程序运行正确性，属于代码组织层面的约束。

规则行为速览

max-classes-per-file的核心行为非常简单：统计当前文件中出现的类声明（ClassDeclaration）与类表达式（ClassExpression）数量，在程序末尾（Program:exit）判断是否超过上限，超过则报告一条错误。

默认配置（即["error", 1]）下：

• 类表达式默认计入数量，除非显式设置ignoreExpressions: true；
• 嵌套在类方法内部的匿名类表达式同样会被统计（这正是ignoreExpressions选项存在的意义）。

默认配置下的错误示例

以下代码包含两个类声明，超过默认上限 1，错误：

/*eslint max-classes-per-file: "error"*/ class Foo {} class Bar {}

默认配置下的正确示例

以下代码只有一个类，正确：

/*eslint max-classes-per-file: "error"*/ class Foo {}

选项配置详解

规则允许用数字或对象两种形态进行配置，两种形态在源码 schema（lib/rules/max-classes-per-file.js#L26-L48）中通过oneOf互斥定义，同一时刻只能选择其一。

数字形式：直接指定上限

{ "max-classes-per-file": ["error", 1] }

• 数字必须是大于等于 1 的整数（schema 中type: "integer", minimum: 1）；
• 语义等同于{ "max": n }。

对象形式：细粒度控制

{ "max-classes-per-file": [ "error", { "ignoreExpressions": true, "max": 2 } ] }

对象形式支持两个可选项，可单独使用也可同时使用：

配置校验方面，源码 schema 做了两层约束：

• 对象中additionalProperties: false，即不允许出现ignoreExpressions、max之外的任何未知键，配置写错键名会直接抛出 schema 校验错误；
• 与数字形式一致，max也必须是minimum: 1的整数，ignoreExpressions必须是布尔值。

配置解析逻辑（源码视角）

lib/rules/max-classes-per-file.js#L57-L62对两种配置形态做了统一归一化处理：

const option = context.options[0]; const [ignoreExpressions, max] = typeof option === "number" ? [false, option] : [option.ignoreExpressions, option.max || 1];

可以看到：

• 数字形态下ignoreExpressions恒为false（无法通过数字关闭对类表达式的统计）；
• 对象形态下max缺失时回退到默认值1，ignoreExpressions缺失时为undefined（等价于 falsy），行为与默认值一致；
• 未传任何选项时，defaultOptions: [1]（lib/rules/max-classes-per-file.js#L50）保证option为数字1。

选项生效后的正确示例

当max设为 2

下面文件包含两个类声明，恰好达到上限，正确：

/* eslint max-classes-per-file: ["error", 2] */ class Foo {} class Bar {}

当ignoreExpressions设为 true

类表达式（包括返回匿名类的工厂方法）不计入总数，以下代码只有一个类声明，正确：

/* eslint max-classes-per-file: ["error", { ignoreExpressions: true }] */ class VisitorFactory { forDescriptor(descriptor) { return class { visit(node) { return `Visiting ${descriptor}.`; } }; } }

源码实现原理：三类 AST 节点监听

create(context)返回的监听器（lib/rules/max-classes-per-file.js#L57-L95）是整个规则的实现核心，它监听三类节点：

两个值得关注的实现细节：

1. 条件计数，而非过滤统计。当ignoreExpressions: true时，实现方式是「跳过类表达式的自增」，而不是在最终结果里扣除表达式数量。这两者在绝大多数场景下等价，但当多个类表达式嵌套在同一个类声明内部时，结果也保持一致——因为类表达式无论嵌套在哪一层都会被独立访问到。

2. 报告位置精确覆盖整个类区域。报错时（lib/rules/max-classes-per-file.js#L70-L84），报告节点是Program，但loc被精心设置为「从文件第一个语句起点到最后一个语句终点」，并携带两个数据字段：

context.report({ node, loc: { start: node.body[0].loc.start, end: node.body.at(-1).loc.end, }, messageId: "maximumExceeded", data: { classCount, max }, });

对应消息模板为：

File has too many classes ({{ classCount }}). Maximum allowed is {{ max }}.

也就是说，开发者看到的错误信息会同时包含实际类数量与允许上限，例如File has too many classes (3). Maximum allowed is 2.，便于直接判断差距。

测试用例佐证：边界行为一览

仓库测试文件tests/lib/rules/max-classes-per-file.js用RuleTester全面验证了该规则的边界行为，可作为理解规则语义的权威参考：

有效（通过）用例涵盖：

• 单个类声明、单个类表达式、完全不含类的普通变量声明；
• options: [1]、[2]两种数字配置下的通过场景；
• { max: 1 }、{ max: 2 }对象配置下的通过场景；
• { ignoreExpressions: true, max: 1 }下「1 个类声明 + 1 个类表达式」通过；
• { ignoreExpressions: true, max: 2 }下「2 个类声明 + 1 个类表达式」通过；
• 通过/* eslint-disable rule-to-test/max-classes-per-file */行内禁用后，即使两个类也不会报错（证明该规则尊重 eslint-disable 指令）。

无效（报错）用例涵盖：

• 默认配置下两个类声明报错，错误定位覆盖第 1 行第 1 列到第 2 行第 13 列（endColumn: 13恰好是第二个类声明的结尾）；
• 类表达式默认计入：class Foo {}\nconst myExpression = class {}在默认配置下报错，classCount: 2, max: 1；
• 纯类表达式同样计入：var x = class {};\nvar y = class {};在默认配置下也报错；
• 同一行内的多个类class Foo {} class Bar {}同样被准确统计并报错；
• ignoreExpressions: true时，类声明超出上限仍会报错（此时类表达式被忽略，classCount只统计声明）。

这些用例与源码监听逻辑一一对应，构成了规则行为的可回归验证基线。

在配置文件中启用该规则

扁平配置（flat config，eslint.config.js）

import js from "@eslint/js"; export default [ js.configs.recommended, { rules: { "max-classes-per-file": ["error", 1], // 或使用对象形态 // "max-classes-per-file": ["error", { "ignoreExpressions": true, "max": 2 }] } } ];

传统配置（eslintrc，.eslintrc.json）

{ "rules": { "max-classes-per-file": ["error", 1] } }

在传统配置下，也可以在文件顶部用注释行内开启（文档示例即采用该方式）：

/*eslint max-classes-per-file: "error"*/

单行内联配置示例

/* eslint max-classes-per-file: ["error", { ignoreExpressions: true, max: 3 }] */

规则名max-classes-per-file已注册在lib/rules/index.js（第 81 行），采用懒加载方式按需require("./max-classes-per-file")，因此即使项目中没有显式引用，也不会影响启动性能。

与 max-* 系列规则的协同使用

max-classes-per-file属于 ESLint 内置的「复杂度/规模上限」规则家族，同类规则包括：

• max-lines：限制文件总行数；
• max-lines-per-function：限制单个函数行数；
• max-depth：限制块嵌套深度；
• max-params：限制函数参数个数；
• max-statements、max-nested-callbacks、max-len等。

这类规则的共同特点是：都不是recommended预设的一部分，需要团队根据代码规模与模块划分习惯自行设定阈值。实践中，max-classes-per-file: ["error", 1]通常与「单文件单职责」的模块组织规范搭配使用，配合max-lines能同时约束文件「横向膨胀」（类数量）与「纵向膨胀」（总行数）。

注意事项与适用场景

1. 类表达式默认被统计：匿名类、赋值给变量的类表达式都会计入数量。若代码中大量使用工厂模式返回匿名类，建议开启ignoreExpressions: true，避免误报——文档示例中的VisitorFactory.forDescriptor正是这一场景。
2. 规则不区分类的作用域：无论类定义在顶层、函数内部还是嵌套在块中，都会被全局统计。没有作用域级别的豁免机制。
3. 报错为整文件级别：错误会标记在文件整体范围内（从第一个语句到最后一个语句），不具体指向某个「多余」的类，因此修复时需要自行判断哪个类应该拆分到独立文件。
4. 适合渐进式引入：存量代码库中若大量文件包含多个类，直接以 1 为上限会瞬间产生大量报错。可先从max: 3或max: 2起步，逐步收敛到1，并用对象形态配合ignoreExpressions降低误报率。

参考资料

• 规则文档原文：docs/src/rules/max-classes-per-file.md
• 规则源码实现：lib/rules/max-classes-per-file.js
• 规则测试用例：tests/lib/rules/max-classes-per-file.js
• 规则注册入口：lib/rules/index.js

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint