eslint-plugin-react 的 boolean-prop-naming 规则:统一布尔 Props 命名规范实战指南

原创2026-09-24 16:34:031,843 阅读
文章标签:开发工具代码质量静态分析

eslint-plugin-react 的 boolean-prop-naming 规则:统一布尔 Props 命名规范实战指南

react/boolean-prop-naming 是 eslint-plugin-react 提供的一条样式类(Stylistic Issues)规则,用于强制组件中期望接收布尔值(boolean)的 props 采用一致的命名模式。无论你用 PropTypes、TypeScript 还是 Flow 来定义组件 props,本规则都能基于类型信息自动识别出"布尔型 props",并校验它们的命名是否满足你约定的正则模式(默认要求以 is 或 has 开头)。阅读完本文,你将掌握该规则的完整配置参数(propTypeNames、rule、message、validateNested)、正确的开启方式,并能理解它在 规则源码 层面的检测原理与边界行为。

规则概览:做什么、不做什么

该规则的核心逻辑很简单:遍历组件声明的所有 props,找出其中类型为"布尔"的 prop,然后用你给定的正则表达式测试它的名字,不匹配即报告错误。

需要特别强调的是,本规则的"布尔类型识别"是跨类型系统的:

  • 运行时 PropTypes:如 PropTypes.bool、React.PropTypes.bool,以及直接引入的 bool 标识符;
  • TypeScript 静态类型:如 enabled: boolean、type Props = {...}、interface、交叉类型与联合类型;
  • Flow 静态类型:如 enabled: boolean、ObjectTypeAnnotation。

如 规则文档 的 Note 所说明,规则会"无论你如何定义 props 都进行校验",因此你不需要额外切换配置,同一份规则即可同时覆盖三种写法混用的项目。

不符合规则的代码(Incorrect)

使用 createReactClass + PropTypes 定义布尔 prop 却未遵循命名模式:

var Hello = createReactClass({
  propTypes: {
    enabled: PropTypes.bool
  },
  render: function() { return <div />; };
});

使用 Flow 类型定义布尔 prop:

type Props = {
  enabled: boolean
}
const Hello = (props: Props) => <div />;

符合规则的代码(Correct)

var Hello = createReactClass({
  propTypes: {
    isEnabled: PropTypes.bool
  },
  render: function() { return <div />; };
});
type Props = {
  isEnabled: boolean
}
const Hello = (props: Props) => <div />

