代码规范与自动化工具
约 984 字大约 3 分钟
2026-02-06
团队开发中，代码规范是基础，手动检查效率低且易遗漏，通过自动化工具强制遵循PEP8（Python 官方代码风格指南），保证所有开发者的代码风格一致，减少代码评审中的风格争议。
自动化工具三件套
| 工具名 | 核心作用 | 核心特性 | 核心命令 |
|---|---|---|---|
| flake8 | 代码规范检查 | 检查 PEP8 规范 + 语法错误 + 代码复杂度，仅检查不修复 | flake8 src/ tests/ |
| black | 代码自动格式化 | 强制 PEP8 规范，自动修复缩进 / 行宽 / 命名等问题，无配置项（减少争议） | black src/ tests/ |
| isort | 导入语句自动排序 | 按 PEP8 规范自动排序导入语句（标准库→第三方库→自定义库），可与 black 配合 | isort src/ tests/ |
工具安装与使用
# 安装（开发环境，添加到requirements-dev.txt/Poetry dev依赖）
pip install flake8 black isort -i https://mirrors.aliyun.com/pypi/simple/
# 核心命令（项目根目录执行）
isort src/ tests/ # 自动排序导入语句
black src/ tests/ # 自动格式化代码
flake8 src/ tests/ # 检查代码规范，无输出则表示无问题
# 组合命令（一行执行，推荐在代码提交前执行）
isort src/ tests/ && black src/ tests/ && flake8 src/ tests/编辑器配置（VS Code/PyCharm）
VS Code：安装 Python 插件，在settings.json中添加以下配置，实现保存时自动执行 isort+black：
{
"editor.formatOnSave": true,
"python.formatting.provider": "black",
"editor.codeActionsOnSave": {
"source.organizeImports": true
},
"python.analysis.typeCheckingMode": "basic"
}PyCharm：安装Black/isort插件，在Settings → Tools → Black/isort中配置工具路径，开启On Save自动格式化。
提交前检查：pre-commit 钩子（团队开发推荐）
通过pre-commit在Git 提交代码前自动执行代码规范检查 / 格式化，避免不符合规范的代码提交到 Git 仓库，从源头保证代码质量。
pre-commit 核心命令
# 1. 安装pre-commit
pip install pre-commit -i https://mirrors.aliyun.com/pypi/simple/
# 2. 项目根目录创建.pre-commit-config.yaml（配置钩子）
# 示例配置（包含isort/black/flake8）
repos:
- repo: https://github.com/pycqa/isort
rev: 5.12.0
hooks:
- id: isort
args: ["--profile", "black"] # 与black兼容
- repo: https://github.com/psf/black
rev: 23.11.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/pycqa/flake8
rev: 6.1.0
hooks:
- id: flake8
args: ["--max-line-length", "88"]
# 3. 安装钩子到Git
pre-commit install
# 4. 手动执行所有钩子（检查所有文件）
pre-commit run --all-files关键特性
- 提交前自动执行：执行
git commit时，会自动对提交的文件执行钩子（isort/black/flake8），若检查失败，提交会被终止，需修复后重新提交； - 增量检查：仅对修改的文件执行检查，效率高；
- 可扩展性：支持添加更多钩子，如mypy（类型检查）、pytest（单元测试）、bandit（安全检查）等。
版本控制：Git 核心规范（团队协作必备）
Git 是 Python 开发的标准版本控制工具，团队开发中需遵循统一的 Git 规范，保证提交记录清晰、可追溯，便于代码回滚、分支管理和 Code Review。
Git 分支管理规范
Git Flow 是一套成熟的 Git 分支管理策略，适合中大型团队和长期维护的项目，核心分支如下：
| 分支名 | 核心作用 | 生命周期 | 合并规则 |
|---|---|---|---|
main/master | 生产环境分支，存放可发布的稳定代码 | 永久 | 仅从develop/hotfix分支合并 |
develop | 开发主分支，存放最新的开发代码 | 永久 | 从feature/release分支合并 |
feature/xxx | 功能分支，开发新功能 | 临时，功能完成后删除 | 合并到develop分支 |
release/xxx | 发布分支，准备发布生产环境，仅修复 bug | 临时，发布完成后删除 | 合并到main和develop分支 |
hotfix/xxx | 热修复分支，修复生产环境的紧急 bug | 临时，修复完成后删除 | 合并到main和develop分支 |
分支命名规范
- 功能分支：
feature/功能名，如feature/user-login/feature/data-import； - 发布分支：
release/版本号，如release/v1.0.0/release/v1.1.0； - 热修复分支：
hotfix/bug描述，如hotfix/redis-connection-error/hotfix/user-info-null。