23.3 代码质量工具 - 人人都会AI编程

上一节讲了 PEP 8 等编码规范的理论要求，但靠人眼逐行检查不仅效率低，还容易漏掉。代码质量工具的作用就是自动化地帮你把关，让规范落地变成一件“保存时自动修，提交前强制查”的事。本节介绍最常用、最务实的三类工具：格式化、代码检查和类型检查。

代码格式化：Black + isort

格式化工具负责自动修正代码风格，让团队成员无论习惯如何，产出的代码形状都高度一致。

Black

口号：“任何你用 Black 格式化的代码，看起来就像同一个人写的。”
特点：零配置，没有选项可争论。它会彻底重排你的代码，使缩进、换行、引号、括号等完全一致。
使用：

  pip install black
  black my_script.py        # 格式化单个文件
  black src/                # 格式化整个目录

推荐：集成到编辑器（VS Code / PyCharm）的“保存时格式化”中，每次 Ctrl+S 自动规整代码。也可以加入 pre-commit 钩子，在提交前自动运行。

isort

作用：专门整理 import 语句的顺序和分组。标准库在前，第三方库在中，本地模块在后，每组之间用空行分隔，字母顺序排列。
使用：

  pip install isort
  isort my_module.py

配合 Black：两者默认配置兼容，一起用不会冲突。大多项目会同时启用。

代码检查（Linter）：flake8 + pylint

格式化解决“样子”问题，Linter 则检查潜在的错误、代码异味、未使用的变量、过于复杂的结构，帮你提高代码质量。

flake8

组成：它其实是三个工具的包装器——PyFlakes（检查逻辑错误）、pycodestyle（检查 PEP 8 风格）、McCabe（检查圈复杂度）。
优势：快速、轻量，报出的问题大多真实有效，误报少。
使用：

  pip install flake8
  flake8 src/ --max-line-length=88

（此处 --max-line-length 应与 Black 的默认 88 一致，避免冲突。）

常见忽略项：有些规则可能不适合你的项目，在项目根目录下创建 .flake8 配置：

  [flake8]
  max-line-length = 88
  extend-ignore = E203, W503

（E203 和 W503 是 Black 与旧版 PEP 8 冲突的规则。）

pylint

定位：比 flake8 更“严格”和深入，会检查代码规范、接口设计、重复代码、文档字符串缺失等，并给出评分。
特点：可配置性强，但默认配置可能非常啰嗦。建议在项目已有一定规模后引入，花时间定制 .pylintrc，不要让初始报告吓跑团队。
使用：

  pip install pylint
  pylint my_module.py

实用建议：把 pylint 放在 CI 流水线中作为最后一道检查，不必要求本地环境处处满分，可以设定一个最低评分阈值。

静态类型检查：mypy

Python 3.5+ 支持类型提示（Type Hints），能让代码可读性更高，也为 IDE 智能提示和重构提供了依据。但类型提示只是注释，运行时并不会检查。mypy 就是可选的静态类型检查器，它能在不运行代码的情况下，校验你的类型标注是否正确。

使用场景：项目体量变大、多人协作时，类型检查能显著降低因为参数类型传递错误导致的 Bug。
使用：

  pip install mypy
  mypy src/

示例：如果写了一个函数 def greet(name: str) -> str:，但调用时传入了 greet(123)，mypy 会立刻报错。
逐步引入：大型老项目可以一次只检查一个模块，或在 mypy.ini 中配置只检查标注过的函数，避免一次性改太多代码。

工具整合与最佳实践

这些工具不是孤立的，常用的工程化方案是：

编辑器集成：在 VS Code / PyCharm 中安装对应插件，让格式化和检查在编码时实时反馈。
pre-commit 钩子：用 pre-commit 框架配置 Black、isort、flake8、mypy 等，在每次 git commit 前自动运行，失败则阻止提交，确保进入仓库的代码都是合格的。
CI/CD 流水线：在 CI（如 GitHub Actions、GitLab CI）中执行同样的检查，作为合并请求的门禁。

一个典型的 .pre-commit-config.yaml 片段：

repos:
  - repo: https://github.com/psf/black
    rev: 23.12.0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy

一句话总结：用 Black + isort 统一格式，用 flake8 拦住低级错误，用 mypy 提前暴露类型隐患，再通过 pre-commit 和 CI 把这一切自动化，代码质量就不再是“靠自觉”的口号，而是可落地的工程习惯。