Python 代码质量分析与优化工具pylint、black、Ruff，代码检查、分析优化、格式化、漏洞扫描、类型检查、import整理、找出未使用代码，以及在pycharm、vscode 如何配置

原创已于 2025-10-09 14:31:58 修改 · 728 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#python #开发语言

于 2025-09-19 14:11:33 首次发布

python基础专栏收录该内容

65 篇文章

订阅专栏

一、背景

代码像垃圾一样，混乱、不可读、难维护
缩进乱、命名怪、满屏红色警告
程序流程不清，跳转随意，难以理解
屎一样代码，结构混乱、层层嵌套
实在难以下咽，噎人

这篇讲了8个代码优化工具，像保证代码写的像诗歌一样

名称	主要功能	特点
ruff	代码检测、简化、优化	极快、支持 pyproject.toml，可替代 flake8 + isort + autopep8 + pylint 部分功能
pylint	最全面的静态分析	规则最丰富，检出率高，可自定义插件，速度较慢
black	自动格式化代码	零配置、风格统一、不可微调，“所见即所得”
isort	自动整理 import 语句	支持按字母/长度分组、与 black 无缝配合
mypy	静态类型检查	基于 PEP 484/561，渐进式类型系统，可集成 CI
flake8	轻量级代码风格检查	组合 pyflakes + pycodestyle + mccabe，插件生态丰富
autopep8	自动修复 PEP 8 错误	直接按 PEP 8 规则修正格式，保守无侵入
vulture	找出未使用代码	检测死代码、未导入/未调用的函数与变量
bandit	安全漏洞扫描	专注常见安全问题（如 exec、assert、硬编码密钥等）

二、ruff 代码检测、代码简化、优化工具

提升代码质量和可维护性
发现代码中的错误、不符合规范的地方、潜在 bug 等

工具	功能	速度	推荐用途
`ruff`	✅ lint + ✅ format	⚡⚡⚡ 极快	✅ 新项目首选
`flake8`	✅ lint	🐢 慢	❌ 旧项目兼容
`black`	❌ lint	✅ format	🔄 可被 ruff format 替代
`isort`	❌ lint	✅ sort imports	✅ 已集成进 Ruff
`pylint`	✅ lint（更严格）	🐌 很慢	🟡 复杂项目仍可用

`Ruff —— 优雅Python代码的秘密`

功能：核心功能包括代码格式化和静态错误检查（即Linter）

特性	说明
📦 类型	Python 静态分析工具（linter）
⚡ 语言	用 Rust 实现，性能极高
✅ 功能	替代 `flake8` + `isort` + `pyupgrade` + `pydocstyle` 等
🎯 定位	“Fastest linter out there” —— 极速 linting

核心功能

代码风格【替代 flake8】: 检查 PEP 8 风格违规（如 E302、W503）
代码风格【替代 flake8】: 支持超过 100 种规则（来自 flake8 插件生态）
自动排序【替代 isort】: import 自动按标准库、第三方、本地模块分组排序
自动排序【替代 isort】: 可配置是否启用
修复问题【–fix】: ruff check --fix . 自动修复大多数常见问题（如多余空行、import 顺序、括号格式等）
代码建议【替代 pyupgrade】: 建议将 % 格式化改为 f-string
代码建议【替代 pyupgrade】: 将 typing.Optional[str] 改为 str | None
代码建议【替代 pyupgrade】: 删除废弃语法
忽略特定规则:支持 .ruff.toml 或 pyproject.toml 配置，灵活控制规则

安装：

# 推荐方式：pip
pip install ruff
pip install "ruff[format]"

# 或使用 conda
conda install -c conda-forge ruff

# 或使用 brew (macOS)
brew install ruff

# 验证安装
ruff --version

🛠️ 基本使用命令

功能分类	命令	说明
扫描	`ruff .` 或 `ruff check .`	扫描当前目录所有 `.py` 文件
扫描	`ruff check main.py`	扫描单个文件
修复	`ruff check --fix .`	自动修复可修复的问题
实验性功能	`ruff check --preview .`	启用实验性规则（如新的安全检测）
修复	`ruff src --fix`	修复某个文件夹中的所有文件
修复	`ruff src/*/.py --fix`	修复 `src` 文件夹下的所有 `.py` 文件
规则控制	`ruff . --select F401`	只检查指定的规则（如未使用的导入）
规则控制	`ruff . --ignore E501`	忽略指定的规则（如行宽限制）
规则控制	`ruff check . --select E,F`	只检查指定的规则（如 `E` 代表 PEP 8 错误，`F` 代表 Pyflakes 错误）
规则控制	`ruff check . --ignore E501,W605`	忽略特定规则（如行长限制 E501 和原始字符串警告 W605）
信息显示	`ruff check . --show-source`	显示问题代码片段，帮助定位问题所在的代码行
信息显示	`ruff check . --show-fixes`	显示自动修复建议的前后对比
信息显示	`ruff check . --statistics`	按问题类型统计数量（如 E301 出现次数 5 次）
输出格式	`ruff check . --output-format=json`	以 JSON 格式输出结果，便于机器解析（适合 CI/CD 集成）
配置管理	`ruff check . --config=pyproject.toml`	使用指定的配置文件路径（默认自动查找）
缓存管理	`ruff check . --no-cache`	禁用缓存，强制重新扫描代码（用于调试）
排除目录	`ruff check . --exclude migrations/ --extend-exclude tests/`	排除特定目录（如数据库迁移、测试代码）
格式化	`ruff format .`	格式化代码（需安装 `ruff[format]`）⚠️ 见下文
格式化	`ruff format . --check`	检查哪些文件需要格式化，而不实际修改文件（常用于 CI/CD 流程）
格式化	`ruff format . --diff`	显示格式化后的差异以预览修改内容
格式化	`ruff format main.py app/`	格式化指定文件和目录
格式化	`ruff format . --config=.ruff.toml`	使用自定义配置文件进行格式化
规则说明	`ruff rule E302`	查看指定规则的详细说明（如 `E302: expected 2 blank lines`）
规则说明	`ruff linter`	列出所有支持的规则代码（可结合 `grep` 过滤）
缓存管理	`ruff clean`	清除 Ruff 内部缓存（用于解决可能的缓存问题）
工作目录	`ruff --work-dir /path/to/dir`	指定 Ruff 执行时的工作目录
文件类型	`ruff check --type py`	指定要检查的文件类型（假设 Ruff 支持）
输出详细	`ruff --verbose`	启用详细输出模式，提供更多调试信息

