@george2f/eslint-plugin-clean-code

中文文档
0.5.0发布于 2026/10/19MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 8928

ESLint规则出自"清洁码"一书(Robert C. Martin)

中文使用文档
文档目录22 节
  1. 为什么会这样
  2. 安装
  3. 使用量
  4. 配置
  5. 规则等级
  6. 机器可读规则目录
  7. 第17章:气味和热度
  8. 评论
  9. 环境
  10. 职能
  11. 常规
  12. Java 区域
  13. 名称
  14. 测试
  15. 章衍生出的规则
  16. 选项
  17. 自动修正和建议
  18. 与 ESLint 核心规则重叠
  19. 高血压
  20. 发展
  21. 释放
  22. 许可证

埃斯林特- 插座- 清洁码

npm version CI license

ESLint规则来源于 清洁码 由罗伯特·C·马丁(Robert C.

每个规则都映射到一个编号的书规则(第17章"口味和Heuristics",外加从第3,7和9章中选取的规则),每个参考文献都保存在规则元数据中(第17章)meta.docs.cleanCodeId)),所以一个小报告直接指向了这本书.

  • 44个ESLint规则,每本书规则1个
  • 第17章的66个编号的休眠:39个自动化,27个记录表明无法静态地探测(见 第17章 测绘(中文(简体) )
  • ESLint 9 平面配置, TypeScript 友好, 双重无害环境管理/ CJS 构建

为什么会这样

我写这个插件是因为我一直想知道 遵守所有清洁守则规则有多难。 事实证明,对于人类来说是困难的,对于特工来说是微不足道的——所以现在,你的特工们与其遵守规则,不如跟着他们为你. 指着他们 strict,或 strictest 如果你感到勇敢, 他们会写出干净,一致, 严格规则的代码, 它会让即使是最活泼的机器人哭出 一致和干净的快乐的眼泪.

安装

npm install --save-dev eslint @george2f/eslint-plugin-clean-code

需要 ESLint QQ 8.57 (8.57, 9.x和 10.x 支持; 零运行时间依赖性). 这个 configs.recommended 编号 : configs.strict 出口为平面配置对象;关于遗产 .eslintrc 设置, 注册插件 (plugins: ['@george2f/clean-code'])并手动启用规则.

使用量

// eslint.config.js
import cleanCode from '@george2f/eslint-plugin-clean-code';

export default [
  cleanCode.configs.recommended, // 12 high-confidence rules, all errors
  // cleanCode.configs.strict,     // all 44 rules; static = error, heuristic = warn
  // cleanCode.configs.strictest,  // all 44 rules at error, heuristics included
];

或单独选择规则:

import cleanCode from '@george2f/eslint-plugin-clean-code';

export default [
  {
    plugins: { 'clean-code': cleanCode },
    rules: {
      'clean-code/max-arguments': ['error', { max: 4 }],
      'clean-code/law-of-demeter': ['warn', { maxChainLength: 2 }],
    },
  },
];

配置

配置规则严重性意图
clean-code/recommended第12条error可靠的AST检测,低假阳性率
clean-code/strict第44条error 静态/ warn 高压所有的一切,包括有观点的修养
clean-code/strictest第44条error所有错误, 都包含弹性; 期望调用选项

12个 recommended 规则 : max-arguments, (中文(简体) ), no-commented-out-code, (中文(简体) ), no-dead-code, (中文(简体) ), no-encodings, (中文(简体) ), no-flag-arguments, (中文(简体) ), no-magic-numbers, (中文(简体) ), no-negative-conditionals, (中文(简体) ), no-overridden-safeties, (中文(简体) ), no-pass-null, (中文(简体) ), no-return-null, (中文(简体) ), no-skipped-tests, (中文(简体) ), no-todo-tests。 。 。 .

规则等级

  • 静态 - 可靠的AST探测器;船只装入 recommended。 。 。 .
  • 高压 带有可配置选项的以阈值为基础的探测; warn 默认在 strict 财务报告和审定财务报表 error 内 strictest。期望在真实的代码库中调制选项或禁用少数选项;每个Heuristic都有文件记录的选项集(参见 选项) (中文(简体) ).

机器可读规则目录

出版的邮包船 rules.json (作为 @george2f/eslint-plugin-clean-code/rules.json: 每一个带有其书名ID,分级,配置成员,默认选项,JSON schema,自定义/建议旗,以及docs链接的规则. 用于工具与编码代理.

第17章:气味和热度

图例: static 船舶在 recommended • 妇女 heuristic 船舶在 strict 作为警告 doc-only 故意不执行(说明理由)——没有假规则.

评论

身份证书本规则规则仁爱
C1 级信息不当clean-code/no-inappropriate-comments高压
C2级过时注释—— 说仅 doc- —— 需要语义学上的知识 代码
C3 数据冗余注释clean-code/no-redundant-comments高压
C4级错误的书面评论—— 说只有医生——主观;手动审查
第5类注释出代码clean-code/no-commented-out-code静态

环境

身份证书本规则规则仁爱
页:1构建需要更多的步骤—— 说只有医生——保留一个 npm run build; 构建工具,而非线条
E2级测试需要更多的步骤—— 说只有医生——保留一个 npm test; 测试工具,而非用意

职能

身份证书本规则规则仁爱
F1 导弹参数太多clean-code/max-arguments静态
F2 请检查DATE=中的日期值 (帮助) F2输出参数clean-code/no-output-arguments高压
F3 联合国旗帜参数clean-code/no-flag-arguments静态
F4 联合国已死函数clean-code/no-dead-functions柔和主义——只有同一份文件

常规

身份证书本规则规则仁爱
集团1一个源文件中的多语言clean-code/no-multiple-languages高压
G2型明显的行为未执行—— 说只有医生——需要意图;使用TDD和审查
G3集团边界上的不正确行为—— 说仅 doc- -- 边界测试( T5 ), 不用 lint
G4集团安全无虞clean-code/no-overridden-safeties静态
5国集团复制clean-code/no-duplication高压- 相同的文件; 使用 jscpd 用于跨文件克隆
6国集团抽象度错误的代码—— 说只有医生——设计判断
7国集团取决于衍生物的基类clean-code/no-base-class-knowing-derivatives高压
8国集团信息过多clean-code/limited-public-api高压
9国集团死亡代码clean-code/no-dead-code静态
10国集团垂直分离clean-code/declaration-proximity高压
11国集团不一致—— 说只有 doc —— 使用 Pretier 和 共享配置
12国集团克吕特clean-code/no-clutter高压
13国集团人工耦合—— 说只有医生——设计判断
14国集团特性条目clean-code/no-feature-envy高压
15国集团选择参数clean-code/no-selector-arguments高压
16国集团淫荡的意向clean-code/no-obscured-intent高压
17国集团错位责任—— 说只有医生——设计判断
18国集团不适当的静态clean-code/no-inappropriate-statics高压
19国集团使用解释变量clean-code/use-explanatory-variables高压
20国集团函数名称应该说它们做什么clean-code/function-names-say-what-they-do高压
21国集团理解算法—— 说只有医生——需要理解;审查
22国集团建立逻辑依赖—— 说只有医生——设计判断
23国集团偏好多态化到 If/Else 或 switch/ Caseclean-code/prefer-polymorphism高压
24国集团遵守标准公约—— 说只有doc——将公约编码为规则
25国集团将魔法数字替换为命名的常数clean-code/no-magic-numbers静态
26国集团精细clean-code/be-precise高压
27国集团《公约》结构—— 说只有医生——设计判断
28国集团封装条件clean-code/encapsulate-conditionals高压
29国集团避免负条件clean-code/no-negative-conditionals静态
30国集团函数应该做一个东西clean-code/function-does-one-thing高压
31国集团隐藏时间交错—— 说只有 doc —— 需要运行时命令知识
32国集团不要随意—— 说仅 doc- 样式一致性; 使用共享配置
33国集团封装边界条件clean-code/encapsulate-boundaries高压
34国集团函数应仅发送一个抽象级clean-code/one-level-of-abstraction高压
35国集团将可配置数据保持在高水平—— 说只有医生——安置判决
36国集团避免通航(Demeter法)clean-code/law-of-demeter高压

Java 区域

身份证书本规则规则仁爱
J1 数据使用通配符避免长导入列表clean-code/prefer-namespace-imports柔和主义——与树相搏;有意选择
联合来文2不要继承常数clean-code/no-inherited-constants高压
J3 数据常数对 Enums—— 说只有 doc —— TypeScript idioms 与 Java 不同

名称

身份证书本规则规则仁爱
编号1选择描述性名称clean-code/descriptive-names高压
编号2在抽象的适当级别选择名称—— 说只有doc——需要域知识
编号3可能时使用标准名称—— 说仅 doc- 需要项目词典
无无矛盾名称clean-code/no-ambiguous-names高压
编号5长范围使用长名clean-code/long-names-for-long-scopes高压
编号6避免编码clean-code/no-encodings静态
编号7名称应描述边效果clean-code/names-describe-side-effects高压

测试

身份证书本规则规则仁爱
T1 电话测试不足—— 说使用覆盖工具(c8, (中文(简体) ), nyc(中文(简体) )
T2 电话使用覆盖工具!—— 说只有医生——相同
T3 电话不要跳过三次测试clean-code/no-skipped-tests静态
T4 电话被忽略的测试 是一个关于谜题clean-code/no-todo-tests静态
T5型导弹测试边界条件—— 说仅 doc- -- 测试设计, 而非 lint
T6 电话彻底测试 Bugs 附近—— 说仅限医生
T7 电话失败模式正在显现—— 说仅限医生
T8型导弹测试覆盖模式可以揭示—— 说仅限医生
T9 电话测试应该快速—— 说仅限医生

章衍生出的规则

第17章中未列出的前面各章中的规则:

章 次 页 次原则规则仁爱
3个命令查询分离clean-code/command-query-separation高压
3个优先选择返回出错代码的例外clean-code/prefer-exceptions-over-error-codes高压
第7条不要还原clean-code/no-return-null静态
第7条别传努尔clean-code/no-pass-null静态
第9条每一次测试一次clean-code/one-assertion-per-test高压

没有通融规则的章节原则(有文献记载,按设计): Boy Scout Rule, KISS, 找到根源, 使用依赖性注入, 单独多行码, 防止过度配置, 偏好专有值对象于原始人, 隐藏内部结构, 偏好数据结构, F. I. R. S. T. (部分被覆盖) no-skipped-tests 财务报告和审定财务报表 one-assertion-per-test),以及所有格式化规则(使用Pretier).

选项

每个规则都接受一个选项对象;部分选项与下面的默认合并.

规则默认
max-arguments{ max: 3 }
no-dead-code{ ignoreNames: [], ignoreRestSiblings: true }
no-magic-numbers{ ignore: [0, 1, 2, -1], ignoreDefaultValues: true, ignoreArrayIndexes: false, ignoreEnums: true }
no-pass-null{ ignoreCallees: ['^use[A-Z]'] }
no-return-null{ allowNullableReturnType: true }
no-skipped-tests{ testFunctions: ['it', 'test', 'describe', 'context', 'suite', 'specify'] }
no-todo-tests{ testFunctions: ['it', 'test', 'specify'] }
no-inappropriate-comments{ patterns: [] } (外部正则出处)
no-redundant-comments—— 说
no-output-arguments—— 说
no-dead-functions{ allow: [] }
function-does-one-thing{ maxStatements: 20, maxLines: 30 }
one-level-of-abstraction{ minLowLevelOps: 3, minHighLevelCalls: 2 }
no-multiple-languages{ checkSql: true, checkHtml: true }
no-duplication{ minStatements: 4, minNodes: 25 }
limited-public-api{ maxClassMembers: 25, maxExports: 50 }
declaration-proximity{ maxDistance: 15 }
no-feature-envy{ minimumAccesses: 4 }
no-selector-arguments{ minComparisons: 2 }
use-explanatory-variables{ minComplexLookups: 1 }
function-names-say-what-they-do{ forbidden: ['handle', 'process', 'manage', 'util', 'utils', 'misc', 'stuff', 'thing', 'data', 'info', 'temp', 'tmp', 'foo', 'bar', 'baz', 'func', 'fn', 'callback', 'cb', 'do', 'perform', 'execute', 'handleData', 'doStuff', 'doWork', 'doIt'] }
prefer-polymorphism{ maxSwitchCases: 4, maxIfElseBranches: 5 }
encapsulate-conditionals{ maxLogicalOperators: 2 }
law-of-demeter{ maxChainLength: 3, allow: [] }
descriptive-names{ allow: ['i', 'j', 'k', 'x', 'y', 'z', 'e', '_'], forbidden: ['data', 'info', 'stuff', 'thing', 'temp', 'tmp', 'foo', 'bar', 'baz', 'obj', 'arr', 'val', 'utils', 'misc'] }
no-ambiguous-names{ confusingNames: ['l', 'O', 'I'] }
long-names-for-long-scopes{ minLength: 3, allow: ['i', 'j', 'k', 'x', 'y', 'z', 'e', '_', 'it'] }
no-encodings{ patterns: [], typePrefixes: false }
names-describe-side-effects{ prefixes: ['get', 'is', 'has', 'find'] }
prefer-namespace-imports{ maxNamedImports: 10 }
one-assertion-per-test{ maxAssertions: 1, testFunctions: ['it', 'test'] }
no-overridden-safeties{ allowEmptyCatch: false, allowTsIgnore: false, requireDisableReason: true }

上文未列出的规则没有选择权.

max-arguments 将每个绑定物分别计算为分解图案,重复为嵌入图案;剩余绑定物计为一. function f({ a, b, c, d }) 因此,有四个论点.

自动修正和建议

三个规则支持 eslint --fix数字 :

规则自动修正
no-negative-conditionals (29国集团)交换分枝并取出 ! (连续否定语如: !! 在一张通行证内删除)
no-clutter (12国集团)删除出错 ; 语句,将空控流机构转换为 {},删除无用的构造器
no-dead-code (G9,仅进口)删除未使用的导入描述符并重写声明(或发出) import "mod"; 保留模块副作用)

编辑器快速修补(建议——每起事件应用,从未使用过) --fix:

规则建议
C5 / C1 / C3 注释规则删除注释
no-dead-code (9国集团)删除未使用的变量声明(仅在初始化器没有副作用时),或删除无法获取的语句
no-dead-functions (F4级)删除已死函数或私有方法
no-skipped-tests (图3)解开测试
no-clutter (12国集团)删除 debugger 语句
no-overridden-safeties (四国集团)替换 @ts-ignore 与 @ts-expect-error

与 ESLint 核心规则重叠

一些规则有意重新执行与核心规则或其他通俗规则相重叠的书语义. 只允许一方避免重复报告 :

此插件重叠与
max-arguments (F1级)核心项目 max-params
no-magic-numbers (25国集团)核心项目 no-magic-numbers
no-negative-conditionals (29国集团)核心项目 no-negated-condition
no-dead-code (9国集团)核心项目 no-unused-vars, (中文(简体) ), no-unreachable, (中文(简体) ), @typescript-eslint/no-unused-vars
no-obscured-intent (16国集团)核心项目 no-nested-ternary, (中文(简体) ), no-sequences, (中文(简体) ), no-cond-assign
no-skipped-tests (图3)jest/no-disabled-tests, (中文(简体) ), vitest/no-disabled-tests
no-overridden-safeties (四国集团)@typescript-eslint/ban-ts-comment (计: @ts-ignore(中文(简体) )

高血压

高压规则是判决要求的近似值. 每个阈值都是一个选项;如果一个热度在你的代码库中是响亮的,首先调整其选项,然后用一个解释原因的评论来禁用它——这正是书中认可的那种评论.

发展

npm install
npm test            # vitest + ESLint RuleTester (44 rule suites + integration test)
npm run typecheck   # tsc --noEmit
npm run build       # tsup -> dist (minified ESM + CJS + d.ts + rules.json)
npm run verify:dist # checks the built bundles (rule count, configs, meta)
npm run lint        # builds, then lints the plugin with its own rules + typescript-eslint

每一个规则都生活在 src/rules/<rule-name>.ts 与合用地点 .test.ts。书名参考文献在 meta.docs.cleanCodeId 财务报告和审定财务报表 meta.docs.cleanCodeRule. 编码代理的撰稿人笔记 一般事务人员(其他职等)。 。 。 .

释放

用 npm 信任的出版方式( OIDC) 从 CI 发布; 任何地方都不存储任何符号 .

  1. 弹出 version 内 package.json 并添加更改日志条目
  2. 提交,然后标记并按: git tag vX.Y.Z && git push origin vX.Y.Z
  3. .github/workflows/release.yml lints,测试,从匹配的 changlog 部分创建出 GitHub 发布器,并发布出处

一次性设置: 在 npmjs.com 上, 将软件包可信任的出版商配置为 GitHub Actions, profile George2f/eslint-plugin-clean-code工作流程 release.yml (第一次出版必须在配置后的两天内进行).

许可证

麻省理工学院

版本与发布记录

@george2f/eslint-plugin-clean-code 共发布 5 个版本,首次发布于 2026/10/15;过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.0latest2026/10/1927 天前
0.4.12026/10/151 个月前
0.4.02026/10/151 个月前
0.3.02026/10/151 个月前
0.0.0-stage2026/10/151 个月前

关于 @george2f/eslint-plugin-clean-code 的常见问题

@george2f/eslint-plugin-clean-code 是什么?

ESLint规则出自"清洁码"一书(Robert C. Martin)

如何安装 @george2f/eslint-plugin-clean-code?

在项目目录运行 npm install @george2f/eslint-plugin-clean-code,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:eslint(^8.57.0 || ^9.0.0 || ^10.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@george2f/eslint-plugin-clean-code 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@george2f/eslint-plugin-clean-code 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@george2f/eslint-plugin-clean-code 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^18.18.0 || ^20.9.0 || >=21.1.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@george2f/eslint-plugin-clean-code 可以商用吗?

@george2f/eslint-plugin-clean-code 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@george2f/eslint-plugin-clean-code 的下载量有多少?

根据 npm 官方下载统计,@george2f/eslint-plugin-clean-code 在 2026/10/16 – 2026/11/14 这 30 天内被下载 8,928 次,日均约 298 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@george2f/eslint-plugin-clean-code 还在维护吗?

最新版本 0.5.0 发布于 2026/10/19(27 天前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2026/10/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。