注意:在默认规则 ^(is|has)A-Z+ 下,enabled 因为缺少 is 前缀而被标记;而 isEnabled 完全匹配。非布尔类型的 props(如 PropTypes.string、PropTypes.any)不受此规则约束,测试用例中大量使用 something: PropTypes.any 作为合法示例即可佐证这一点(见 测试文件 中 // ES6 components with non-boolean PropTypes 等用例)。

如何开启该规则

该规则默认不启用——在 规则源码 的 meta.docs 中 recommended: false,因此它不会出现在 react/recommended 预设里,需要手动在 ESLint 配置中开启:

// .eslintrc 传统配置
{
  "plugins": ["react"],
  "rules": {
    "react/boolean-prop-naming": ["error", {
      "propTypeNames": ["bool"],
      "rule": "^(is|has)A-Z+",
      "message": "",
      "validateNested": false
    }]
  }
}

所有规则统一在 规则注册表 中注册,插件通过 lib/rules/boolean-prop-naming.js 导出。开启后,任何不匹配的布尔 prop 都会触发如下默认错误消息:

Prop name `enabled` doesn't match rule `^(is|has)A-Z+`

这条默认消息定义在 源码 messages 表 中(patternMismatch 消息 ID),消息文本使用 ESLint 的 {{ 占位符 }} 模板插值机制渲染。

规则选项详解

完整选项结构如下(来自 文档 与 JSON Schema 定义):

...
"react/boolean-prop-naming": [<enabled>, {
  "propTypeNames": Array<string>,
  "rule": <string>,
  "message": <string>,
  "validateNested": <boolean>
}]
...

从 Schema 可以确认以下约束与默认值:

选项 类型 默认值 Schema 约束
propTypeNames Array<string> ['bool'] 至少 1 项(minItems: 1),且不能重复(uniqueItems: true)
rule string `'^(is has)A-Z+'`
message string 默认错误消息 至少 1 个字符(minLength: 1)
validateNested boolean false —

其余未列出的属性一律被 additionalProperties: false 拒绝,配置时需注意不要拼错键名。

propTypeNames:声明哪些类型算"布尔"

默认情况下,规则只把 PropTypes 中的 bool 视为布尔类型。但实际项目中常有自定义的布尔语义类型,例如 airbnb-prop-types 的 mutuallyExclusiveTrueProps(一组互斥的布尔 props)。你可以扩展名单:

"react/boolean-prop-naming": ["error", { "propTypeNames": ["bool", "mutuallyExclusiveTrueProps"] }]

源码层面,配置读取逻辑为 const propTypeNames = config.propTypeNames || <a href="https://link.gitcode.com/i/a5d72cdf1d40c087c3b72e665b694d44" target="_blank">'bool'];(见 [lib/rules/boolean-prop-naming.js),随后在 regularCheck 中通过 propTypeNames.indexOf(propKey) >= 0 判断某个 prop 的类型名是否在名单内。

值得注意的实现细节:这里匹配的是类型标识符名,因此 PropTypes 的多种写法都能命中:

  • PropTypes.bool(成员表达式,取 .property.name)
  • React.PropTypes.bool
  • 直接引入的 bool(如 import { bool } from 'prop-types',属 Identifier 节点)
  • PropTypes.bool.isRequired(会跳过 isRequired 再取 bool)

以上各种写法分别由 getPropKey 的不同分支处理(源码 L102-L123),测试用例 // Custom PropTypes that are specified as variables 也验证了直接写 mutuallyExclusiveTrueProps、bool 标识符的场景。

rule:布尔 props 的命名正则

默认模式为 "^(is|has)A-Z+",即要求布尔 prop 以 is 或 has 开头,且紧跟一个大写字母。文档给出的合法示例:

  • isEnabled
  • isAFK
  • hasCondition
  • hasLOL

其中 isAFK、hasLOL 这类全大写缩写也能通过,因为模式允许大写字母与数字任意组合([A-Za-z0-9])。

显式声明默认规则:

"react/boolean-prop-naming": "error", { "rule": "^(is|has)[A-Z+" }]

如果只想强制 is 前缀(例如团队约定只用 is 不用 has):

"react/boolean-prop-naming": "error", { "rule": "^is[A-Z+" }]

此时仅以下形式合法:

  • isEnabled
  • isAFK

源码中 const rule = config.rule ? new RegExp(config.rule) : null;(L85),将配置字符串编译为正则后,在三种检查函数(flowCheck / regularCheck / tsCheck)里统一用 rule.test(propName) === false 判定"不匹配"。另外注意:未配置 rule 时,rule 为 null,规则会直接跳过所有检查(多处 if (!rule) return; 守卫),因此该规则几乎总是需要显式提供 rule 才有意义。

你也可以在正则中加入例外名单,比如测试用例中出现的 (^(is|has|should|without)A-Z+|disabled|required|checked|defaultChecked)——这种写法把 HTML 原生布尔属性名直接列为可接受项。

message:自定义报错文案

默认消息不够友好时,可以自定义提示。自定义消息支持两个模板变量:

  • propName – 未通过模式校验的 prop 名
  • pattern – 实际用于校验的正则模式

例如 prop 名为 something、模式为 "^(is|has)A-Z+" 时:

message: 'It is better if your prop ({{ propName }}) matches this pattern: ({{ pattern }})'

实际报错渲染为:

It is better if your prop (something) matches this pattern: (^isA-Z+)

注意:报错中渲染的 {{ pattern }} 始终是你实际配置的 rule 字符串。上述示例中的 ^is[A-Z]... 是文档为演示模板变量而展示的取值,实际项目中它会原样输出你在 rule 中填写的正则。

