Python 代码质量：pylint 与 flake8 检查

安装 pylint 和 flake8 工具是提升 Python 代码可读性与规范性的第一步。这两个工具能自动发现代码中的风格问题、潜在错误和不符合 PEP 8 规范的地方。

安装检查工具

1. 打开终端（Windows 用户使用命令提示符或 PowerShell，macOS/Linux 用户使用 Terminal）。
2. 运行以下命令安装两个工具：

   pip install pylint flake8

3. 验证是否安装成功，分别执行：

   pylint --version
   flake8 --version

   如果显示版本号，说明安装完成。

基础用法：直接检查单个文件

假设你有一个名为 example.py 的 Python 文件。

1. 使用 pylint 检查该文件：

   pylint example.py

   输出会包含评分（如 Your code has been rated at 5.00/10）以及具体问题列表，例如变量命名不规范、缺少文档字符串等。

2. 使用 flake8 检查同一文件：

   flake8 example.py

   输出格式为 文件名:行号:列号: 错误代码 错误描述，例如：

   example.py:3:1: E302 expected 2 blank lines, found 1

注意：pylint 默认规则较严格，而 flake8 更聚焦于 PEP 8 风格和语法错误。

配置忽略规则

项目中某些警告可能无需处理（如临时调试代码）。可通过配置文件自定义忽略项。

为 flake8 创建配置

1. 在项目根目录下创建文件 .flake8 或 setup.cfg。
2. 编辑 .flake8 内容如下（以忽略特定错误为例）：

   [flake8]
   ignore = E203, W503
   max-line-length = 88
   exclude = .git,__pycache__,venv

   • ignore：跳过指定错误码（E203 是空格问题，W503 是行延续符位置）。
   • max-line-length：允许每行最长字符数（Black 格式化器常用 88）。
   • exclude：不检查的目录或文件。

为 pylint 创建配置

1. 生成默认配置文件：

   pylint --generate-rcfile > .pylintrc

2. 编辑 .pylintrc 文件，找到 [MESSAGES CONTROL] 部分，修改 disable 行：

   disable=missing-docstring,
           invalid-name,
           too-few-public-methods

   上述配置将忽略“缺少文档字符串”、“无效变量名”和“公共方法太少”三类警告。

配置文件必须放在项目根目录，工具会自动读取。

在项目中批量检查

大型项目通常包含多个 Python 文件，需一次性检查全部代码。

1. 进入项目根目录（确保 .flake8 和 .pylintrc 已存在）。
2. 运行 flake8 检查整个目录：

   flake8 .

3. 运行 pylint 检查整个目录：

   pylint .

若只想检查特定子目录（如 src/），替换 . 为目录名即可。

集成到开发流程

将检查步骤嵌入开发习惯，可在提交代码前自动拦截低质量代码。

使用 pre-commit 钩子

1. 安装 pre-commit：

   pip install pre-commit

2. 在项目根目录创建 .pre-commit-config.yaml 文件，内容如下：

   repos:
     - repo: https://github.com/pycqa/flake8
       rev: 7.0.0
       hooks:
         - id: flake8
     - repo: https://github.com/pycqa/pylint
       rev: v3.0.3
       hooks:
         - id: pylint
           args: ["--rcfile=.pylintrc"]

3. 安装钩子：

   pre-commit install

4. 下次执行 git commit 时，系统会自动运行 flake8 和 pylint。若检查失败，提交将被阻止。

常见错误码速查表

以下列出高频出现的问题及其含义，帮助快速定位修复。

选择建议：何时用哪个？

根据团队目标决定主用工具：

• 追求严格质量控制：优先使用 pylint。它能检测逻辑漏洞（如未定义变量、类型不匹配），适合长期维护项目。
• 仅需风格统一：使用 flake8。它轻量、快速，与 Black、isort 等格式化工具配合更流畅。
• 最佳实践：两者同时使用。flake8 负责基础风格，pylint 负责深层逻辑，互补无冲突。

运行 flake8 快速过一遍风格，再用 pylint 深度扫描，是高效组合。