Python `ruff` / `flake8`：代码风格检查与 Linting 规则定制

好的，各位观众，欢迎来到今天的“Python 代码质量提升秘籍：Ruff 和 Flake8 的那些事儿”讲座现场！我是今天的分享人，一个在代码的海洋里扑腾多年，头发日渐稀疏的程序猿。今天咱们就来聊聊如何用 Ruff 和 Flake8 这两把利器，让你的 Python 代码变得更漂亮、更易读、更易维护，最终让你成为团队里最靓的仔！

开场白：代码界的“颜值即正义”

话说回来，咱们写代码，不光要能跑，还要能“看”。想象一下，你接手了一个项目，打开一看，代码风格乱七八糟，变量命名毫无规律，注释比代码还少，你的内心是不是瞬间崩溃？没错，这就是代码质量的重要性。好的代码风格，就像一个穿着得体的帅哥美女，让人赏心悦目，而糟糕的代码风格，就像一个蓬头垢面的邋遢大叔，让人避之不及。

所以，代码界的“颜值即正义”可不是随便说说的。代码风格的好坏，直接影响到代码的可读性、可维护性、可扩展性，甚至影响到整个团队的开发效率。

第一部分：Flake8：老牌劲旅，值得信赖

Flake8，作为 Python 代码风格检查的老牌劲旅，已经陪伴了我们很多年。它就像一位经验丰富的老师傅，能帮你找出代码中的各种问题，比如：

• 语法错误：比如少了冒号、括号不匹配等等。
• 命名规范：比如变量名不符合 PEP 8 规范。
• 代码复杂度：比如函数过于复杂，需要拆分。
• 潜在 Bug：比如未使用的变量、导入但未使用的模块等等。

1. Flake8 的安装与配置

安装 Flake8 非常简单，只需一条命令：

pip install flake8

安装完成后，就可以在命令行中使用 flake8 命令来检查你的代码了。

flake8 your_python_file.py

Flake8 默认会检查代码是否符合 PEP 8 规范。如果想自定义规则，可以通过配置文件来实现。Flake8 支持多种配置文件格式，比如 .flake8、setup.cfg、tox.ini 等等。

例如，我们创建一个 .flake8 文件，内容如下：

[flake8]
ignore = E501,W503
max-line-length = 120
exclude = .git,__pycache__,docs

这个配置文件的意思是：

• ignore = E501,W503：忽略 E501（行长度超过 79 字符）和 W503（行前有换行符）的错误。
• max-line-length = 120：设置最大行长度为 120 字符。
• exclude = .git,__pycache__,docs：排除 .git 目录、__pycache__ 目录和 docs 目录下的文件。

2. Flake8 的常用插件

Flake8 本身的功能已经很强大了，但通过安装插件，可以进一步扩展其功能。常用的 Flake8 插件包括：

• flake8-bugbear：用于检测潜在的 Bug。
• flake8-comprehensions：用于检查列表推导式和生成器表达式的使用。
• flake8-import-order：用于检查导入语句的顺序。
• flake8-docstrings：用于检查文档字符串的规范。
• flake8-annotations：用于检查类型注解的使用。

安装这些插件也非常简单，只需使用 pip 命令即可：

pip install flake8-bugbear flake8-comprehensions flake8-import-order flake8-docstrings flake8-annotations

安装完成后，Flake8 会自动加载这些插件，并在检查代码时应用它们。

3. Flake8 的使用示例

假设我们有以下 Python 代码：

def my_function(a, b):
    """
    This is a function that adds two numbers.
    """
    result = a + b
    return result

x = 1
y = 2
print(my_function(x,y))

使用 flake8 命令检查这段代码：

flake8 your_python_file.py

Flake8 可能会给出以下错误提示：

your_python_file.py:1:1: D100 Missing docstring in public module
your_python_file.py:1:1: D103 Missing docstring in public function
your_python_file.py:8:1: E302 Expected 2 blank lines, found 0

这些错误提示的意思是：

• D100 Missing docstring in public module：模块缺少文档字符串。
• D103 Missing docstring in public function：函数缺少文档字符串。
• E302 Expected 2 blank lines, found 0：期望两个空行，实际找到 0 个。

根据这些错误提示，我们可以修改代码如下：

"""
This is a module that contains a function that adds two numbers.
"""

def my_function(a, b):
    """
    This is a function that adds two numbers.
    """
    result = a + b
    return result

x = 1
y = 2
print(my_function(x, y))

修改后的代码符合 Flake8 的规范，再次运行 flake8 命令，就不会再有错误提示了。

第二部分：Ruff：后起之秀，速度惊人

Ruff，作为 Python 代码风格检查的后起之秀，以其惊人的速度和强大的功能，迅速赢得了开发者的喜爱。它就像一位年轻力壮的小伙子，不仅能完成老师傅的任务，而且速度更快、效率更高。

1. Ruff 的优势

Ruff 相比 Flake8，具有以下优势：

• 速度更快：Ruff 使用 Rust 编写，性能远超 Flake8。
• 功能更强：Ruff 集成了大量的 Flake8 插件，开箱即用。
• 自动修复：Ruff 可以自动修复一些常见的代码风格问题。
• 更易配置：Ruff 的配置更加简单直观。