源码中消息渲染走 report 工具 + message 工具:当未提供自定义 message 时使用 messages.patternMismatch 的消息 ID(便于在 ESLint ≥ 4.15 下使用 messageId 机制做多语言/程序化处理);提供了自定义消息时,则以 config.message 优先,模板变量 propName、pattern、component 通过 data 注入(L219-L231)。

validateNested:是否校验嵌套布尔 props

布尔 props 可能藏在对象型 props 的内部,例如 PropTypes.shape({...})。默认 validateNested: false,此时只校验顶层布尔 props,shape 内部的布尔 props 不会被检查。开启后则递归下钻校验深层:

"react/boolean-prop-naming": ["error", { "validateNested": true }]

开启后,如下代码中的 failingItIs(shape 内部、未遵循 is 前缀)也会被报告:

class Hello extends React.Component {
  render() {
    return (
      <div />
    );
  }
}

Hello.propTypes = {
  isSomething: PropTypes.bool.isRequired,
  nested: PropTypes.shape({
    failingItIs: PropTypes.bool
  })
};

源码中通过 nestedPropTypes 判断"当前 prop 的值是函数调用(如 PropTypes.shape({...}))",满足条件且 config.validateNested 为真时,对 prop.value.arguments<a href="https://link.gitcode.com/i/d5e481a9709603d6c958c613f831942f" target="_blank">0].properties 递归执行 runCheck([L27-L32 与 L183-L195)。递归是深度优先的,因此多层 shape 嵌套也能逐层穿透(测试用例中就有两层 nested: PropTypes.shape({ nested: PropTypes.shape({...}) }) 的验证)。

源码级原理:规则是如何检测的

理解规则的工作流有助于排查"为什么没报错"类问题。整体流程可分为三个阶段:

阶段一:定位 propTypes 声明

规则注册了多个 AST 访问器来捕获不同写法的 propTypes 声明:

  • ClassProperty / PropertyDefinition:处理 static propTypes = {...}、Flow 的 props: {...} 类属性(L311-L331);
  • MemberExpression:处理 Hello.propTypes = {...} 的赋值语句(L333-L353);
  • ObjectExpression:处理 createReactClass({ propTypes: {...} }) 这类对象字面量写法(L355-L367)。

其中"这是不是 propTypes 声明"的判断由 props 工具 的 isPropTypesDeclaration 完成:Flow 下识别键名为 props 的类属性,其余情况识别属性名是否为 propTypes。

阶段二:识别布尔类型并匹配正则

对收集到的每个 prop 属性节点,依次执行三种类型检查,任一命中即视为"布尔 prop":

检查函数 适用场景 判定条件
flowCheck Flow 节点类型为 ObjectTypeProperty,且值为 BooleanTypeAnnotation
regularCheck PropTypes 提取到的类型标识符在 propTypeNames 名单内
tsCheck TypeScript 节点类型为 TSPropertySignature,且类型注解为 TSBooleanKeyword

三者任一满足且 rule.test(propName) === false(即命名不匹配)时,该 prop 进入 invalidProps 列表(L146-L176)。非布尔类型(如 PropTypes.any、string、number 等)在此阶段被自然过滤,这也是规则不会误伤普通 props 的原因。

阶段三:汇总并报告

规则在 Program:exit(程序退出时)统一遍历所有已收集组件,执行 reportInvalidNaming 一次性输出所有违规(L382-L423)。这种"先收集、后报告"的设计允许规则先完整解析 TypeScript 类型别名再校验,从而支持更复杂的类型语法。

额外能力一:propWrapperFunctions 支持

如果项目用 merge、Object.assign、_.assign、forbidExtraProps 等包装函数生成 propTypes,只要在 ESLint 的 settings.propWrapperFunctions 中声明这些函数,规则就能"穿透"包装、校验内部的布尔 props:

{
  "settings": {
    "propWrapperFunctions": ["merge", "forbidExtraProps"]
  }
}

源码通过 propWrapper 工具 的 isPropWrapperFunction 判断调用是否为声明的包装函数,命中后对包装参数中的 ObjectExpression 继续执行 validatePropNaming(L233-L238)。对应的测试用例覆盖了 merge、Object.assign、_.assign、forbidExtraProps 四种包装形式,且支持 'Object.assign'、'_.assign' 这类带命名空间的字符串。

额外能力二:TypeScript 高级类型语法

从 测试文件 的用例可以看出,规则对现代 TypeScript 类型语法支持相当完整:

  • 类型别名引用:type Props = {...} + const Hello = (props: Props) => ...;
  • React.FC 泛型:const Hello: React.FC<Props> = (props) => ...;
  • interface:interface TestFNType { enabled: boolean };
  • 交叉类型:type Props = {...} & OtherProps,包括命名类型与内联字面量混合交叉;
  • 联合类型:type Props = {...} | {...},以及交叉中嵌联合 A & (B | C);
  • 内联对象类型:const Hello = (props: { enabled: boolean }) => <div />。

实现上,规则用 objectTypeAnnotations 缓存所有 TypeAlias / TSTypeAliasDeclaration / TSInterfaceDeclaration 的类型体(findAllTypeAnnotations),并在 Program:exit 阶段通过 getComponentTypeAnnotation 定位组件 props 的类型注解,再解析交叉/联合结构递归找出所有属性,最终逐个校验(L240-L304)。

常见边界情况与避坑提示

  1. isRequired 不会导致漏检:PropTypes.bool.isRequired 与普通 PropTypes.bool 一样参与校验。getPropKey 专门处理了 isRequired 成员表达式,先取出 .object.property 的类型名(即 bool)再比对名单(L109-L117)。

  2. 对象展开不会被误检:static propTypes = {isSomething: PropTypes.bool, ...spreadProps} 中展开进来的属性会被跳过。getPropKey 对 ExperimentalSpreadProperty / SpreadElement 节点返回 null,从而不会因取不到 .property 而报错或崩溃(L103-L107)。

  3. shape({}).isRequired 不会误报:当值为 PropTypes.shape({...}).isRequired 时,getPropKey 取到的是 shape 而非 bool,不在 propTypeNames 名单内,因此不会误判(测试用例 // Ensure the rule does not throw when a shape prop isRequired)。

  4. 忘记配置 rule 时规则静默失效:如前述,rule 缺省为 null,所有访问器都会提前 return。如果你发现规则"完全没反应",优先检查是否遗漏了 rule 配置。

  5. validateNested 只对函数调用形式的嵌套生效:嵌套检测依赖 nestedPropTypes(prop 值为函数调用,如 PropTypes.shape({...})),普通对象字面量嵌套不在其检测路径中。

  6. 默认不进入 recommended 预设:需要在配置中显式开启("error" 或 "warn"),它不会随 plugin:react/recommended 自动启用。

测试与验证

该规则拥有非常完整的测试套件(tests/lib/rules/boolean-prop-naming.js,共 1387 行),覆盖 createReactClass、React.createClass、ES6 类(静态/实例 propTypes)、函数组件、Flow、TypeScript(含 Babel/旧 TS 解析器变体)等场景。测试通过 messageId: 'patternMismatch' 与 data: { propName, pattern } 断言错误内容,其中自定义消息用例验证了模板变量插值的实际输出:

It is better if your prop (something) matches this pattern: (^isA-Z+)

若你修改了该规则或自定义了配置,可运行对应测试确认行为符合预期(测试运行器基于 tests/helpers/ruleTester.js)。

小结

react/boolean-prop-naming 是一条"小而精"的命名一致性规则:通过 rule 正则统一布尔 props 的命名模式,借助 propTypeNames 扩展自定义布尔类型,message 定制报错文案,validateNested 下钻校验 shape 嵌套。在源码层面,它以 AST 类型识别(BooleanTypeAnnotation / TSBooleanKeyword / PropTypes 类型名单)而非运行时值来判断"布尔 props",因此能同时服务 PropTypes、TypeScript、Flow 三类用户;配合 propWrapperFunctions 设置,即使 propTypes 经过包装函数处理也能正常校验。建议在团队项目中结合 is / has 前缀约定开启此规则,让布尔 props 从命名上一眼可辨。

登录后查看全文
eslint-plugin-react