代码评审的时候我经常在 PR 里看到三类东西缩进一会儿空格一会儿 Tab几个没用的 import 堆在那里还有一个函数参数多到要翻两屏才看完。这种问题不算致命但会反复出现——只要项目里没有一套自动化的检查机制人工 Review 就会永远陷在这些琐碎里。所以两年前我做的第一个动作就是给项目装上 Pylint 和 Flake8 这两道静态检查关卡让机器先替人把明显的问题挡住。这篇文章不是 Pylint 和 Flake8 官方文档的翻译而是我先后在几个 Python 项目里把它们从装了跑一下到真正写进开发和评审流程的完整经验。适合刚接触静态检查的小白也适合已经在用但觉得规则太吵、不知道该怎么配置的团队。我会尽量把里头的门道讲清楚它们各自查什么、为什么两个都要、配置到底怎么写、以及怎样让团队愿意长期用而不是装完就扔。1. 静态检查到底在查什么先建立代码质量的共识1.1 不运行代码就能查问题是什么原理先说明白一件事Pylint 和 Flake8 都属于静态代码分析工具。所谓静态指的是它们不真正执行你的代码而是把源码当成文本来解析在语法树和逻辑结构上做检查。因此它们跑得再慢也慢不到哪去而且永远不会真的把你的数据玩坏。这跟单元测试、集成测试有本质区别——那些测试你要构造环境、准备数据、跑业务流程而静态检查只要一行命令几秒到几十秒就出结果。我记得第一次用 Flake8 检查一个旧项目时几十个文件瞬间就扫完了列出来的问题五花八门有没用的 import有定义了却没用的变量有一个函数缩进不一致导致的潜在语法歧义还有一行长到 120 个字符的火车代码。这些问题是人眼很难在一遍遍 Review 里始终盯住的但机器可以做到每次都一样严格。这一节我想先帮大家建立一个共识代码质量不是一个模糊的感性概念而是一组可以被规则化、被自动验证的客观标准。Pylint 和 Flake8 就是把这套标准落地的工具。后面讲配置时你会频繁看到规则这个词每个规则都有自己的编号和明确行为描述这意味着团队里任何一个人都可以查文档搞清楚某条规则在说什么而不是靠印象吵架。1.2 Flake8 的三合一体质风格、低级错误、复杂度Flake8 其实不是单一的检查器它默认把三个工具包在一起pycodestyle 负责 PEP 8 风格检查pyflakes 负责找出未使用变量、未使用 import、未定义名称这类逻辑硬伤mccabe 负责计算圈复杂度。这三个角色分别可以理解成排版校对员低级错误探测器和复杂度雷达。pyflakes 那一层我特别喜欢因为它几乎不会误报。它做的是纯粹的静态推导某个名字在整个文件里 import 了但从没被用过某段代码引用了不存在的变量某个分支里的语句永远不可能执行到——这些结论都是确定的不需要猜测代码意图。正因为如此Flake8 在门禁场景特别管用它说不行就是真的不行团队里基本不会有人跟它争论。mccabe 的圈复杂度衡量的是函数里独立路径的数量。比如一个函数有五个 if 分支加两个 for 循环得分就会直线上升。这类函数往往是最容易藏 bug 的地方因为调用者很难覆盖所有路径。Flake8 默认把复杂度阈值设在 10超过就报警这个数值本身就是一个很合理的起点。1.3 Pylint 的体检范围从命名到坏味道Pylint 则走得更深。它不止查风格和明显的错误还会分析函数参数数量、类的方法个数、模块里的重复代码比例、命名是否符合规范比如函数名要小写加下划线、常量要全大写、异常处理是否过宽、变量名是否与关键字冲突等等。可以说 Flake8 更像急诊分诊台Pylint 更像一次全面体检它会告诉你很多现在没出问题但长期看可能出事的隐患。举个例子Pylint 会检查一个函数是否参数太多默认超过 5 个就警告是否在一个函数里做了太多事情可以通过分支数量判断甚至能识别出近似重复的代码块并给出相似度报告。这些能力对重构特别有帮助尤其当你要接手的是一段三年前的祖传代码时Pylint 的报告几乎就像一张先清哪块债的施工图。那么到底用哪个我的答案是两个一起用但分工不同。下一节具体讲它们怎么配合。2. Pylint 和 Flake8 的分工差异为什么两个都要装2.1 一张表看清两者的定位先给一张对比表对比维度Flake8Pylint内核组成pycodestyle pyflakes mccabe独立分析引擎检查重点风格、低级错误、复杂度命名、坏味道、重复代码、逻辑隐患运行速度快秒级扫描大项目较慢大项目可能需要几十秒误报率低规则边界清晰偏高需要配置调教配置成本低几个参数就能开工高默认规则偏严初期噪音多典型场景CI 门禁、提交前快速检查定期体检、重构辅助、深度 Review这表的结论很直接Flake8 适合当门卫因为又快又准Pylint 适合当家庭医生因为查得全但偶尔会小题大做需要你给它划清楚边界。我在项目里的实际组合是pre-commit 阶段只跑 Flake8几十毫秒出结果不打断开发节奏Pylint 放在 CI 里跑生成完整报告检查不达标就不允许合并。这样一个快一个慢、一个浅一个深互相不干扰。2.2 Pylint 能查到而 Flake8 查不到的典型问题光说查得深太抽象举几个具体例子。Flake8 的 pyflakes 能发现变量定义了但没用但它不会管这个变量是不是命名不当Pylint 则会把命名规范、参数数量、函数长度、模块内重复代码这些维度全部拉进来。更关键的是 Pylint 能做一定程度的跨语句逻辑推理。比如它会发现某个 except 子句捕获了 Exception 却没有任何处理只是默默吞掉错误这在 Flake8 看来完全没问题但实际是事故高发区。再比如它会在发现类里定义了某个方法但从未被使用时给出提示帮助清理死代码。还有一个我印象很深的能力是 Pylint 的相似代码检测。它默认会把超过四行且高度相似的代码块标出来这对抓 CtrlC / CtrlV 出来的重复逻辑特别管用。我有一次在某个服务里跑了一遍立刻发现两个工具函数长得几乎一模一样只有参数名不同顺手就合并了。这种问题靠 Code Review 很难发现因为人眼扫过去会默认这是两个函数而机器会告诉你这俩是同一段代码的复制。2.3 为什么不是二选一而是组合拳有人会说 Flake8 已经能查风格和低级错误了再加个 Pylint 是不是重复我觉得不是。把代码质量的检查维度拆开看风格层、语法错误层、逻辑隐患层、维护性层每一层都需要不同的检查深度Flake8 只覆盖前两层半Pylint 才有能力触达后面两层。让一个工具扮演它不擅长的角色结果就是配置越改越离谱最后只能把规则全关掉。反过来如果只装 Pylint它的噪音会让新人在入职第一周就产生这工具是不是有病的念头团队很难坚持下去。所以最稳妥的路线永远是先用 Flake8 把底线立住再让 Pylint 作为深度体检工具逐步介入。这套组合在我的几个项目里跑了一两年效果非常稳定。3. 从安装到跑通让两个工具先在自己的项目里转起来3.1 安装命令和最简单的用法安装没什么花头pip install flake8 pylint我建议装在项目的虚拟环境里而不是全局安装这样每个项目的规则版本不会互相污染。装好后对单个文件就能直接跑flake8 app/models.py pylint app/models.py对一个目录flake8 app/ pylint app/第一次跑完大概率会看到一大屏输出。不要慌这很正常尤其是老项目。此时的目标不是把数字变成零而是先看懂它在喊什么。3.2 读懂输出里的规则编号以 Flake8 为例典型输出是文件路径:行号:列号: 规则码 描述。比如app/models.py:15:1: F401 os imported but unused app/models.py:27:5: E501 line too long (92 79 characters)规则码第一位字母代表来源E/W 来自 pycodestyleE 是错误W 是警告F 来自 pyflakesC 来自 mccabe 复杂度。看到 F401 就知道是import 了没用看到 E501 就是行太长。查这些编号非常方便直接搜flake8 F401就能找到官方解释和常见处理方案。Pylint 的输出格式是文件路径:行号: 规则码: 描述 (消息名)比如app/models.py:15:0: C0116: Missing function or method docstring (missing-function-docstring) app/models.py:27:0: R0913: Too many arguments (6/5) (too-many-arguments)规则码同样有意义C 表示惯例问题conventionR 表示重构建议refactorW 是警告E 是错误。括号里的消息名是短横线格式配置时要用这个名字来关闭对应规则。3.3 退出码和 Pylint 评分机器怎么判断过不过这里有个容易被忽略但很重要的细节命令行工具跑完是有退出码的。Flake8 只要发现任何问题就返回非零退出码所以它天生适合做门禁——CI 里一条命令跑完非零就挂掉。Pylint 则用 0 到 10 的评分来表示代码健康度默认 10 分满分每发现一个问题按严重程度扣分。CI 里可以用--fail-under8这种参数来设置分数线低于 8 分就退出非零。这个机制灵活多了适合一步步提高标准的场景。我见过有人为了凑满分把大量规则 disable 掉这完全本末倒置。评分的意义是给你一个当前代码整体处于什么水平的参考而不是逼你把每个警告都清零。真正健康的做法是设置一条合理基线比如 8 分低于它才拦然后慢慢把分数往上推。4. 配置才是关键用 .pylintrc 和 .flake8 定制团队规则4.1 配置文件从哪来Flake8 的配置可以放在项目根目录的.flake8文件也可以是 setup.cfg 里的 [flake8] 段。Pylint 用.pylintrc一条命令就能生成模板pylint --generate-rcfile .pylintrc生成的模板有几百行注释第一次看会头晕。我的建议是不要照单全收先跑一次默认配置把那些明显不合理的告警记录成清单然后只针对清单改配置。配置文件的核心作用不是把所有规则都打开而是把团队认同的规则留下把不认同的关掉并写清楚为什么。4.2 最值得调整的几个参数无论 Flake8 还是 Pylint有几个参数几乎每个项目都要动行长度上限、函数参数上限、复杂度上限、禁用规则列表。行长度是争吵最多的一个。PEP 8 建议 79但现代项目在 120 以内普遍可接受。我不是说越长越好而是团队用什么格式规范就应该保持一致。Flake8 里写[flake8] max-line-length 120 extend-ignore E203, W503Pylint 里对应的是[MASTER] ignore migrations, build, venv [MESSAGES CONTROL] disable C0116, R0903 [DESIGN] max-args 6 max-complexity 10E203 和 W503 是 Flake8 里跟 Black 格式化工具冲突的两条规则用过 Black 的人基本都会把它们加进忽略列表不然格式化完的代码还会被 Flake8 标红特别尴尬。4.3 局部忽略规则不是一刀切的配置文件的 disable 是全局的但实际项目里总有这个地方我知道违规但确实合理的情况。比如一行特别长的 URL、一个动态生成的属性名。这种时候用局部忽略而不是为了一个角落把整个规则关掉。Flake8 用# noqa加规则码url https://example.com/some/very/long/path/that/breaks/line/length # noqa: E501Pylint 用pylint: disabledef legacy_api(data): # pylint: disabletoo-many-arguments ...# noqa不带规则码的话会忽略这一行所有问题我建议大家永远带上具体规则码不然漏掉真正的新问题都不知道。还有一种更精细的写法按文件忽略。Flake8 支持per-file-ignores比如测试文件可以放宽几类规则[flake8] per-file-ignores tests/*:S101整体原则是局部问题用局部手段解决全局问题才动全局配置。这条原则在 Pylint 里同样成立它能按模块、按文件设置不同的禁用项只是语法稍微绕一点值得花时间读一遍文档。5. 接入开发流程让检查器跑在每个改动落地之前5.1 为什么先拦住本地很多人一开始只在 CI 里跑检查但问题在于CI 发现错误时代码已经提交了修复要走一遍完整流程来回成本高。更聪明的做法是在本地提交之前就拦截。这就是 pre-commit 钩子的价值——commit 命令执行前自动运行一系列检查不通过就不让提交。我见过一个项目早期没有本地拦截CI 每次都因为一个没删干净的 print 语句挂掉开发者平均要等三分钟才知道自己错了。后来加了 pre-commit同样的错在提交瞬间就被拦下来三分钟变成三秒。5.2 pre-commit 配置示例pre-commit 是一个独立的工具安装后项目根目录放一个.pre-commit-config.yamlrepos: - repo: https://github.com/PyCQA/flake8 rev: 6.1.0 hooks: - id: flake8 args: [--config.flake8]然后跑一次pre-commit install之后每次 git commit它就会先对你的暂存文件做检查。配置里也可以加 Pylint但因为 Pylint 跑得慢我一般只把它放到 CI不太适合放在提交钩子里打断节奏。5.3 CI 门禁与代码评审的分工到了 CI 这一层检查的意义就变了它不再是帮你改问题而是确保每个合并进来的代码都满足最低标准。此时 Pylint 的--fail-under就派上用场设一条分数线不达标直接阻止合并。这种硬门禁的好处是让代码评审从找低级错误里解放出来——行太长、没写 docstring、参数太多这类事机器已经很可靠了评审人只需要把精力放在逻辑、架构和数据安全上。我常在评审里看到有人给缺少空行这类风格问题留评论说实话这很浪费。把风格问题交给工具评审才有意义。5.4 渐进式接入先管新增代码再清旧债老项目的存量问题通常几千条强行清零会让团队崩溃。稳妥做法是只对新代码生效把旧问题记进一个基线文件允许存在但不增加。Flake8 和 Pylint 都有类似基线或豁免机制也可以配合脚本统计增量问题。这样团队不会有改一行代码还要顺便修十条老问题的挫败感同时新代码的质量从第一天起就被管住。等存量问题慢慢被重构消化再把基线收紧。我见过一个团队用这种方式半年后基线文件里的问题从两千多条降到了两百条中间没有任何一次集中式大扫除全靠每次改动顺手清理。6. 误报、噪音与规则打架让团队愿意长期使用的关键6.1 最常见的误报场景Pylint 误报率偏高的名声主要来自几个固定场景。第一个是动态属性比如 SQLAlchemy 的模型列、Pydantic 的字段Pylint 静态分析看不到这些运行时才存在的属性就会报模块没有 X 成员。第二个是 pytest 的 fixture 参数fixture 名字在测试函数里作为参数出现Pylint 可能报未定义变量或参数未使用。第三个是框架的全局对象运行时会注入很多属性静态分析也不可见。这类误报一旦出现记住一个原则宁可针对具体模块配置豁免也不要全局关闭相关规则。比如 SQLAlchemy 项目里可以在 Pylint 配置中写[MASTER] ignored-modules sqlalchemy [DESIGN] generated-members query, filter, all, firstgenerated-members是告诉 Pylint这些成员是动态生成的不用查了。这个设置比全局 disable 精准得多不会放过模型里真正的笔误。6.2 处理误报的正确姿势先讨论再忽略我在团队里推行过一个规矩任何想增加的 ignore 都必须带注释说明理由。比如测试文件里某个规则被忽略注释要写出该文件服务于测试夹具参数不传默认值是有意的。这样半年后再有人看到这些豁免不会一头雾水不敢删也不敢改。更重要的次序是先确认是工具理解不了业务还是代码确实不健康。有几次我以为是 Pylint 误报后来仔细一看才发现是自己代码里隐藏了真实问题——一个函数确实参数太多只是恰好在当前业务里没出事。遇到规则和你直觉冲突时先读一遍规则文档再决定是改代码还是豁免规则。大部分时候改代码是更好的选择。6.3 降噪三板斧第一板斧是控制规则范围别默认全开。Pylint 的 disable 列表可以精简到只剩你真正在乎的规则。第二板斧是分层执行Flake8 在提交前跑Pylint 在 CI 跑别让慢的、严的检查打断高频操作。第三板斧是设定基线而不是清零目标先让输出数量可视化看着数字一点点下降比逼团队一次性清零有效得多。如果团队刚引入工具我的建议是前两周只观察不设硬性门禁让大家习惯输出格式第三周开始启用 Flake8 门禁一个月后再把 Pylint 的分线数纳入合并标准。节奏比力度重要。6.4 定期复盘规则规则不是一成不变的。我习惯每个迭代结束后看一眼两份检查报告删掉那些从没触发过的 disable 项或者根据新出现的高频告警补充规则。有过一次很典型的经历项目里所有模块都允许缺少 docstring后来接口越来越多新同事对接时经常需要猜函数用途我们就在复盘里把 C0116 重新打开了只给公共模块加豁免。工具的配置会跟着团队的认知一起演化只要它还在版本控制里就随时可以安全地调整。把规则当成一个活的东西来维护而不是装完就再也不碰的静态文件。7. 几个让我少走弯路的落地习惯7.1 配置和流程上的三个细节讲几个工具之外的习惯这几条才是让整套方案真正发挥价值的点。第一配置文件必须进版本库。团队里任何一个人改了配置其他人通过代码评审就能看到规则演化全程有记录。第二只检查改动文件比检查全库更有执行力。git 的暂存机制配合 pre-commit 天然只处理本次改动的文件这既快又能让新代码必须干净这件事变得无路可退。第三把检查器和格式化工具组合起来用。静态检查负责指出问题格式化工具负责自动修排版两者不重叠但能互相配合。我们项目里约定先格式化再检查这样 E 类错误基本被消灭剩下的告警都是真正需要人看的逻辑问题。7.2 工具之外的一点体会最后说一点我个人的体会工具的价值不在于把代码变成零警告的完美状态而在于让团队对什么算好代码达成共识。装了 Pylint 和 Flake8 之后评审里的风格争论几乎消失了每个人按同一套标准写代码沟通成本降了一大截。如果你正在为代码评审里的琐碎争执头疼不妨先让机器把底线管起来。你会发现省下来的不只是时间还有整个团队在细节问题上反复拉扯的耐心。