配置文件示例（pyproject.toml）

# pyproject.toml
[tool.ruff]
select = [
    "E",   # flake8 错误
    "W",   # 警告
    "F",   # pyflakes
    "I",   # isort
    "UP",  # pyupgrade
    "B",   # bugbear
]
ignore = ["E501"]  # 忽略行长度限制（或用 E402 等）

# 启用 fix（自动修复）
fixable = ["ALL"]
unfixable = []

# 行长度
line-length = 88

# target-version（影响 pyupgrade 规则）
target-version = "py310"

三、代码检测、代码简化、优化工具

`2.1 pylint —— 最全面的静态分析工具`

功能：检查代码风格、错误、未使用变量、命名规范、模块结构等
安装：
```
pip install pylint
```
命令使用:
```
pylint your_script.py 检查某个py文件
pylint ./api/         检查某个文件夹
```
输出包括评分（如 8.56/10）、问题分类（E=错误, W=警告, C=约定, R=重构建议）

`2.2 black —— 自动格式化工具Black`

功能：自动格式化代码，符合统一风格（PEP 8）
安装：
```
pip install black
```

命令使用:

blackyour_script.py 检查某个py文件
black ./api/         检查某个文件夹

`2.3 isort —— 自动整理 import 语句`

功能：按字母顺序排序导入，并分组标准库、第三方库、本地库
安装：
```
pip install isort
```

命令使用:

isort your_script.py 检查某个py文件
isort ./api/         检查某个文件夹

`2.4 mypy —— 类型检查工具（Type Checker）`

功能：检查类型注解是否正确，提前发现类型相关 bug
安装：
```
pip install mypy
```
使用：
```
mypy your_script.py
```

示例：

def add(a: int, b: int) -> int:
    return a + b

`2.5 flake8 —— 轻量级代码风格检查器`

功能：结合了 pyflakes（语法检查）、pep8（风格检查）、mccabe（复杂度检测）
安装：
```
pip install flake8
```
使用：
```
flake8 your_script.py
```
适合 CI/CD 中快速检查代码是否符合 PEP 8 规范

`2.6 autopep8 —— 自动修复 PEP 8 错误`

安装：
```
pip install autopep8
```

使用：

autopep8 --in-place --aggressive your_script.py

`2.7 vulture —— 找出未使用代码`

功能：找出未使用的函数、变量、类等
安装：
```
pip install vulture
```

使用：

vulture your_script.py

vulture myscript.py  # or
python3 -m vulture myscript.py
vulture myscript.py mypackage/
vulture myscript.py --min-confidence 100  # Only report 100% dead code.

帮助“减产”——减少无用代码！

`2.8 bandit —— 安全漏洞扫描工具`

功能：检测常见的安全问题（如硬编码密码、命令注入、不安全的 eval、pickle等）
安装：
```
pip install bandit
```
使用：
```
bandit -r your_project/
```

2.9 radonPython 代码质量分析工具

一款强大的 Python 代码度量工具，它能够计算多种代码指标，
McCabe复杂度，即圈复杂度
原始指标（包括 SLOC、注释行、空白行等）
Halstead指标（全部）
可维护性指数（Visual Studio 中使用的指数）
适用于 Python 代码质量评估和持续集成等场景。
安装
```
$ pip install radon
```

$ radon cc sympy/solvers/solvers.py -a -nc
sympy/solvers/solvers.py
    F 346:0 solve - F
    F 1093:0 _solve - F
    F 1434:0 _solve_system - F
    F 2647:0 unrad - F
    F 110:0 checksol - F
    F 2238:0 _tsolve - F
    F 2482:0 _invert - F
    F 1862:0 solve_linear_system - E
    F 1781:0 minsolve_linear_system - D
    F 1636:0 solve_linear - D
    F 2382:0 nsolve - C

11 blocks (classes, functions, methods) analyzed.
Average complexity: F (61.0)

四、在Pycharm、VsCode 中添加部分检查插件

PyCharm: 在 PyCharm -> Preferences 里找到 工具 -> Black，设置为保存时自动格式化。
PyCharm: 在 PyCharm -> Preferences 里找到 工具 -> Ruff，设置为保存时自动格式化。
PyCharm: 在 PyCharm -> Preferences 里找到 工具 -> Pylint，设置为保存时自动格式化。

VSCode: 使用这个插件，并且在设置-Text Editor-Formatting 里设置为保存时自动Format。