RuboCop v0.67.1 版本解析Naming/RescuedExceptionsVariableName默认异常变量名统一为e【免费下载链接】rubocopA Ruby static code analyzer and formatter, based on the community Ruby style guide.项目地址: https://gitcode.com/GitHub_Trending/rub/rubocopRuboCop v0.67.1 是一个小版本补丁发布唯一的变更点是将命名类 CopNaming/RescuedExceptionsVariableName的默认配置项PreferredName设置为e从而使 rescued 异常变量的默认命名约定与社区 Ruby 风格指南保持一致。本文以该变更为主线结合仓库源码config/default.yml与 Cop 实现lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb深入解析该 Cop 的工作原理、配置方式与自动修正边界帮助读者理解并驾驭这条开箱即用的异常变量命名规则。一、变更背景v0.67.1 在 v0.67.0 之上的定位Naming/RescuedExceptionsVariableNameCop 诞生于 v0.67.0见 config/default.yml 的VersionAdded: 0.67用于统一rescue块中异常变量的命名。v0.67.1 随即做了一次默认值收敛把PreferredName的默认值从代码兜底的实现约定显式写进默认配置统一为e。这次变更对应 relnotes/v0.67.1.md 中记录的唯一一条 ChangesSet defaultPreferredNametoeforNaming/RescuedExceptionsVariableName.在 config/default.yml 中可以看到该 Cop 的完整默认配置Naming/RescuedExceptionsVariableName: Description: Use consistent rescued exceptions variables naming. Enabled: true VersionAdded: 0.67 VersionChanged: 0.68 PreferredName: e几个关键字段的含义Enabled: true该 Cop 在默认配置下即处于启用状态无需手动开启VersionAdded: 0.67引入该 Cop 的版本VersionChanged: 0.68默认值在后续版本中仍有演进该字段反映了配置默认值最近一次变化的版本PreferredName: ev0.67.1 起确立的默认期望变量名。二、Cop 功能速览它检查什么、何时生效Naming/RescuedExceptionsVariableName的核心职责是确保rescue子句中绑定的异常变量使用预期的名字。它在 lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb 中实现注册于Naming部门并继承自RuboCop::Cop::Base同时extend AutoCorrector说明它支持自动修正Always。以下代码摘自 docs/modules/ROOT/pages/cops_naming.adoc 中的 Cop 元信息表属性值默认启用是Enabled安全性安全Safe自动修正始终支持Always引入版本0.67最近变更版本0.68检查范围该 Cop 同时覆盖两种 rescue 写法显式指定异常类型rescue MyException exc隐式 rescue不指定异常类型rescue error以及带*展开的异常列表rescue *handled exc。无论哪种写法只要绑定了异常变量其命名就会被检查而形如rescue MyException未绑定变量或rescue完全隐式的写法不受影响。三、默认命名约定e与下划线前缀的兼容在默认PreferredName: e下该 Cop 接受两种写法# good begin # do something rescue MyException e # do something end # good begin # do something rescue MyException _e # do something end对应地exception、exc、error、e1等写法会被判为违规# bad begin # do something rescue MyException exception # do something end下划线前缀的巧妙处理从源码看Cop 对带下划线前缀的变量做了特殊处理。在 lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb 的preferred_name方法中def preferred_name(variable_name) preferred_name cop_config.fetch(PreferredName, e) if variable_name.to_s.start_with?(_) _#{preferred_name} else preferred_name end end即如果当前变量名以下划线开头如_exc期望名会保留下划线前缀变成_e否则使用PreferredName的原始值。这样既尊重未使用变量加下划线的 Ruby 惯例又不破坏命名一致性。在 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb 中_exc会被报告为Use_einstead of_exc.并自动修正为_e。四、配置指南自定义PreferredNamePreferredName接受任意合法变量名字符串。若团队约定使用exception可在项目的.rubocop.yml中覆盖Naming/RescuedExceptionsVariableName: PreferredName: exception配置后e反成为违规写法而exception与_exception均为合法示例同样来自 docs/modules/ROOT/pages/cops_naming.adoc# bad begin # do something rescue MyException e # do something end # good begin # do something rescue MyException exception # do something end配置项的完整定义见 config/default.yml默认值为e可配置值为任意字符串文档中以String类型标注见 cops_naming.adoc 的 Configurable attributes 表。从源码看PreferredName是通过cop_config.fetch(PreferredName, e)读取的因此即使配置文件中缺省该项也会回退到e——这正是 v0.67.1 将默认值显式写入 config/default.yml 的意义所在。五、源码级原理从 AST 节点到自动修正理解该 Cop 的实现细节有助于预判它在真实代码中的行为边界。核心逻辑集中在on_resbody回调lib/rubocop/cop/naming/rescued_exceptions_variable_name.rbdef on_resbody(node) offending_name variable_name(node) return unless offending_name # Handle nested rescues by only requiring the outer one to use the # configured variable name, so that nested rescues dont use the same # variable. return if node.each_ancestor(:resbody).any? preferred_name preferred_name(offending_name) return if preferred_name.to_sym offending_name # check variable shadowing for exception variable return if shadowed_variable_name?(node) ... end关键判定依次为获取违规名通过node.exception_variable.name读取resbody节点绑定的异常变量名若 rescue 未绑定变量respond_to?(:name)为假直接返回。嵌套 rescue 豁免node.each_ancestor(:resbody).any?检查当前节点是否位于外层 rescue 之内。若存在嵌套则只要求最外层 rescue 使用配置名内层保持不变。原因在 Cop 注释中有明确说明源码 L12-L15无法保证外层异常变量在内层未被使用贸然改名内层变量会遮蔽外层变量。对应测试见 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb外层e1被修正为e内层e2保持不变。命名已合规若期望名与当前名一致跳过。变量遮蔽检查shadowed_variable_name?遍历节点后代中的lvar若PreferredName对应的名字已在 rescue 块内被其他变量占用例如外层已有e error message则不报告避免自动修正引发遮蔽问题对应测试见 spec。自动修正的引用替换与重赋值保护自动修正在 autocorrect 中完成先把异常变量本身替换为期望名再通过correct_node遍历 rescue 体乃至begin之后的兄弟节点把所有对该异常变量的引用一并改名。这里有两条重要的边界逻辑重赋值即停一旦遇到lvasgn/masgn对异常变量的重新赋值修正器只修正重赋值右侧对该异常变量的引用之后对同名变量的引用不再改动。因为重赋值之后该名字已经指向一个不同的值如error { error_message: error.message }后再puts error其中error是局部哈希变量而非异常。相关用例见 spec。hash value omission 兼容对于 Ruby 3.1 的省略值哈希写法do_something(error:)源码在 L128-L134 通过value_omission?检测并改写为do_something(error: e)对应测试见 spec。多分支与 rescue 后的引用同一begin的多个rescue分支会各自独立报告并修正foo、bar都会被改为e见 spec变量在begin/rescue语句结束之后仍被引用时修正器也会通过kwbegin_node.right_siblings继续处理这些后续引用见 L102-L106 与 spec。六、运行与验证在 v0.67.1 及之后版本中该 Cop 默认即生效可直接用 CLI 验证# 检查违规 rubocop --only Naming/RescuedExceptionsVariableName path/to/file.rb # 自动修正 rubocop --only Naming/RescuedExceptionsVariableName -A path/to/file.rb生成违规报告时的消息格式为Use% sinstead of% s.定义于 源码 L64例如默认配置下rescue error会被报告为Useeinstead oferror.并可通过-A直接完成全量改名。若要临时豁免可在行内使用# rubocop:disable Naming/RescuedExceptionsVariableName指令或在.rubocop.yml中Exclude相应路径——不过对于这条安全的命名规则更推荐直接依赖其自动修正能力保持全仓库命名统一。七、小结与适用前提v0.67.1 的这次变更虽小却意义明确它把Naming/RescuedExceptionsVariableName的期望命名从实现细节固化为默认配置事实让所有升级到该版本的项目开箱即用地获得e这一社区惯用命名。使用时需注意两点前提该 Cop 的安全修正基于对 AST 的精确分析遇到重赋值、嵌套 rescue、变量遮蔽等场景会谨慎跳过或部分修正这是刻意为之的正确行为不建议通过关闭 Cop 来规避若团队已有自己的异常变量命名习惯如全量使用exception请在.rubocop.yml中显式配置PreferredName并注意该配置项的默认值在后续版本中仍可能调整VersionChanged字段已标注为 0.68。对Naming/RescuedExceptionsVariableName的完整行为矩阵含各类边界用例可进一步研读其测试套件 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb其中覆盖了显式/隐式 rescue、下划线前缀、多分支、嵌套、重赋值、writer 方法赋值等全部场景。【免费下载链接】rubocopA Ruby static code analyzer and formatter, based on the community Ruby style guide.项目地址: https://gitcode.com/GitHub_Trending/rub/rubocop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
RuboCop v0.67.1 版本解析：`Naming/RescuedExceptionsVariableName` 默认异常变量名统一为 `e`
RuboCop v0.67.1 版本解析Naming/RescuedExceptionsVariableName默认异常变量名统一为e【免费下载链接】rubocopA Ruby static code analyzer and formatter, based on the community Ruby style guide.项目地址: https://gitcode.com/GitHub_Trending/rub/rubocopRuboCop v0.67.1 是一个小版本补丁发布唯一的变更点是将命名类 CopNaming/RescuedExceptionsVariableName的默认配置项PreferredName设置为e从而使 rescued 异常变量的默认命名约定与社区 Ruby 风格指南保持一致。本文以该变更为主线结合仓库源码config/default.yml与 Cop 实现lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb深入解析该 Cop 的工作原理、配置方式与自动修正边界帮助读者理解并驾驭这条开箱即用的异常变量命名规则。一、变更背景v0.67.1 在 v0.67.0 之上的定位Naming/RescuedExceptionsVariableNameCop 诞生于 v0.67.0见 config/default.yml 的VersionAdded: 0.67用于统一rescue块中异常变量的命名。v0.67.1 随即做了一次默认值收敛把PreferredName的默认值从代码兜底的实现约定显式写进默认配置统一为e。这次变更对应 relnotes/v0.67.1.md 中记录的唯一一条 ChangesSet defaultPreferredNametoeforNaming/RescuedExceptionsVariableName.在 config/default.yml 中可以看到该 Cop 的完整默认配置Naming/RescuedExceptionsVariableName: Description: Use consistent rescued exceptions variables naming. Enabled: true VersionAdded: 0.67 VersionChanged: 0.68 PreferredName: e几个关键字段的含义Enabled: true该 Cop 在默认配置下即处于启用状态无需手动开启VersionAdded: 0.67引入该 Cop 的版本VersionChanged: 0.68默认值在后续版本中仍有演进该字段反映了配置默认值最近一次变化的版本PreferredName: ev0.67.1 起确立的默认期望变量名。二、Cop 功能速览它检查什么、何时生效Naming/RescuedExceptionsVariableName的核心职责是确保rescue子句中绑定的异常变量使用预期的名字。它在 lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb 中实现注册于Naming部门并继承自RuboCop::Cop::Base同时extend AutoCorrector说明它支持自动修正Always。以下代码摘自 docs/modules/ROOT/pages/cops_naming.adoc 中的 Cop 元信息表属性值默认启用是Enabled安全性安全Safe自动修正始终支持Always引入版本0.67最近变更版本0.68检查范围该 Cop 同时覆盖两种 rescue 写法显式指定异常类型rescue MyException exc隐式 rescue不指定异常类型rescue error以及带*展开的异常列表rescue *handled exc。无论哪种写法只要绑定了异常变量其命名就会被检查而形如rescue MyException未绑定变量或rescue完全隐式的写法不受影响。三、默认命名约定e与下划线前缀的兼容在默认PreferredName: e下该 Cop 接受两种写法# good begin # do something rescue MyException e # do something end # good begin # do something rescue MyException _e # do something end对应地exception、exc、error、e1等写法会被判为违规# bad begin # do something rescue MyException exception # do something end下划线前缀的巧妙处理从源码看Cop 对带下划线前缀的变量做了特殊处理。在 lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb 的preferred_name方法中def preferred_name(variable_name) preferred_name cop_config.fetch(PreferredName, e) if variable_name.to_s.start_with?(_) _#{preferred_name} else preferred_name end end即如果当前变量名以下划线开头如_exc期望名会保留下划线前缀变成_e否则使用PreferredName的原始值。这样既尊重未使用变量加下划线的 Ruby 惯例又不破坏命名一致性。在 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb 中_exc会被报告为Use_einstead of_exc.并自动修正为_e。四、配置指南自定义PreferredNamePreferredName接受任意合法变量名字符串。若团队约定使用exception可在项目的.rubocop.yml中覆盖Naming/RescuedExceptionsVariableName: PreferredName: exception配置后e反成为违规写法而exception与_exception均为合法示例同样来自 docs/modules/ROOT/pages/cops_naming.adoc# bad begin # do something rescue MyException e # do something end # good begin # do something rescue MyException exception # do something end配置项的完整定义见 config/default.yml默认值为e可配置值为任意字符串文档中以String类型标注见 cops_naming.adoc 的 Configurable attributes 表。从源码看PreferredName是通过cop_config.fetch(PreferredName, e)读取的因此即使配置文件中缺省该项也会回退到e——这正是 v0.67.1 将默认值显式写入 config/default.yml 的意义所在。五、源码级原理从 AST 节点到自动修正理解该 Cop 的实现细节有助于预判它在真实代码中的行为边界。核心逻辑集中在on_resbody回调lib/rubocop/cop/naming/rescued_exceptions_variable_name.rbdef on_resbody(node) offending_name variable_name(node) return unless offending_name # Handle nested rescues by only requiring the outer one to use the # configured variable name, so that nested rescues dont use the same # variable. return if node.each_ancestor(:resbody).any? preferred_name preferred_name(offending_name) return if preferred_name.to_sym offending_name # check variable shadowing for exception variable return if shadowed_variable_name?(node) ... end关键判定依次为获取违规名通过node.exception_variable.name读取resbody节点绑定的异常变量名若 rescue 未绑定变量respond_to?(:name)为假直接返回。嵌套 rescue 豁免node.each_ancestor(:resbody).any?检查当前节点是否位于外层 rescue 之内。若存在嵌套则只要求最外层 rescue 使用配置名内层保持不变。原因在 Cop 注释中有明确说明源码 L12-L15无法保证外层异常变量在内层未被使用贸然改名内层变量会遮蔽外层变量。对应测试见 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb外层e1被修正为e内层e2保持不变。命名已合规若期望名与当前名一致跳过。变量遮蔽检查shadowed_variable_name?遍历节点后代中的lvar若PreferredName对应的名字已在 rescue 块内被其他变量占用例如外层已有e error message则不报告避免自动修正引发遮蔽问题对应测试见 spec。自动修正的引用替换与重赋值保护自动修正在 autocorrect 中完成先把异常变量本身替换为期望名再通过correct_node遍历 rescue 体乃至begin之后的兄弟节点把所有对该异常变量的引用一并改名。这里有两条重要的边界逻辑重赋值即停一旦遇到lvasgn/masgn对异常变量的重新赋值修正器只修正重赋值右侧对该异常变量的引用之后对同名变量的引用不再改动。因为重赋值之后该名字已经指向一个不同的值如error { error_message: error.message }后再puts error其中error是局部哈希变量而非异常。相关用例见 spec。hash value omission 兼容对于 Ruby 3.1 的省略值哈希写法do_something(error:)源码在 L128-L134 通过value_omission?检测并改写为do_something(error: e)对应测试见 spec。多分支与 rescue 后的引用同一begin的多个rescue分支会各自独立报告并修正foo、bar都会被改为e见 spec变量在begin/rescue语句结束之后仍被引用时修正器也会通过kwbegin_node.right_siblings继续处理这些后续引用见 L102-L106 与 spec。六、运行与验证在 v0.67.1 及之后版本中该 Cop 默认即生效可直接用 CLI 验证# 检查违规 rubocop --only Naming/RescuedExceptionsVariableName path/to/file.rb # 自动修正 rubocop --only Naming/RescuedExceptionsVariableName -A path/to/file.rb生成违规报告时的消息格式为Use% sinstead of% s.定义于 源码 L64例如默认配置下rescue error会被报告为Useeinstead oferror.并可通过-A直接完成全量改名。若要临时豁免可在行内使用# rubocop:disable Naming/RescuedExceptionsVariableName指令或在.rubocop.yml中Exclude相应路径——不过对于这条安全的命名规则更推荐直接依赖其自动修正能力保持全仓库命名统一。七、小结与适用前提v0.67.1 的这次变更虽小却意义明确它把Naming/RescuedExceptionsVariableName的期望命名从实现细节固化为默认配置事实让所有升级到该版本的项目开箱即用地获得e这一社区惯用命名。使用时需注意两点前提该 Cop 的安全修正基于对 AST 的精确分析遇到重赋值、嵌套 rescue、变量遮蔽等场景会谨慎跳过或部分修正这是刻意为之的正确行为不建议通过关闭 Cop 来规避若团队已有自己的异常变量命名习惯如全量使用exception请在.rubocop.yml中显式配置PreferredName并注意该配置项的默认值在后续版本中仍可能调整VersionChanged字段已标注为 0.68。对Naming/RescuedExceptionsVariableName的完整行为矩阵含各类边界用例可进一步研读其测试套件 spec/rubocop/cop/naming/rescued_exceptions_variable_name_spec.rb其中覆盖了显式/隐式 rescue、下划线前缀、多分支、嵌套、重赋值、writer 方法赋值等全部场景。【免费下载链接】rubocopA Ruby static code analyzer and formatter, based on the community Ruby style guide.项目地址: https://gitcode.com/GitHub_Trending/rub/rubocop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