2. Ruff 的安装与配置

安装 Ruff 也非常简单，只需一条命令：

pip install ruff

安装完成后，就可以在命令行中使用 ruff 命令来检查你的代码了。

ruff check your_python_file.py

Ruff 默认会检查代码是否符合 PEP 8 规范，并提供一些额外的检查。如果想自定义规则，可以通过配置文件来实现。Ruff 支持 pyproject.toml 配置文件。

例如，我们创建一个 pyproject.toml 文件，内容如下：

[tool.ruff]
line-length = 120
select = ["E", "W", "F", "I"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["D"]

这个配置文件的意思是：

• line-length = 120：设置最大行长度为 120 字符。
• select = ["E", "W", "F", "I"]：选择要检查的错误类型，包括 E（错误）、W（警告）、F（Flake8 错误）和 I（导入错误）。
• ignore = ["E501"]：忽略 E501（行长度超过 79 字符）的错误。
• [tool.ruff.lint.per-file-ignores]：针对特定文件或目录，忽略特定的错误类型。
  • "tests/*" = ["D"]：忽略 tests 目录下所有文件的文档字符串错误。

3. Ruff 的自动修复功能

Ruff 最大的亮点之一就是其自动修复功能。使用 --fix 参数，Ruff 可以自动修复一些常见的代码风格问题，比如：

• 删除多余的空格
• 调整导入语句的顺序
• 添加缺失的换行符

例如，运行以下命令：

ruff check your_python_file.py --fix

Ruff 会自动修复 your_python_file.py 文件中的一些代码风格问题。

4. Ruff 的使用示例

假设我们有以下 Python 代码：

def add(x,y):
    return x+ y

print(add(1,  2))

使用 ruff check 命令检查这段代码：

ruff check your_python_file.py

Ruff 可能会给出以下错误提示：

your_python_file.py:1:1: E302 Expected 2 blank lines, found 0
your_python_file.py:1:8: E225 Missing whitespace around operator
your_python_file.py:4:10: E203 Whitespace before ':'

这些错误提示的意思是：

• E302 Expected 2 blank lines, found 0：期望两个空行，实际找到 0 个。
• E225 Missing whitespace around operator：运算符周围缺少空格。
• E203 Whitespace before ':'：冒号前有空格。

使用 ruff check --fix 命令自动修复这段代码：

ruff check your_python_file.py --fix

Ruff 会自动修复代码如下：

def add(x, y):
    return x + y

print(add(1, 2))

可以看到，Ruff 自动添加了空行，并在运算符周围添加了空格，使代码更符合 PEP 8 规范。

第三部分：Flake8 vs Ruff：如何选择？

既然 Flake8 和 Ruff 都是 Python 代码风格检查的利器，那么我们应该如何选择呢？

特性	Flake8	Ruff
性能	较慢	极快
功能	需要安装插件才能扩展功能	集成了大量功能，开箱即用
自动修复	不支持	支持
配置	较为繁琐	简单直观
社区支持	成熟，插件丰富	快速发展，社区活跃

总的来说，如果你的项目已经使用了 Flake8，并且对现有的配置和插件非常熟悉，那么可以继续使用 Flake8。但如果你是新项目，或者希望提高代码检查的速度和效率，那么强烈建议使用 Ruff。

第四部分：定制你的代码风格规则

无论是 Flake8 还是 Ruff，都允许你定制自己的代码风格规则。这对于团队协作非常重要，可以确保团队成员的代码风格保持一致。

1. 制定团队代码风格规范

首先，需要制定一份清晰、详细的代码风格规范。这份规范应该包括以下内容：

• 命名规范：变量、函数、类、模块的命名规则。
• 代码布局：缩进、空格、空行的使用规则。
• 注释规范：文档字符串、行内注释的编写规则。
• 导入规范：导入语句的顺序、格式。
• 其他规范：比如最大行长度、代码复杂度等等。

2. 配置 Flake8 或 Ruff

根据团队的代码风格规范，配置 Flake8 或 Ruff 的配置文件。例如，可以设置最大行长度、忽略特定的错误类型、配置导入语句的顺序等等。

3. 集成到 CI/CD 流程

将 Flake8 或 Ruff 集成到 CI/CD 流程中，可以确保每次提交的代码都符合团队的代码风格规范。如果代码不符合规范，CI/CD 流程会自动失败，从而避免将不规范的代码合并到主分支。

4. 持续改进

代码风格规范不是一成不变的，需要根据实际情况不断改进。可以定期回顾代码风格规范，并根据团队成员的反馈进行调整。

结束语：代码质量，永无止境

各位观众，今天的讲座就到这里了。希望通过今天的分享，大家能够对 Flake8 和 Ruff 有更深入的了解，并能够利用它们来提升你的 Python 代码质量。记住，代码质量的提升是一个持续不断的过程，需要我们不断学习、不断实践、不断改进。

最后，祝大家写出漂亮、易读、易维护的 Python 代码，成为团队里最靓的仔！ 谢谢大家！