ESLint new-cap 规则完全指南强制构造函数命名以大写字母开头【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintnew-cap是 ESLint 内置的一条风格建议型suggestion规则用于强制 JavaScript 构造函数名以大写字母开头同时约束大写的函数只能作为构造函数使用。它帮助团队在执行new调用时一眼识别构造语义避免因命名不规范导致的阅读误判与潜在new遗漏。读完本文你将掌握new-cap的全部 7 个配置项、内置豁免标识符机制、正则例外模式的实际用法以及该规则在 ESLint 源码中的完整判定流程。规则背景为什么构造函数要大写JavaScript 中new操作符会创建一个特定类型对象的新实例而该类型由构造函数表示。构造函数本质上仍是普通函数唯一的区分特征是调用时是否使用了new。原生 JavaScript 函数习惯以大写字母开头以区分哪些函数应作为构造函数使用许多风格指南也建议沿用这一约定从而更容易识别构造调用const friend new Person();new-cap规则正是基于这一命名约定而设计。需要特别说明的是这条规则在 ESLint 中默认为关闭状态recommended: false且不可自动修复、不提供建议fixable: false、hasSuggestions: false属于纯检查型规则这一点可以在 docs/src/_data/rules.json 的规则元数据中确认。规则详情与内置豁免标识符new-cap要求构造函数名以大写字母开头。某些内置标识符不受此规则约束这些内置标识符在源码中定义于CAPS_ALLOWED常量见 lib/rules/new-cap.jsArrayBooleanDateErrorFunctionNumberObjectRegExpStringSymbolBigInt内置标识符豁免的底层实现有两处在newIsCap方向new调用必须大写CAPS_ALLOWED仅作为capIsNew方向的默认豁免而在capIsNew方向大写函数必须配合new源码会将CAPS_ALLOWED无条件并入豁免集合见 lib/rules/new-cap.js。这意味着Boolean(arg)、Object(null)这类以函数方式不带new调用内置构造器的代码是合法的——它们属于类型转换而非构造这一行为在测试用例var x Boolean(42)、var x Date.UTC(2000, 0)中均有覆盖见 tests/lib/rules/new-cap.js。规则默认配置下的正确代码示例/*eslint new-cap: error*/ function foo(arg) { return Boolean(arg); }Boolean(arg)之所以正确是因为Boolean位于内置豁免列表即便没有使用new也不会触发upper报错。选项总览该规则接受一个对象选项完整定义见源码的schema与defaultOptions见 lib/rules/new-cap.js选项类型默认值作用newIsCapbooleantrue要求所有new操作符必须调用大写开头的函数capIsNewbooleantrue要求所有大写开头的函数必须配合new操作符调用newIsCapExceptionsstring[][]允许指定的小写开头函数名配合new调用newIsCapExceptionPatternstring无允许匹配指定正则的小写开头函数名配合new调用capIsNewExceptionsstring[][]允许指定的大写开头函数名不带new调用capIsNewExceptionPatternstring无允许匹配指定正则的大写开头函数名不带new调用propertiesbooleantrue是否检查对象属性如person.acquaintance的大小写从源码看该对象的additionalProperties: false传入未定义的键会直接导致配置校验失败因此配置时务必使用上述精确键名。newIsCapnew调用必须大写默认配置{ newIsCap: true }下new调用小写开头的函数会触发lower消息A constructor name should not start with a lowercase letter.。错误代码/*eslint new-cap: [error, { newIsCap: true }]*/ const friend new person();正确代码/*eslint new-cap: [error, { newIsCap: true }]*/ const friend new Person();当设置为{ newIsCap: false }时规则完全关闭对new调用的大写检查小写构造函数同样合法/*eslint new-cap: [error, { newIsCap: false }]*/ const friend new person();注意newIsCap为false时源码中对应的NewExpression监听器根本不会被注册见 lib/rules/new-cap.js即该方向的检查被整体跳过而不是仅仅放行小写名称。capIsNew大写函数必须配合new默认配置{ capIsNew: true }下以普通调用不带new方式使用大写开头的函数会触发upper消息A function with a name starting with an uppercase letter should only be used as a constructor.。错误代码/*eslint new-cap: [error, { capIsNew: true }]*/ const colleague Person();正确代码/*eslint new-cap: [error, { capIsNew: true }]*/ const colleague new Person();当设置为{ capIsNew: false }时允许大写函数不带new调用/*eslint new-cap: [error, { capIsNew: false }]*/ const colleague Person();对应地capIsNew为false时源码不会注册CallExpression监听器见 lib/rules/new-cap.js。同理capIsNew为false时测试中还放行了bar.Foo(42)、Foo.bar(42)等各类成员调用。newIsCapExceptions放行指定小写构造函数当第三方库或既有代码中存在必须用new调用的小写构造函数时可通过newIsCapExceptions精确放行/*eslint new-cap: [error, { newIsCapExceptions: [events] }]*/ const events require(events); const emitter new events();这里events是 Node.js 模块其构造函数约定为小写命名放行后new events()不再报错。源码将该配置构造为Set以支持 O(1) 查找见 lib/rules/new-cap.js。newIsCapExceptionPattern按正则放行小写构造函数当需要放行的是一类符合模式的名称而非枚举时使用正则表达式。正则会被编译为带u标志的RegExp对象见 lib/rules/new-cap.js匹配目标是调用表达式中 callee 的源码文本。放行person命名空间下的小写构造/*eslint new-cap: [error, { newIsCapExceptionPattern: ^person\\.. }]*/ const friend new person.acquaintance(); const bestFriend new person.friend();放行以.bar结尾的属性/*eslint new-cap: [error, { newIsCapExceptionPattern: \\.bar$ }]*/ const friend new person.bar();注意正则的匹配对象是node.callee的源码文本sourceCode.getText(node.callee)见 lib/rules/new-cap.js因此^person\..匹配的是person.acquaintance这类完整表达式。测试用例newIsCapExceptionPattern: ^foo\\..放行new foo.bar(42)正是这一机制的验证。capIsNewExceptions放行指定大写函数不带new当某些大写开头的函数本身是普通函数而非构造函数时可通过capIsNewExceptions放行其普通调用/*eslint new-cap: [error, { capIsNewExceptions: [Person] }]*/ function foo(arg) { return Person(arg); }源码中capIsNewExceptions会与CAPS_ALLOWED合并构造为集合见 lib/rules/new-cap.js。从测试用例可以看到两个值得注意的细节只放行属性名不够Foo.Bar(42)配合capIsNewExceptions: [Foo]仍然报错必须写全名[Foo.Bar]才能放行见 tests/lib/rules/new-cap.js匹配同时支持集合成员与源码文本两种形式allowedNames.has(calleeName) || allowedNames.has(sourceText)见 lib/rules/new-cap.js。capIsNewExceptionPattern按正则放行大写普通调用放行person命名空间下的大写普通函数/*eslint new-cap: [error, { capIsNewExceptionPattern: ^person\\.. }]*/ const friend person.Acquaintance(); const bestFriend person.Friend();放行以.Bar结尾的属性/*eslint new-cap: [error, { capIsNewExceptionPattern: \\.Bar$ }]*/ foo.Bar();放行以Foo开头的名称注意会同时放行Foo、Foobar以及成员访问Foo.Bar/*eslint new-cap: [error, { capIsNewExceptionPattern: ^Foo }]*/ const x Foo(42); const y Foobar(42); const z Foo.Bar(42);对应测试用例还确认了正则的排他性Bar.Foo(42)配合capIsNewExceptionPattern: ^Foo\\..依然会报upper错误见 tests/lib/rules/new-cap.js说明模式只匹配模式本身描述的形状。properties是否检查对象属性new与调用不仅作用于裸标识符也可能作用于对象属性。默认{ properties: true }会检查属性形式的大小写——即最后一个属性名callee 的最后一段需要遵循大小写约定。错误代码/*eslint new-cap: [error, { properties: true }]*/ const friend new person.acquaintance();正确代码/*eslint new-cap: [error, { properties: true }]*/ const friend new person.Acquaintance();当设置为{ properties: false }时跳过对对象属性的检查/*eslint new-cap: [error, { properties: false }]*/ const friend new person.acquaintance();源码中skipProperties !config.properties当 callee 是MemberExpression且skipProperties为真时直接放行见 lib/rules/new-cap.js。属性名的提取依赖astUtils.getStaticPropertyName该方法支持标识符属性、字符串字面量属性与计算属性名见 lib/rules/utils/ast-utils.js因此new a.b[Constructor]()、new b[\foo]() 等形态也能被正确识别——这些用例都在测试中覆盖见 tests/lib/rules/new-cap.js。源码级判定流程剖析new-cap的检查核心分为名称提取 → 大小写判定 → 豁免判断三步全部集中在 lib/rules/new-cap.js 中这里拆解其实现要点1. 名称提取extractNameFromExpression若 callee 是裸标识符Identifier直接取名字否则通过astUtils.getStaticPropertyName取静态属性名取不到则返回空字符串见 lib/rules/new-cap.js。空名称如new function(){}、new o[1]()这类数字索引不会触发检查。2. 大小写判定getCap取首字符并比较其toLowerCase()与toUpperCase()分为三种状态见 lib/rules/new-cap.jsnon-alpha首字符无大小写变体如_、$、数字、非字母符号不检查lower小写开头配合newIsCap检查upper大写开头配合capIsNew检查。因此new _、new $、new Σ希腊字母 Sigma都是合法代码。同时注意希腊字母 φ 属于小写有对应大写变体new φ会被报为lower错误测试中专门覆盖了这一点见 tests/lib/rules/new-cap.js。3. 豁免判断isCapAllowed依次检查集合成员、正则模式、对象属性开关最后是Date.UTC特例——当 callee 是MemberExpression且属性名为UTC、对象为Date时放行见 lib/rules/new-cap.js。这就是测试中Date.UTC(2000, 0)合法的原因而裸调用UTC()或a.Date.UTC()依然报错见 tests/lib/rules/new-cap.js。4. 报错定位report若 callee 是成员表达式报错位置指向属性段而非整个表达式使错误定位更精准见 lib/rules/new-cap.js。5. 可选链支持规则通过astUtils.skipChainExpression见 lib/rules/utils/ast-utils.js剥开ChainExpression因此foo?.Bar()、new (foo?.bar)()等可选链写法也能被正确检查相关用例需在ecmaVersion: 2020下运行见 tests/lib/rules/new-cap.js。6. 内置对象方法不豁免new toString()、new constructor()、new valueOf()等对象原型方法默认会被报为lower错误必须显式加入newIsCapExceptions才能放行见 tests/lib/rules/new-cap.js这提示团队在使用类 jQuery 风格的小写构造 API 时需要主动配置豁免。配置方式与完整示例在 flat config 中可通过rules字段配置该规则例如在 eslint.config.js 中export default [ { rules: { new-cap: [error, { newIsCap: true, capIsNew: true, newIsCapExceptions: [], newIsCapExceptionPattern: ^person\\., capIsNewExceptions: [Immutable], capIsNewExceptionPattern: \\.Bar$, properties: true }] } } ];在传统.eslintrc风格中则写为{ rules: { new-cap: [error, { newIsCapExceptions: [events] }] } }配置为off可以整体关闭也可仅关闭某一方向例如new-cap: [error, { capIsNew: false }]表示只保留new必须大写这一约束而允许大写函数作为普通函数调用。什么时候不使用它如果你的代码约定不要求构造函数大写或不要求大写函数只能作为构造函数使用请关闭该规则。典型场景包括项目采用小写风格命名的构造函数如某些第三方库或函数式编程风格项目大量依赖必须通过普通调用触发的大写 API此时可先用capIsNew: false或异常模式定向放行而非全局关闭团队已有更严格的命名规范或使用 TypeScript 的new类型约束来保障构造语义。总结new-cap通过newIsCap与capIsNew双向约束配合两个名称集合与两个正则模式的豁免机制以及properties开关为构造函数命名约定提供了细粒度的控制能力。结合源码lib/rules/new-cap.js、内置豁免列表与完整测试tests/lib/rules/new-cap.js来看它正确处理了内置构造器、成员表达式、计算属性名、可选链、非字母开头标识符等边界情况是落实 JavaScript 构造语义命名规范的基础工具之一。若你的风格指南还要求强制使用new括号new Foo()而非new Foo可搭配 new-parens 规则使用。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考