Python代码审查自动化：ruff+mypy与LLM的实践

1. 项目背景与核心价值

在代码审查环节中，传统的人工逐行检查方式存在效率低下、标准不统一的问题。特别是在大型项目中，一个PR（Pull Request）可能包含数百行代码变更，审查者往往需要花费数小时才能完成全面检查。更棘手的是，不同审查者对代码质量的理解存在主观差异，导致审查结果缺乏一致性。

这个项目通过组合使用ruff（Python静态检查工具）、mypy（类型检查工具）和LLM（大语言模型），构建了一套自动化PR风险分级审查系统。它能自动分析代码变更，识别潜在风险点，并生成结构化的审查报告。根据我们的实测数据，这套方案能将代码审查时间缩短60%以上，同时显著提升问题发现的准确率。

2. 工具链选型解析

2.1 为什么选择ruff+mypy组合

ruff作为新一代Python静态分析工具，相比flake8等传统工具具有明显优势：

• 检查速度快（Rust编写，比flake8快10-100倍）
• 内置600+规则，覆盖PEP8、bug风险等各类问题
• 支持自动修复（--fix参数）
• 可配置性强（pyproject.toml配置）

mypy则专注于类型检查：

• 捕获类型不匹配、未定义属性等静态问题
• 支持渐进式类型检查
• 与Python类型提示系统深度集成

这两个工具形成互补：

• ruff处理代码风格和简单逻辑问题
• mypy处理更复杂的类型系统问题
• 组合使用可覆盖80%以上的常见代码问题

2.2 LLM在审查中的独特价值

传统静态分析工具存在局限性：

• 只能识别预定义规则的问题
• 无法理解代码的业务语义
• 对设计模式、架构问题无能为力

LLM（如GPT-4、Claude等）可以：

• 理解代码的业务上下文
• 识别潜在的设计缺陷
• 发现安全漏洞模式
• 提供改进建议（而不仅是报错）

3. 系统架构设计

3.1 整体工作流程

mermaid复制graph TD
    A[获取PR代码变更] --> B[运行ruff静态检查]
    A --> C[运行mypy类型检查]
    B --> D[解析检查结果]
    C --> D
    D --> E[LLM语义分析]
    E --> F[生成风险分级报告]

3.2 核心组件实现

3.2.1 代码变更获取模块

使用GitPython库提取PR变更：

python复制from git import Repo

def get_pr_changes(repo_path, pr_number):
    repo = Repo(repo_path)
    pr = repo.pull_request(pr_number)
    return [item for item in pr.get_files()]

3.2.2 静态检查执行器

封装ruff和mypy调用：

python复制import subprocess

def run_ruff(file_path):
    result = subprocess.run(
        ["ruff", "check", "--format=json", file_path],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

def run_mypy(file_path):
    result = subprocess.run(
        ["mypy", "--show-column-numbers", "--no-error-summary", file_path],
        capture_output=True,
        text=True
    )
    return parse_mypy_output(result.stdout)

3.2.3 LLM分析引擎

构造prompt模板获取深度分析：

python复制def analyze_with_llm(code, issues):
    prompt = f"""
    请分析以下Python代码的潜在问题：
    {code}
    
    已发现的静态检查问题：
    {issues}
    
    请从以下角度提供分析：
    1. 业务逻辑一致性
    2. 潜在安全风险
    3. 性能优化点
    4. 代码可维护性
    """
    return llm_client.generate(prompt)

4. 风险分级策略

4.1 四级风险分类体系

4.2 分级算法实现

python复制def classify_issue(issue):
    if issue['tool'] == 'ruff':
        if issue['code'] in ['B002', 'B003']:  # 安全相关规则
            return 'Critical'
        elif issue['code'].startswith('E9'):  # 语法错误
            return 'High'
        else:
            return 'Medium'
    elif issue['tool'] == 'mypy':
        if 'Incompatible return value' in issue['message']:
            return 'High'
        else:
            return 'Medium'
    elif issue['tool'] == 'llm':
        if '安全漏洞' in issue['analysis']:
            return 'Critical'
        elif '逻辑错误' in issue['analysis']:
            return 'High'
        else:
            return 'Low'

5. 报告生成与集成

5.1 报告模板设计

使用Jinja2生成Markdown格式报告：

html复制## PR风险审查报告 ({{pr_number}})

### 风险概览
{% for level in ['Critical', 'High', 'Medium', 'Low'] %}
- {{level}}: {{counts[level]}}个
{% endfor %}

### 详细问题
{% for issue in issues %}
#### {{issue.file}}:{{issue.line}}
- **等级**: {{issue.level}}
- **工具**: {{issue.tool}}
- **描述**: {{issue.message}}
{% if issue.suggestion %}
- **建议**: {{issue.suggestion}}
{% endif %}
{% endfor %}

5.2 CI/CD集成示例

GitHub Actions配置示例：

yaml复制name: PR Risk Analysis
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
    - run: pip install ruff mypy openai
    - run: python risk_analyzer.py ${{ github.event.pull_request.number }}
    - uses: actions/upload-artifact@v3
      with:
        name: risk-report
        path: report.md

6. 实战效果与优化

6.1 实际项目中的表现

在某中型Python项目（约5万行代码）中的测试数据：

6.2 性能优化技巧

1. 增量检查：只分析变更文件而非整个项目
2. 缓存机制：对未修改文件使用上次检查结果
3. LLM批处理：将多个问题合并提交给LLM
4. 规则过滤：忽略历史问题较多的文件

python复制# 增量检查实现示例
def get_changed_files(pr):
    base = repo.get_commit(pr.base.sha)
    head = repo.get_commit(pr.head.sha)
    return base.diff(head).iter_change_type('M')

7. 常见问题与解决方案

7.1 误报处理策略

1. 建立白名单：对已知误报模式添加忽略规则

toml复制# pyproject.toml
[tool.ruff]
ignore = ["E501", "F401"]

2. LLM二次验证：对静态工具发现的问题进行确认

python复制def verify_with_llm(issue, code):
    prompt = f"请确认以下是否是真正的问题：\n{issue}\n在代码中：\n{code}"
    return llm.generate(prompt)

7.2 处理大型PR的策略

1. 分块分析：按模块/功能拆分PR审查
2. 优先级排序：先处理高风险变更
3. 采样检查：对相似变更进行抽样
4. 资源控制：限制LLM的token使用量

python复制# 分块分析实现
def analyze_large_pr(pr, chunk_size=5):
    files = get_pr_changes(pr)
    for i in range(0, len(files), chunk_size):
        analyze_chunk(files[i:i+chunk_size])

这套系统在实际项目中显著提升了代码审查效率，特别是在持续集成环境中，能够为开发团队提供即时、客观的代码质量反馈。通过合理的风险分级，团队可以优先处理最关键的问题，而不必被大量低风险警告分散注意力。