如何为不符合flake8规范的代码库通过GitHub Actions集成flake8检查

实现步骤 #

• 第一步：本地配置flake8规则
  首先安装flake8及配套工具：pip install flake8 mccabe，其中mccabe用于检测代码圈复杂度。
  在仓库根目录新建.flake8配置文件，参考配置如下：

  [flake8]
  max-line-length = 120
  max-complexity = 10
  exclude = .git,__pycache__,venv,dist,build,*.pyc
  ignore = E203,W503
  

  配置项可根据团队开发习惯自行调整。
• 第二步：处理存量代码问题
  本地执行flake8 .查看全量代码的检查结果，有两种处理方案可选：

  如果存量问题少，可直接一次性整改完毕后再上线CI检查；
  如果存量问题多，可通过per-file-ignores配置项先忽略存量文件的已有问题，仅要求新提交代码符合规范，后续逐步整改存量。

• 第三步：配置GitHub Actions流水线
  在仓库根目录新建.github/workflows/flake8-check.yml文件，内容参考：

  name: Flake8代码检查
  on:
    push:
      branches: [ main, develop ]
    pull_request:
      branches: [ main, develop ]
  jobs:
    lint:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - name: 配置Python环境
          uses: actions/setup-python@v5
          with:
            python-version: "3.10" # 替换为项目实际使用的Python版本
        - name: 安装依赖
          run: |
            pip install --upgrade pip
            pip install flake8 mccabe # 按需添加其他flake8插件
        - name: 执行flake8检查
          run: flake8 .
  

• 第四步：验证生效
  将配置文件提交到仓库，触发流水线运行，确认检查逻辑正常，不符合规范的代码提交会被阻断即可。

重点注意事项 #

• 规则对齐团队共识：不要直接照搬默认规则，行长度、缩进、忽略规则等要和团队现有开发习惯匹配，调整后的规则要同步到所有开发本地，保证本地检查和CI检查结果一致。
• 存量问题平滑过渡：不要一次性强制全量规则生效导致现有迭代受阻，可分阶段推进规则落地，先管控增量代码，再逐步整改存量问题。
• 依赖版本统一：flake8及相关插件的版本在本地、CI环境要保持一致，可将相关依赖写入项目的requirements-dev.txt统一管理，避免版本差异导致的检查结果不一致问题。
• 复杂度阈值合理：圈复杂度阈值建议设置为10~15，过于严格的要求会导致代码被不必要拆分，反而降低可读性。
• 排除无效检查路径：务必将虚拟环境、构建产物、第三方依赖等不需要检查的目录加入exclude列表，避免拖慢CI运行速度，产生不必要的报错。
• 错误分级管控：可根据需要将语法错误、逻辑类问题设置为合并阻断级别，格式类告警设置为提示级别，避免非核心问题影响正常迭代。

内容的提问来源于stack exchange，提问作者MasterOfTheHouse