基于pre-commit的Python代码规范落地实践

郑文峰的博客

使用dify对接飞书多维表格使用n8n对接飞书多维表格服务启动时出现 OOM 一次服务升级时pg表DDL执行超时失败 Go语言高效IO缓冲技术详解 Go语言延迟初始化(Lazy Initialization)最佳实践 Go语言字符串拼接性能对比与优化指南 Go语言结构体内存对齐完全指南 Go语言空结构体：零内存消耗的高效编程 Go语言堆栈分配与逃逸分析深度解析 Go语言原子操作完全指南 Go语言内存预分配完全指南 Go语言不可变数据共享：无锁并发编程实践 Go语言零拷贝技术完全指南 Go语言遍历性能深度解析：从原理到优化实践 Go语言Interface Boxing原理与性能优化指南 Go协程池深度解析：原理、实现与最佳实践使用etcd分布式锁导致的协程泄露与死锁问题初识 MCP Server pulsar阻塞导致logstash无法接入日志 django-prometheus使用及源码分析 kube-proxy源码分析 kubernetes service如何通过iptables转发 tcp缓存引起的日志丢失 django-apschedule定时任务异常停止理解calico容器网络通信方案原理理解flannel的三种容器网络方案原理理解Linux IPIP隧道理解VXLAN网络理解Linux TunTap设备快速了解iptables kafka中listener和advertised.listeners的作用 django rest_framework 分页 django后端服务、logstash和flink接入VictoriaMetrics指标监控 python中import原理 docker容器单机网络手动实现docker容器bridge网络模型 mysql之MVCC原理 mysql之日志使用java开发logstash的filter插件使用python实现单例模式的三种方式 redis之缓存 redis之分片集群 redis之哨兵机制 redis之主从库同步 redis之持久化 redis之五种基本数据类型 go中如何处理error pod中将代码与运行环境分离 ddt源码分析 python装饰器的使用方法读书笔记:如何阅读一本书使用ddt实现unittest的参数化测试使用kubeadm安装k8s 优化gin表单的错误提示信息 gin中validator模块的源码分析 go简单使用grpc python简单使用grpc k8s之PV、PVC和StorageClass k8s之StatefulSet k8s之DaemonSet k8s之Job和CronJob k8s之ConfigMap和Secret k8s之Service k8s之Pod k8s之Deployment 容器的本质 docker容器 python迭代器与生成器 python元编程 python垃圾回收机制 python上下文管理器 django rest_framework使用jwt django rest_framework异常处理 django rest_framework 自定义文档 django压缩文件下载 django rest_framework使用pytest单元测试 django restframework choice 自定义输出数据 django Filtering 使用 django viewset 和 Router 配合使用时报的错 django model的序列化 django中使用AbStractUser django.core.exceptions.ImproperlyConfigured Application labels aren't unique, duplicates users django 中 media配置 django 外键引用自身和on_delete参数 django 警告 while time zone support is active Flask使用flask_socketio实现websocket flask结合mongo tornado 文件上传 tornado 使用jwt完成用户异步认证 tornado 用户密码 bcrypt加密 tornado 结合wtforms使用表单操作 tornado finish和write区别 tornado 使用peewee-async 完成异步orm数据库操作 pyspark streaming简介和消费 kafka示例使用hue创建ozzie的pyspark action workflow count的性能优化 django rest_framework Authentication django celery 结合使用网站

zhengwenfeng · 2025-05-12 · via 郑文峰的博客

# 简介

pre-commit 是一个开源工具，用于管理和执行 Git 钩子，确保代码库的一致性和质量。通过在提交代码前自动运行代码风格检查（Linting）和格式修正（Formatting），它有助于保持项目代码的统一标准。本文将通过一个 Python 项目的实例，展示如何配置 pre-commit 工作流。

本文旨在介绍使用 pre-commit 对 Python 项目进行代码检查的方法，以提前发现并解决代码中的问题，提高代码的整体质量。文中提及的所有代码示例可以在 pre-commit-demo (opens new window) 找到。

# 使用

安装

首先，安装 pre-commit：

安装成功后，您可以通过以下命令验证安装是否成功：

$ pre-commit --version 
pre-commit 4.2.0

1
2

接下来，设置 Git 钩子脚本：

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

1
2

创建配置文件在项目的根目录下创建 .pre-commit-config.yaml 文件，并推荐使用最新稳定版：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: check-yaml
      - id: check-json
      - id: check-toml
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/isort
    rev: 5.13.2
    hooks:
      - id: isort
  - repo: https://github.com/PyCQA/flake8
    rev: 7.2.0
    hooks:
      - id: flake8

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

配置文件说明:

repos: 包含要使用的仓库列表。
repo: 每个仓库的 URL。
rev: 版本号，建议使用最新稳定版。
hooks: 需要执行的钩子列表。
id: 各个钩子的标识符。

每个钩子 ID 的具体作用可参考相应仓库的官方文档。

执行与应用

在执行 commit 命令时，会自动调用配置文件中定义的钩子脚本，检查代码是否符合规范。例如：

$ pre-commit_demo % git add *
$ pre-commit_demo % git commit -m "add main.py"
Check Yaml...........................................(no files to check)Skipped
Check JSON...........................................(no files to check)Skipped
Check Toml...........................................(no files to check)Skipped
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
[main 27890fe] add main.py
 1 file changed, 1 insertion(+)
 create mode 100644 main.py

1
2
3
4
5
6
7
8
9
10
11
12
13

默认情况下，仅检查新添加或修改的文件。若需手动检查所有文件，可以使用如下命令：

$ pre-commit run --all-files
Check Yaml...............................................................Passed
Check JSON...........................................(no files to check)Skipped
Check Toml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed

1
2
3
4
5
6
7
8
9

如需临时跳过校验，可在 commit 命令中加上 --no-verify 参数：

$ git commit -m "add main.py" --no-verify

# 最佳实践

将.pre-commit-config.yaml纳入版本控制，确保团队配置一致
定期运行pre-commit autoupdate保持工具最新版本
优先修复而不是--no-verify，让规范成为肌肉记忆.

# 总结

通过本文的实践，我们已经为Python项目搭建了自动化代码质检流水线。pre-commit 就像一位尽职的代码审查员，帮我们做到：

规范守护者：自动执行代码格式化（Black/isort）和静态检查（flake8）
效率加速器：拦截问题在提交前，避免CI/CD环节反复返工
团队协作者：统一项目代码风格，降低多人协作成本

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

郑文峰的博客

# 简介

# 使用

# 最佳实践

# 总结