Scrut：基于Git变更的Python增量静态代码审查工具

Scrut 是一个很有意思的 Python 静态代码审查工具核心思路一句话就能说明白只审查 Git 里发生变更的文件而不是每次把整个项目从头到尾重扫一遍。这个设计解决的是大型仓库里最常见的痛点——全量静态分析太慢、存量报错太多开发者真正关心的其实是本次改动有没有引入新问题。如果你平时用 Python 开发又希望把代码检查更快地嵌进本地提交或 CI 流程这篇文章会从环境准备、首次运行、核心原理到 CI 集成拆一遍帮你在实际项目里判断它到底值不值得用。我最近拿到这类变更驱动型审查工具时不会先看它支持多少种规则而是先做三件小事确认 Python 环境、准备一个真实的 Git 仓库、故意制造一次带问题的文件修改。这三步跑通之后你才能准确判断工具的反馈速度、报告质量和误报程度。下面按这个顺序完整拆一遍。1. 静态代码审查为什么非要盯着 Git 变更文件1.1 全量扫描的真正痛点传统静态代码审查工具比如 pylint、flake8、mypy 这类默认行为都是对指定目录或整个项目做扫描。项目小的时候没问题几秒到十几秒就出结果。但当仓库膨胀到几十万行、上百万行之后问题就出来了。首先是慢。每次提交或推送后CI 都要重新分析所有文件一个中型 Python 项目全量扫描可能在几十秒甚至几分钟。开发者在等一个提交反馈结果大部分时间耗在分析那些根本没改过的历史文件上。其次是噪音。老仓库往往积累了成千上万条既有告警这些告警是谁在什么时候引入的、要不要修、该谁修本来就说不清楚。更麻烦的是你这次改动只碰了三个文件工具却把整个项目的历史问题全列出来了代码评审的人很难从中间挑出真正和本次改动相关的问题。还有一个实际问题是成本。全量扫描对 CPU、内存、CI 分钟数都有明显消耗做一次能接受每次提交都做一次团队就要开始考虑是不是该关掉某些规则、减少某些检查目录。1.2 Scrut 的定位只审查变更不重新扫全库Scrut 的核心定位就是“增量配合审查”。它的静态代码审查范围不是整个仓库而是 Git 变更集合里的文件。你改了哪些文件它就分析哪些文件。新增、修改、重命名、删除的文件都会进入这个集合和本次改动无关的目录一概不碰。这种思路在工程上其实并不新鲜很多大型 CI 系统内部早就做了增量检查。但把它做成一个专门的 Python 静态代码审查工具好处是使用方式更直接本地提交前可以跑CI 里拿到变更列表后也可以跑不用自己再写一层 diff 筛选逻辑。它最值得关注的不是“比 pylint 更聪明”而是“比全量检查更聚焦”。扫描范围小执行时间和输出数量都会下降。对代码评审流程来说报出来的问题更容易对应到本次改动而不是一堆老账。1.3 适合谁用、不适合谁用如果团队的情况是Python 项目已经用 Git 管理提交和分支流程比较规范想在提交前或 MR 审查阶段给开发者快速反馈全量检查太慢或历史告警太多希望减少噪音能接受“只检查本次变更”而不是“对整个仓库体检”那 Scrut 这类工具就很合适可以先做小规模试点。反过来如果项目根本没有 Git 仓库历史或者想在旧代码里排查存量问题那不适合。它分析的重点是“变更之后的状态”不是“仓库所有文件的健康状况”。同样如果项目代码大量使用动态执行、运行时反射、外部接口动态注入那么基于静态分析的审查工具能发现的问题天然有限。它不是测试也不能替代运行时检查。2. 跑起 Scrut 之前环境和依赖先按这个顺序准备2.1 Python 环境是最先要确认的静态代码审查工具本身是 Python 写的所以第一步就是把 Python 环境弄干净。最好先确认 Python 版本再创建独立虚拟环境。不要图省事直接往系统 Python 里装因为你可能还有别的项目依赖不同版本的库装来装去很容易互相覆盖。在常见环境下新建虚拟环境的命令大致是这样python -m venv .venv source .venv/bin/activateWindows 下的激活命令是.venv\Scripts\activate。激活后终端提示符会变化此时输入python --version确认解释器路径已经指向虚拟环境。对于 Scrut 这类项目具体支持哪个 Python 版本范围要以项目 README 或 setup 配置为准。原始材料没有给出明确的版本门槛我建议落地前先确认你的 Python 主版本不能太老也不要盲目用刚发布的最新版本。一般 3.8、3.9、3.10 之后的常见版本兼容性会好一些但仍然以项目文档为最终标准。2.2 Git 仓库状态和分支习惯Scrut 依赖 Git 来判断“哪些文件发生了变更”所以它必须跑在一个真实的 Git 仓库里。普通文件夹不行没有.git目录也不行。准备阶段先确认几件事当前目录是否已经执行过git init或从远程git clone过工作区里有没有正在修改但未加入暂存区的文件有没有文件被.gitignore忽略当前分支和对比目标分支是否明确。一个比较容易忽略的地方是如果文件还未被 Git 跟踪也就是git status里显示为Untracked那么很多增量检查工具不会把它放进变更集合。因为它在 Git 视角里还不算“变更”而是“新出现但未确定”的文件。2.3 安装 Scrut 的通用方式按照同类 Python 工具的惯例安装方式大概率是通过包管理器安装或者从源码仓库拉下来后本地安装。由于项目名叫 Scrut入口命令通常也会是scrut但具体以项目文档为准。如果走包管理器典型流程可能是这样pip install scrut如果走源码安装通常是这样git clone 项目地址 cd scrut pip install -e .安装完成后先不要急着跑大项目先用一条命令验证工具是否正常进入scrut --help如果没有报错能看到参数说明说明安装层基本没问题。如果提示找不到命令就先检查当前虚拟环境是否激活、安装是否真的成功不要急着怀疑项目本身。我习惯做一张简单的检查清单防止环境问题后来变成排查障碍。检查项判断标准常见问题Python 版本符合项目说明版本过老或过新虚拟环境命令解释器来自 venv装到了系统 PythonGit 仓库存在.git目录普通文件夹无法识别变更Git 状态能正常执行git status仓库损坏或路径错误依赖安装pip list能看到相关包安装失败或未激活环境输出目录目录可写、路径正确日志或报告写入失败3. 用 Scrut 做一次变更审查从最小场景到常见命令3.1 先在本地仓库创建一次可测试的变更我一般建议第一次测试不要直接跑真实的老项目而是单独建一个小仓库人为制造一次带问题的变更。这样能快速验证工具的逻辑也方便看输出格式。可以按下面的方式准备mkdir scrut-demo cd scrut-demo git init然后创建一个最简单的 Python 文件def demo(): unused_var 1 print(hello)先把这版提交git add demo.py git commit -m initial commit接着修改文件故意引入几个常见问题比如未使用变量、未定义名称、缺少必要的 importdef demo(): unused_var 1 print(result)此时再执行git status和git diff --name-only能看到demo.py出现在变更列表里。这一步的目的不是测功能而是确认“Git 能找到这个变更”否则静态审查工具再厉害也拿不到正确的文件集合。3.2 我的建议顺序diff 先过一遍再让 Scrut 审查在实际使用中我建议你先用 Git 命令确认变更集再跑静态审查工具。顺序反过来的话一旦出现“工具没审查到某个文件”的情况你会很难判断是工具的问题还是 Git 变更集本身就不包含这个文件。常用命令是git diff --name-only git diff --name-only HEAD git status --short然后运行 Scrut。由于我没有把具体命令行参数当成标准事实这里给一个通用示意scrut --git-diff如果你的版本里不需要显式指定git-diff那就更简单直接在当前仓库中执行主要命令即可。但不管用哪种方式第一轮测试的目标只有一个让工具自己找到demo.py这个变更文件并在输出里告诉我们问题位置。如果输出里包含文件名、行号、错误描述说明流程已经跑通。接下来再做批量验证才有意义。3.3 首次运行后重点看四个输出维度第一次跑完不要急着调参数先看四个东西第一启动是否正常。有没有报依赖缺失、Python 语法解析失败、Git 执行失败之类的错误。第二文件列表对不对。它分析的是不是刚才变更的那几个文件而不是全仓库。第三报告质量。每条告警是否包含文件、行号、列号、规则或描述是否指向真实问题。第四执行时间。单文件、少量文件的速度应该很快就算脚本启动有固定开销也不应该慢到无法接受。如果输出为空优先检查变更集是否为空。很多新手在这里会花很长时间看规则配置结果发现是git status都没显示文件或者文件被.gitignore忽略了。注意第一轮跑通代表“能运行”不代表“配置正确”。先确认工具分析的确实是变更文件再开始调规则。4. 核心运行原理和判断标准4.1 变更文件是怎么被确定的静态代码审查工具要判断“哪些文件发生了变更”本质上是调用 Git 的底层能力。常见做法是先执行类似git diff --name-only的指令拿到一批文件路径再结合暂存区、工作区、目标分支的差异合并出最终集合。对于一次本地未提交的修改它关心的是工作区和最近一次提交之间的差异。对于 MR 或 PR 审查场景它关心的往往是目标分支和当前分支之间的差异。这个差异集合的准确性直接决定了工具到底审什么。所以你会发现这类工具的根基其实是 Git 流程。如果团队里有人习惯用 IDE 直接改文件但不提交或者经常把文件放在.gitignore里增量审查工具就很容易出现“明明改了很多文件但报告只覆盖了其中一部分”的现象。4.2 静态审查在查什么静态代码审查不是执行代码而是读取源代码的语法、结构、依赖关系然后匹配预设规则。Scrut 作为 Python 静态代码审查工具分析对象是 Python 源码。常见检查维度包括未定义变量、未使用 import、函数参数问题、重复定义、可疑控制流、资源未释放这些容易通过源码结构发现的问题。但是要注意静态分析受限于代码写法。比如def demo(): result something() return result如果something是从其他模块动态导入或者通过globals()拼出来的静态工具可能无法发现它。这不是工具能力不够而是静态分析的天然边界。你拿到工具报告时先看它标注的规则类型再判断是否适用于当前项目会更容易减少误报影响。4.3 怎么判断速度是否正常、结果是否有效判断一个静态审查工具好不好用不是看它报了多少问题而是看以下指标速度单文件应该在秒级内完成少量文件在几十秒内完成属于正常如果只是改一个文件却跑了几分钟要看是不是误触发了全量扫描。有效报告里的每一行都能对应到本次变更文件的具体位置描述能让人判断“是不是问题”。稳定同一个仓库、同一个变更集连续跑两次结果应该一致。如果结果随机变化那报告很难作为 CI 门禁。可读输出内容能解析成表格、JSON 或明确的文本格式方便接进报告系统或者直接贴在 MR 评论里。我一般会把静态审查工具的输出和人工 review 对照一遍看看哪些问题是人能认出来的哪些问题是误报。第一轮人工对照不需要全部修只需要评估“这个工具的规则适不适合我们团队”。5. 接入批量场景CI、pre-commit、多分支对比5.1 在本地 git hook 或 pre-commit 中使用当本地环境跑通之后下一步就是把它固定到工作流里避免每次手敲命令。一种方式是接入 pre-commit。pre-commit 是一个 Git hook 管理器会在 commit 前运行配置好的检查器。如果你希望每次提交前自动检查变更文件可以在.pre-commit-config.yaml里增加一个入口。具体写法取决于项目是否提供了 pre-commit hook如果没提供也可以在.git/hooks/pre-commit里写一行简单脚本作用类似。我自己的习惯是本地提交前使用轻量检查不把全部规则打开只保留最基础、误报率最低的规则。如果本地就把规则全开很多老项目会一直卡在存量告警上开发者反而会为了绕过 hook 使用--no-verify最后 hook 形同虚设。5.2 在 CI 流水线中只审查 MR 变更文件CI 是静态审查工具更合适的场景因为 MR 提交时已经能拿到明确的变更列表。以常见的 CI 流程来说第一步是拉取代码第二步是在 Git 上下文中计算差异文件第三步运行静态审查第四步生成报告并决定是否阻塞合并。核心代码逻辑可以用一个大致的流程来理解# 获取目标分支和当前分支的共同祖先提交 BASE_SHA$(git merge-base origin/main HEAD) # 列出相对于共同祖先发生变化的文件 CHANGED_FILES$(git diff --name-only $BASE_SHA HEAD -- *.py) if [ -z $CHANGED_FILES ]; then echo no python files changed exit 0 fi scrut --files $CHANGED_FILES这里的关键是git merge-base。用origin/main...HEAD可以拿到两个分支之间的差异而不会把 main 上已经存在但当前分支未修改的文件混进来。如果 CI 平台本身就提供了变更文件列表那就直接用平台变量不用再手算 Git 差异。GitHub Actions、GitLab CI、Gitea 这类平台在 MR 事件里通常都有changed_files上下文可以传给审查工具。注意不同平台的变量名和获取方式不一样落地时以平台文档为准。5.3 多分支、Merge 场景下的文件集合处理多分支场景下最容易出错的是对比基准。很多人直接用git diff origin/main HEAD但如果 main 已经落后于当前分支或 main 上有其他未合并的提交这个差异集可能包含当前分支没动过的文件也可能漏掉某些新增但没有提交的更改。更稳妥的方式是先把当前分支git fetch成最新再基于共同祖先计算差异。git fetch origin BASE_SHA$(git merge-base origin/main HEAD) git diff --name-only $BASE_SHA HEAD对于删除文件、重命名文件也要提前确认处理方式。有些工具只会分析当前存在的文件删除文件自然没有内容可分析重命名文件在 Git 里可能被识别为“删除 新增”那就要看新增副本有没有进入变更集合。6. 参数配置和自定义规则从默认值到团队规范6.1 常用参数项说明关于 Scrut 的参数原始材料没有给出明确的参数名所以我这里给的是通用参考框架具体参数以项目 README 或scrut --help输出为准。一般静态审查工具都会涉及以下几个方面。参数方向作用建议变更集来源指定用 Git diff 自动识别还是手动传文件本地用自动CI 用平台变更列表目标目录限定扫描范围避免扫描 venv 和生成目录忽略文件排除不需要检查的文件根据项目实际情况配置输出格式文本、JSON、JUnit 等CI 建议用结构化格式规则级别区分 error、warning、info新项目初期别全开退出码有告警时是否阻塞先不阻塞跑两周再决定6.2 自定义规则的基本思路自定义规则通常不是看工具支持多少现成规则而是看它有没有开放规则接口。理想情况下你可以用自己的函数接收 AST、源码文本或文件路径返回一条告警。写一个自定义规则的伪代码思路def check_no_debugger(tree, filepath): for node in walk(tree): if is_debugger_call(node): yield { file: filepath, line: node.lineno, message: 请勿提交调试器调用, level: warning }实际接口可能不是这样但核心思想一致静态审查规则的难点不在于写判断逻辑而在于表达“什么样的代码算问题”。定义太宽会误报定义太窄会漏报。建议先定义 3 到 5 条团队最在乎的规则跑一段真实代码看看效果再逐步扩展。6.3 不同项目的配置建议小型项目可以直接用默认配置只要确认它能跑、输出清晰即可。中型项目建议加忽略列表和目录限制尤其要把venv、.venv、node_modules、迁移脚本这类目录排除掉。大型项目则应该把规则打开过程拉长可以先只开 error 级别warning 和 info 先输出不阻塞让团队逐渐适应。团队落地时还要注意一个点规则基线和例外处理。项目里总会有一些历史遗留代码不符合新规则如果强制要求全部修改成本很高。更常见的做法是允许按文件或目录设置例外或者先统计历史告警数量设定一个增量目标新代码必须符合规则老代码逐步迁移。7. 常见问题排查不是工具不行多半是前置条件没对齐7.1 启动报错和依赖问题遇到Command not found先确认虚拟环境是否激活再确认安装是否成功。遇到ModuleNotFoundError先看报错缺的是哪个包再补装对应依赖。遇到 Python 版本不兼容先看项目要求的版本范围安装正确的解释器版本。这类问题我建议按“现象 - 环境 - 依赖”的顺序排查不要一开始就怀疑功能实现。先执行python --version和pip list确认当前环境里到底有什么。7.2 审查范围不对改了文件却不审这是静态审查工具最常见的问题而且大部分时候不是工具的问题。优先执行git status --short git diff --name-only如果文件没有出现在输出里工具当然不会审它。可能的原因包括文件没有被 Git 跟踪文件被.gitignore忽略文件路径不在当前仓库内你修改的是工作区文件但工具读取的是暂存区对比结果在 CI 场景里你拿到的差异基准选错了。排查顺序就是先看 Git再看工具传入参数最后再怀疑工具本身。7.3 误报、漏报和输出格式问题误报出现时先看是哪条规则触发的再确认是否适合当前项目。比如有些团队在代码里大量使用装饰器或动态属性静态分析很容易判断为“未定义”。这时候不是把整条规则关掉而是通过配置文件加例外或者缩小规则适用范围。漏报出现时先确认该文件是否真的进入了变更集再确认规则是否被配置文件关闭。某些情况下源文件如果有语法错误解析器会跳过该文件导致漏报大量问题。输出格式乱码或解析失败则优先检查编码和是否使用标准输出重定向不要急着怪工具。7.4 排查顺序可以统一成五步我在实际工作中遇到静态审查工具的问题通常按这个顺序走看现象是启动失败、输出为空、报告错位还是卡住不动。看 Git变更集是否包含目标文件对比基准是否正确。看环境Python 版本、虚拟环境、依赖包是否匹配。看参数文件路径、忽略列表、规则级别是否与预期一致。看工具确认你是用文档里的标准命令运行还是用了实验参数。这个顺序能覆盖绝大多数问题而且每一步都比“直接改代码”更便宜、更快。8. 边界和实际建议这工具不是万能静态检查器8.1 常见边界情况不夸大Scrut 这类变更驱动审查工具最大的优势是响应快、报告聚焦但它的边界也很清楚。它不能保证发现所有 bug。静态分析只能基于源码结构推断问题无法验证运行时状态。一个变量在三个文件之间传递最终在某个分支里被错误使用静态工具很难完整捕获。它不能替代全量检查。如果团队每个季度需要做一次全量代码体检还是需要跑一次覆盖全仓库的工具。增量审查更适合日常反馈全量检查更适合定期治理。它不能解决团队流程问题。如果提交不规范、分支管理混乱、.gitignore随意添加那么增量审查工具拿到的变更集本身就不可靠工具再准也没有意义。8.2 落地时的工作流建议如果要在团队里推广我建议分三步走。第一步先本地试点。选一个核心仓库先跑单文件再跑真实 MR看误报率、速度、输出格式是否可接受。第二步再接入 CI。先在 CI 里只输出报告不阻塞合并。跑一到两周统计一下报告里有多少问题被开发者认可有多少是误报。这个阶段重点不是“修复所有问题”而是评估工具的规则是否适合团队。第三步再决定是否做门禁。当规则和例外已经稳定告警里的噪声明显下降再把关键规则设置为阻塞。不要一开始就用最强规则门禁否则团队会疲劳很容易绕过检查。8.3 最后留几个自己排查时会优先看的点如果你正准备在项目里使用 Scrut我会建议优先盯住这几个地方变更集合是否正确。这是所有增量检查的地基集合错了后面的报告全没意义。安装环境是否独立。用虚拟环境隔离项目依赖避免不同项目互相影响。输出格式是否便于解析。CI 环境建议用结构化输出方便后续自动统计和区分配置。规则是否按级别收敛。先把 error 级规则跑稳再考虑 warning 和 info别一上来全部打开。运行日志和输出目录。无论工具在哪一步卡住日志里一定有线索。这类工具真正落地时最该盯住的不是功能列表而是输入变更集、资源占用和规则噪声。把这三个点控住了它就能成为一个很轻量的代码质量反馈层控不住不管工具本身多好最后都会在重复排查和误报解释里被团队放弃。