rubocop

RuboCop 代码分析与格式化

RuboCop 是 Ruby 领域首屈一指的静态代码分析器（linter）和格式化工具，基于社区驱动的 Ruby 风格指南。此技能可对 Ruby 项目（包括 Rails 应用）进行全面的代码分析、自动格式化并强制执行编码标准。

何时使用此技能

当用户：

• 要求“检查”“lint”“分析”或“审查” Ruby 代码
• 请求代码格式化或风格改进
• 希望强制执行编码标准或风格指南
• 需要检测潜在错误或代码异味
• 询问 RuboCop 配置或设置
• 请求针对 Rails、RSpec 或性能的专项分析
• 希望对 Ruby 代码运行自动修正

Claude 会自动使用此技能。

核心功能

代码分析与 Lint

• 检测所有 cop 类别中的风格违规、错误和代码异味
• 支持 Rails、RSpec、Performance 和自定义 cop 扩展
• 提供详细的问题报告，包含行号和说明

自动代码修正

• 安全自动修正（-a），用于确保安全的修复
• 非安全自动修正（-A），覆盖范围更广但风险更高
• 仅修复布局（-x），仅调整格式，不更改逻辑

配置与自定义

• 灵活的 .rubocop.yml 配置
• 按项目和目录继承配置
• 选择性启用/禁用 cop 并调整严重级别
• 支持开发自定义 cop

扩展集成

• rubocop-rails：Rails 最佳实践与约定
• rubocop-rspec：RSpec 专项分析
• rubocop-performance：性能优化检查

快速分析工作流

运行基本分析

# Analyze current directory
rubocop

# Analyze specific files/directories
rubocop app spec lib/important_file.rb

# Show only correctable offenses
rubocop --display-only-correctable

应用修正

# Safe autocorrection only (recommended)
rubocop -a

# All corrections including unsafe
rubocop -A

# Layout/formatting corrections only
rubocop -x

# Autocorrect specific cops
rubocop -a --only Style/StringLiterals,Layout/TrailingWhitespace

定向分析

# Run only specific cops
rubocop --only Style/StringLiterals,Naming/MethodName

# Run all cops except specified
rubocop --except Metrics/MethodLength

# Run only lint cops
rubocop --lint

# Check only Rails-specific issues
rubocop --only Rails

配置要点

基本的 .rubocop.yml 设置

# Enable extensions
plugins:
  - rubocop-rails
  - rubocop-rspec
  - rubocop-performance

AllCops:
  TargetRubyVersion: 3.2
  NewCops: enable  # Auto-enable new cops
  Exclude:
    - 'db/schema.rb'
    - 'vendor/**/*'
    - 'node_modules/**/*'

# Adjust specific cops
Style/StringLiterals:
  EnforcedStyle: double_quotes

Metrics/MethodLength:
  Max: 15
  Exclude:
    - 'spec/**/*'

常见配置模式

继承共享配置：

inherit_from:
  - .rubocop_todo.yml
  - config/rubocop_defaults.yml

Rails 专项设置：

Rails:
  Enabled: true

Rails/ApplicationRecord:
  Enabled: true
  Exclude:
    - 'db/migrate/**'

RSpec 配置：

RSpec/ExampleLength:
  Max: 10

RSpec/MultipleExpectations:
  Max: 3

分析结果解读

理解问题输出

app/models/user.rb:15:3: C: Style/StringLiterals: Prefer single-quoted strings...
  name = "John Doe"
         ^^^^^^^^^^

格式说明：

• app/models/user.rb:15:3 - 文件路径、行号、列号
• C: - 严重级别（C=约定，W=警告，E=错误，F=致命错误）
• Style/StringLiterals - Cop 类别和名称
• 消息会说明问题，并通常会给出修复建议

严重级别

• Convention (C)：风格/格式问题
• Warning (W)：应当检查的潜在问题
• Error (E)：需要修复的明确问题
• Fatal (F)：导致无法进行分析的语法错误

常见工作流

项目初始设置

# Generate initial configuration
rubocop --init

# Generate .rubocop_todo.yml for existing violations
rubocop --auto-gen-config

# Use todo file to gradually fix issues
# .rubocop.yml:
inherit_from: .rubocop_todo.yml

提交前集成

# Check staged files only
git diff --name-only --cached | grep '\.rb$' | xargs rubocop

# With autocorrection
git diff --name-only --cached | grep '\.rb$' | xargs rubocop -a

CI/CD 集成

# Exit with error code if offenses found
rubocop --format progress --fail-level warning

# Generate formatted reports
rubocop --format json --out rubocop-report.json
rubocop --format html --out rubocop-report.html

并行执行

# Use all available CPUs (enabled by default)
rubocop --parallel

# Limit CPU usage
PARALLEL_PROCESSOR_COUNT=2 rubocop

扩展专项功能

Rails 分析

检测 Rails 专项问题：

• ActiveRecord 最佳实践
• 控制器和路由约定
• 迁移安全检查
• SQL 注入风险

RSpec 分析

强制执行 RSpec 最佳实践：

• 示例的组织与命名
• let 与实例变量的使用
• 期望模式
• 测试文件结构

性能分析

识别性能优化机会：

• 效率低下的集合方法
• 字符串拼接问题
• 不必要的数组分配
• 正则表达式编译优化

故障排除

“Unknown cop” 错误：

• 确保已安装所需的 gem（rubocop-rails、rubocop-rspec 等）
• 在 .rubocop.yml 中添加：plugins: [rubocop-rails]

自动修正不起作用：

• 某些 cop 不支持自动修正
• 使用 -A 进行非安全修正
• 检查配置中是否已启用该 cop

性能问题：

• 使用 --parallel 加快执行速度
• 在配置中的 AllCops 下添加 UseCache: true
• 排除大型生成文件

其他资源

• 配置指南 - 全面的配置参考
• Cop 参考 - 所有 cop 部门及其职责
• 扩展指南 - Rails、RSpec 和 Performance 扩展详情
• 自动更正指南 - 安全与不安全更正说明
• 自定义 Cop 指南 - 为项目创建自定义 cop