eslint-plugin-unicorn 规则生命周期完全指南Deprecated 与 Deleted 规则迁移手册【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn本篇指南系统梳理 eslint-plugin-unicorn 仓库中 docs/deleted-and-deprecated-rules.md 记录的 27 个历史规则逐一说明它们为何被废弃deprecated或删除deleted以及各自对应的替代规则。读完本文你将掌握旧规则与新规则的完整映射关系能在一分钟内完成既有 ESLint 配置的迁移并理解该项目规则命名的演进哲学与底层实现机制。为什么需要关注规则的废弃与删除eslint-plugin-unicorn 是一套提供 300 条 ESLint 规则的开源插件规则覆盖面越广持续演进就越不可避免。当一条规则的能力被另一条规则吸收、命名不够清晰、或者底层依赖失效时维护者会选择以下两种处理方式废弃Deprecated旧规则名仍被注册但不再执行任何检查no-op并在 ESLint 元信息中标记deprecated与replacedBy引导用户切换到新规则删除Deleted旧规则名从插件中彻底移除直接在 rules/index.js 的导出列表中消失配置中引用它们会触发 rule not found 错误。理解这两者的区别是完成迁移的第一步。一、已废弃规则Deprecated Rules仍可引用但已是空操作截至本文档记录共有 9 条规则处于废弃状态。它们的特点是名字仍然保留在插件的规则注册表中配置旧名称不会报错但规则本体不再产出任何检查结果也就是文档中所说的 the old rule is now a no-op。旧规则名状态说明替代规则no-unused-array-method-return被更全面的规则替代no-unused-builtin-method-return额外覆盖 Set 与 Temporal 方法no-instanceof-array被更全面的规则替代no-instanceof-builtins覆盖更多内建类型no-array-push-push被更全面的规则替代prefer-single-call覆盖更多可合并的调用no-length-as-slice-end被更全面的规则替代no-unnecessary-slice-end覆盖更多情况no-hex-escape被更全面的规则替代prefer-unicode-code-point-escapes覆盖更多情况prevent-abbreviations改名name-replacementsprefer-dom-node-dataset改名dom-node-datasetprefer-json-parse-buffer改名consistent-json-file-readbetter-regex因底层库存在 bug 且缺乏支持而被移除无内置替代项目建议使用独立的eslint-plugin-regexp值得注意的是no-unused-array-method-return与no-unused-builtin-method-return的关系后者把检查范围从数组方法扩展到了 Set 的union()、intersection()、difference()等返回新集合的操作以及 Temporal 不可变类型的add()、subtract()、round()等方法完整支持矩阵见 no-unused-builtin-method-return 文档 中的 Temporal 方法表格。二、已删除规则Deleted Rules彻底移除引用即报错下面 18 条规则已从插件中完全删除按去向可归纳为三类改名、被更全面的规则吸收、因过时或缺陷直接移除。2.1 被更全面的规则吸收旧规则名状态说明替代规则no-array-instanceof被更全面的规则替代no-instanceof-builtins2.2 重命名改名后职责更清晰旧规则名改名原因新规则名no-array-for-each重命名no-for-eachno-fn-reference-in-iterator避免在规则名中使用缩写fnno-array-callback-referenceno-reduce让规则名更具体no-array-reduceprefer-dataset重命名dom-node-datasetprefer-event-key让规则名更具体prefer-keyboard-event-keyprefer-flat-map让规则名更具体prefer-array-flat-mapprefer-node-append减少歧义不只针对 Node.jsprefer-dom-node-appendprefer-node-remove减少歧义不只针对 Node.jsprefer-dom-node-removeprefer-replace-all让规则名更具体prefer-string-replace-allprefer-starts-ends-with让规则名更具体prefer-string-starts-ends-withprefer-text-content让规则名更具体prefer-dom-node-text-contentprefer-trim-start-end让规则名更具体prefer-string-trim-start-endregex-shorthand新规则职责远超简写better-regex从这一长串改名记录中可以清晰看出项目维护者的命名约定涉及内置对象方法的一律加上对象类型前缀array-、string-、dom-node-、keyboard-event-这使规则名成为可自我描述的文档也让用户在几百条规则中能通过前缀快速定位。2.3 直接移除旧规则名移除原因import-index规则已过时ESMJavaScript 模块不支持导入目录该写法本身已失去意义no-unsafe-regex因存在 bug 而移除prefer-exponentiation-operator让位于 ESLint 内置的同名规则prefer-object-has-own让位于 ESLint 内置的同名规则其中prefer-exponentiation-operator与prefer-object-has-own的移除尤其值得注意当 ESLint 核心库提供了等价能力时插件主动让位避免重复造轮子这也解释了仓库中 configs/core-rule-replacements.js 这类核心规则替换配置存在的意义——当用户在推荐配置中启用了被内置规则覆盖的插件规则时插件会自动将其转为off。三、源码视角Deprecated 规则是如何空转的要理解废弃规则为何是 no-op可以直接阅读 rules/utils/create-deprecated-rules.js 的工厂函数。核心逻辑是create: () ({}), meta: { docs: { description: deprecatedInfo.message, url, }, deprecated: { message: deprecatedInfo.message, url, replacedBy: deprecatedInfo.replacedBy.map(replacementRuleId ({ rule: { name: replacementRuleId, url: getDocumentationUrl(replacementRuleId), }, })), }, },这段代码揭示了三个关键机制空 create 函数create: () ({})返回空对象意味着规则遍历 AST 时不注册任何访问器因此不产生任何诊断信息——这就是no-op的源码级含义标准化的 deprecated 元信息通过meta.deprecated.message与meta.deprecated.replacedBy向 ESLint 与 IDE 暴露废弃提示和替代规则链接支持 ESLint 规范的废弃规则协议文档锚点链接每个废弃规则的文档 URL 都指向docs/deleted-and-deprecated-rules.md中对应规则名的小节。而废弃规则的注册清单定义在插件入口 index.js 中例如const deprecatedRules createDeprecatedRules({ no-unused-array-method-return: { message: Replaced by unicorn/no-unused-builtin-method-return which covers more cases., replacedBy: [unicorn/no-unused-builtin-method-return], }, // ... });随后这些废弃规则与正常规则合并进导出对象const unicorn { meta: { name: packageJson.name, version: packageJson.version, }, rules: { ...rules, ...deprecatedRules, }, };可以推断已删除与已废弃在代码层面的分界线就是deprecatedRules注册表——登记在案的旧规则名仍可被解析但空转未登记的名字则因为 rules/index.js 不再导出而彻底失效。四、迁移实操三步完成配置更新步骤 1定位旧规则使用点在项目配置如eslint.config.js或旧式.eslintrc中全局搜索以下任一旧名称例如grep -rE unicorn/(no-unused-array-method-return|no-instanceof-array|no-array-push-push|no-length-as-slice-end|no-hex-escape|prevent-abbreviations|prefer-dom-node-dataset|prefer-json-parse-buffer|better-regex) .其中 9 条废弃规则引用时不会报配置错误但 ESLint/编辑器会在 IDE 中显示规则已废弃提示并给出替代规则而 18 条已删除规则会直接产生 Definition for rule unicorn/xxx was not found 之类的报错。步骤 2按映射表替换以最典型的几条为例替换后的配置如下// ❌ 旧配置 unicorn/no-unused-array-method-return: error, unicorn/no-instanceof-array: error, unicorn/no-array-push-push: error, unicorn/no-length-as-slice-end: error, unicorn/no-hex-escape: error, unicorn/prevent-abbreviations: error, unicorn/prefer-dom-node-dataset: error, unicorn/prefer-json-parse-buffer: error, unicorn/better-regex: error, // ✅ 新配置 unicorn/no-unused-builtin-method-return: error, unicorn/no-instanceof-builtins: error, unicorn/prefer-single-call: error, unicorn/no-unnecessary-slice-end: error, unicorn/prefer-unicode-code-point-escapes: error, unicorn/name-replacements: error, unicorn/dom-node-dataset: error, unicorn/consistent-json-file-read: error, // better-regex 无内置替代建议改用独立的 eslint-plugin-regexp步骤 3留意替代规则的选项差异替换不是简单改个名字新规则往往带有更丰富的配置。例如no-instanceof-builtins新增了strategyloose | strict默认loose、include、exclude、useErrorIsError四个选项详见 no-instanceof-builtins 文档prefer-single-call提供ignore选项默认忽略stream.push、process.stdin.push等非数组接收者详见 prefer-single-call 文档。迁移时若旧配置携带选项务必对照新规则文档逐一确认。步骤 4验证迁移后运行完整检查npx eslint .确认不再出现旧规则相关报错并可通过 test/no-instanceof-builtins.js 等规则测试文件了解新规则的判定边界以便在真实代码中调整写法。五、从规则演进中读懂项目的设计原则梳理全部 27 条规则的去向可以归纳出 eslint-plugin-unicorn 维护者遵循的四条可复用原则避免在规则名中使用缩写no-fn-reference-in-iterator更名为no-array-callback-reference因为fn过于晦涩规则名必须精确表达作用对象no-reduce→no-array-reduce、prefer-flat-map→prefer-array-flat-map、prefer-event-key→prefer-keyboard-event-key统一采用对象类型 动作的命名结构消除歧义、拒绝误导prefer-node-append/prefer-node-remove易被误解为 Node.js 相关因此加上dom-前缀明确指向 DOM API与 ESLint 核心能力去重一旦 ESLint 内置规则覆盖如prefer-exponentiation-operator、prefer-object-has-own插件即移除对应规则避免重复维护。总结9 条废弃规则仍然注册但为 no-op18 条已删除规则彻底失效两者的完整映射均记录于 docs/deleted-and-deprecated-rules.md废弃机制的源码实现在 rules/utils/create-deprecated-rules.js通过空create函数与meta.deprecated.replacedBy实现空转 引导迁移迁移时先搜索旧名称再对照本文映射表替换最后检查新规则的选项差异并运行npx eslint .验证这些演进记录不仅是迁移手册更是理解如何给 ESLint 规则命名的最佳实践样本。【免费下载链接】eslint-plugin-unicornMore than 300 powerful ESLint rules项目地址: https://gitcode.com/GitHub_Trending/es/eslint-plugin-unicorn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
