Qodana for Ruby 镜像文档

1. 概述

1.1 简介

Qodana for Ruby 是 JetBrains 推出的静态代码分析工具镜像，专为 Ruby 项目设计。基于 IntelliJ 平台的代码洞察能力，集成 RuboCop 等 Ruby 生态主流分析工具，可自动化检测代码中的语法错误、潜在漏洞、性能问题及代码风格违规，帮助开发团队提升代码质量与可维护性。

1.2 主要用途

• 自动化 Ruby 项目静态代码分析
• 检测代码风格违规（符合 Ruby 社区规范）
• 识别潜在逻辑错误与性能隐患
• 生成标准化代码质量报告
• 集成 CI/CD 流程实现质量门禁

2. 核心功能与特性

2.1 语言与框架支持

• Ruby 版本：支持 2.5 及以上稳定版本
• 框架兼容：原生支持 Ruby on Rails、Sinatra、Hanami 等主流 Ruby 框架
• 依赖管理：自动解析 Gemfile 及 gemspec 依赖关系

2.2 代码分析能力

• 多维度检查：覆盖语法正确性、代码风格（基于 RuboCop）、类型安全（结合 Sorbet/Steep）、性能优化建议
• 自定义规则：支持扩展 RuboCop 规则集，可配置项目专属检查策略
• 增量分析：支持增量扫描（仅分析变更文件），提升 CI 流程效率

2.3 报告与集成

• 多格式报告：生成 HTML、JSON、XML 格式报告，包含问题详情与修复建议
• IDE 集成：报告可直接导入 RubyMine/IntelliJ IDEA，支持一键定位问题代码
• 第三方平台对接：支持导出结果至 SonarQube、GitHub Code Scanning 等平台

3. 使用场景

3.1 本地开发环境

• 开发阶段实时检查代码质量，提交前验证代码合规性
• 快速定位重构风险点，减少技术债务积累

3.2 CI/CD 流程集成

• 作为 PR/合并请求的质量门禁，阻止不合格代码进入主分支
• 自动化生成构建阶段代码质量报告，关联构建编号与提交记录

3.3 团队代码审计

• 定期扫描代码库，生成团队级质量趋势报告
• 识别高频违规模式，针对性优化团队编码规范

4. 使用方法

4.1 前提条件

• 安装 Docker Engine（20.10+）或 Docker Desktop
• 项目根目录存在有效的 Gemfile（或 gemspec）
• 网络环境可访问 Docker Hub（拉取镜像）及 RubyGems（解析依赖）

4.2 基本使用（docker run）

通过以下命令启动基础代码分析：

bash
docker run --rm -it \
  -v $(pwd):/data/project \  # 挂载本地项目目录至容器
  -p 8080:8080 \             # 映射报告查看端口
  jetbrains/qodana-ruby:latest

参数说明：

• -v $(pwd):/data/project：必须项，将本地项目目录挂载到容器内分析路径
• -p 8080:8080：可选，映射容器内报告服务端口（默认 8080）
• jetbrains/qodana-ruby:latest：默认使用最新稳定版镜像（指定版本可替换 latest 为标签，如 2023.3）

4.3 Docker Compose 配置

创建 docker-compose.yml 简化本地部署：

yaml
version: '3.8'
services:
  qodana:
    image: jetbrains/qodana-ruby:latest
    volumes:
      - ./:/data/project          # 挂载项目代码
      - qodana_cache:/data/cache  # 持久化缓存（加速重复分析）
    ports:
      - "8080:8080"
    environment:
      - QODANA_TOKEN=${QODANA_TOKEN}  # 可选，Qodana Cloud 令牌（用于报告上传）
      - PROJECT_DIR=/data/project     # 容器内项目根路径（默认无需修改）

volumes:
  qodana_cache:  # 缓存卷用于存储依赖与分析中间结果

启动命令：docker-compose up --build

4.4 配置参数与环境变量

4.4.1 核心环境变量

4.4.2 命令行参数

通过 -- 传递额外分析参数（需放在镜像名后）：

bash
docker run ... jetbrains/qodana-ruby:latest -- --exclude=vendor/ --rule=Metrics/LineLength:disable

• --exclude=<path>：排除指定目录/文件（支持通配符）
• --rule=<rule>:<action>：临时启用/禁用特定规则（如 RuboCop/Cops/Style:enable）

4.5 查看分析报告

分析完成后，报告默认生成在项目内的 qodana/report 目录（本地路径），包含：

• index.html：可视化 HTML 报告（推荐通过浏览器打开）
• report.json：机器可读 JSON 报告（用于集成第三方工具）

如需实时查看，可通过容器映射的 8080 端口访问：
http://localhost:8080（分析过程中自动启动临时 Web 服务）

5. 配置文件详解

5.1 配置文件路径

项目根目录下创建 qodana.yaml 文件，用于持久化配置分析规则与行为（优先级高于命令行参数）。

5.2 基本结构示例

yaml
version: 1.0
profile:
  name: qodana.recommended  # 基础规则集（内置有 recommended/strict/minimal）
exclude:
  - vendor/
  - spec/fixtures/
linter:
  ruby:
    version: 3.2.0  # 强制 Ruby 版本
    rubocop:
      config: .rubocop.yml  # 引用项目自定义 RuboCop 配置
      disabled:
        - Metrics/AbcSize  # 禁用特定 RuboCop 规则
threshold:
  critical: 0  # 严重问题数量阈值（超过则触发 FAIL_ON_ERROR）
  high: 5      # 高优先级问题阈值

5.3 常用配置项

• profile：指定基础规则集（recommended 包含主流 Ruby 最佳实践，strict 启用更多严格检查）
• exclude：全局排除路径列表（支持相对路径与 glob 模式）
• linter.ruby.rubocop.config：指定自定义 RuboCop 配置文件路径（覆盖默认规则）
• threshold：设置问题严重级别阈值，用于控制 CI 流程中的失败条件

6. 集成示例

6.1 GitLab CI/CD 集成

在 .gitlab-ci.yml 中添加分析任务：

yaml
qodana:
  image: jetbrains/qodana-ruby:latest
  stage: test
  variables:
    QODANA_TOKEN: $QODANA_CLOUD_TOKEN  # 在 GitLab 项目设置中配置令牌
  script:
    - /opt/qodana/bin/run
  artifacts:
    paths:
      - qodana/report/  # 保存报告为 CI 产物
    expire_in: 1 week

6.2 本地开发工作流集成

添加到 Rakefile 简化执行：

ruby
task :qodana do
  sh <<~BASH
    docker run --rm -it \
      -v $(pwd):/data/project \
      jetbrains/qodana-ruby:latest
  BASH
end

通过 rake qodana 一键启动分析。