基于实战经验的 Python 代码交付质量检查清单

这篇文章是我基于近3年从事Python相关外包项目并交付代码的经验总结而成的，旨在提供一份提升Python代码质量的检查清单。

由于这是基于我个人的外包经验编写的内容，因此与平时的文章不同，没有引用任何论文来源。

因此，这篇文章将仅对粉丝公开，而不是完全公开。

如果有任何不清楚的地方，请随时提问！

本文档提供了在外包开发项目中交付代码时必须审查的质量标准。
目标不仅是临时运行，而是确保可持续的维护和可重用的结构 。

0. 虚拟环境工具选择指南

在外包项目中，可重现的运行环境是必不可少的。
特别是在 Python 项目中，虚拟环境工具的选择与运行成功与否密切相关。

在 Python 中，默认可以使用 venv 和 pip 来构建虚拟环境。
然而，最近出现了许多更快速、更集成的工具，可以根据团队规模或项目目标进行选择：

• venv + pip : 最普遍的选择，适用于标准环境搭建。
• poetry : 同时管理依赖和打包，适合重视可重现性和构建质量的场景。
• uv : 如果需要更快的安装速度，可以考虑（可替代 pip）。
• rye : 一个实验性工具，集成了虚拟环境、依赖管理、构建和运行功能。

近期备受关注的 uv 是由 Astral 开发的超高速 Python 包管理器 。

• 它旨在替代 poetry、pip、pip-tools 和 virtualenv 等工具。

• poetry 在依赖解析和安装速度上存在较慢的问题，并且内部也有关于 resolver 性能的争议 。

• uv 改进了所有这些问题，支持通过单个二进制文件实现虚拟环境创建 + 依赖解析 + 安装 。

在外包交付时，必须文档化安装方法和使用方法 ，
如果使用了最新的工具，务必在 README.md 中清楚说明。

---

1. 目录结构（是否结构化）

项目	检查	说明
src/,core/等功能文件夹区分	☐	功能责任分离情况
执行脚本不在根目录，而在entrypoints/中	☐	不要将main.py放在根目录
测试文件夹(tests/)分离	☐	用于判断测试覆盖率的可能性
配置文件夹(config/)分离	☐	不同运行环境的配置分离
文档文件夹(docs/)单独构成	☐	API文档、用户指南等

---

2. 模块化和__init__.py

项目	检查	说明
每个子文件夹包含__init__.py	☐	需要被识别为包并支持import
内部函数、类通过__all__控制导出	☐	明确API设计
使用模块级import而非相对路径import	☐	确保结构扩展性
无循环引用(circular import)	☐	检查模块间的依赖图
遵守单一责任原则	☐	每个模块仅承担一个明确的责任

---

3. 执行入口点(Entrypoint)分离

项目	检查	说明
if __name__ == "__main__"位置明确	☐	防止模块导入时自动执行
工具功能与执行脚本分离	☐	功能通过import实现，执行仅在main中进行
提供CLI接口 (argparse,click等)	☐	提供命令行执行选项
分离Web API入口点（如适用）	☐	API服务器运行与逻辑分离
脚本执行指南文档化	☐	包含使用说明

---

4. 打包/可重现性

项目	检查	说明
包含requirements.txt或pyproject.toml	☐	依赖项声明情况
虚拟环境重现文档 (venv,poetry,conda等)	☐	确保环境移植性
在setup.py或pyproject.toml中填写元信息	☐	判断是否可打包
开发/生产环境分离 (dev-requirements.txt)	☐	开发工具与生产依赖分离
存在版本管理策略 (semantic versioning)	☐	包版本管理方式
执行包安装测试	☐	确认实际可安装

5. 配置/敏感信息分离

项目	检查	说明
通过.env,config.yaml等分离环境	☐	API Key、数据库信息等不应硬编码到代码中
通过dotenv或configparser等方式加载	☐	运行环境与代码应分离
Git中未提交敏感信息（.gitignore）	☐	防止安全风险
提供环境配置文件模板	☐	区分开发/测试/生产环境
记录敏感信息安全处理策略	☐	密码、API密钥管理方法
存在配置有效性验证逻辑	☐	检查必填配置值的功能

---

6. 代码静态分析及规范遵循

项目	检查	说明
应用了flake8,black,pylint中的至少一种	☐	代码一致性及格式统一
通过mypy,pyright等进行类型检查	☐	确保类型安全性
遵守函数长度和深度限制（<30行,<3层嵌套）	☐	判断维护难度
注释与代码一致（无过时注释）	☐	文档与代码同步
所有TODO项目解决或文档化	☐	确认未完成代码
测量代码复杂度（McCabe < 10）	☐	按函数限制复杂度
应用一致的命名约定	☐	遵守PEP8或企业标准

---

7. 测试/文档

项目	检查	说明
存在单元测试（pytest,unittest）	☐	保证核心逻辑正确性
主要函数包含docstring	☐	说明用途及返回值
README.md中说明运行方法和要求	☐	提供入职指南
测量测试覆盖率（coverage等）	☐	建议代码覆盖率达到70%以上
存在集成/系统测试	☐	端到端测试的存在性
自动生成API文档（sphinx,pdoc等）	☐	从代码生成文档
变更历史管理（CHANGELOG.md）	☐	跟踪版本变更

---

8. 错误处理和日志记录

项目	检查	说明
应用一致的异常处理模式	☐	代码中采用相同的错误处理方式
实现日志系统（使用logging模块）	☐	使用系统化日志代替print
适当区分日志级别（DEBUG/INFO/WARNING/ERROR）	☐	根据场景区分日志重要性
分离用户错误消息和调试信息	☐	单独管理最终用户消息
生产环境错误追踪方案	☐	错误报告及监控方法
重试机制（如需要）	☐	针对临时错误的重试策略

---

9. API设计

项目	检查	说明
函数接口的一致性	☐	参数和返回值类型统一
清晰的函数签名和类型提示	☐	使用Python 3.6+的类型注解
考虑API稳定性（向下兼容性）	☐	变更时尽量减少对现有调用代码的影响
应用SOLID原则	☐	遵循面向对象设计原则
区分内部API和外部API	☐	明确公开/非公开接口
API版本管理策略（如适用）	☐	API变更时的版本管理方案

---

10. 性能及可扩展性

项目	检查	说明
资源使用量剖析	☐	分析CPU、内存使用模式
必要时应用异步/并行处理（asyncio,threading等）	☐	利用并发提高性能
大规模数据处理策略	☐	高效内存处理方案
识别并优化性能瓶颈	☐	改进慢速代码部分
设计可扩展架构	☐	应对负载增长的结构
缓存策略（如适用）	☐	优化重复计算

---

11. 自动化部署

项目	检查	说明
构建CI/CD流水线	☐	自动化构建/测试/部署
支持容器化（Dockerfile）	☐	能够构建Docker镜像
提供部署脚本	☐	自动化服务器安装/更新
分离不同环境的部署配置	☐	区分开发/测试/生产部署
回滚策略	☐	部署失败时的恢复方案
监控集成方案	☐	运行状态监控可能性

---

12. 质量指标测量

项目	检查	说明
代码复杂度指标	☐	循环复杂度 < 10
测试覆盖率比例	☐	代码覆盖率 > 70%
重复代码比例	☐	重复代码 < 5%
技术债务测量	☐	静态分析工具评分
文档完成度	☐	主要API文档化比例
外部依赖漏洞检查	☐	无安全漏洞

---

综合评判标准

• 不仅是“可以运行”的水平，
• 还需要检查是否具备“可维护、可扩展、可部署的结构”。
• 平衡定量质量指标与定性评估。

---

示例目录结构

project/
├── src/
│   ├── core/
│   │   ├── __init__.py
│   │   ├── models.py
│   │   └── utils.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── endpoints.py
│   └── __init__.py
├── config/
│   ├── default.yaml
│   ├── development.yaml
│   └── production.yaml
├── tests/
│   ├── unit/
│   │   └── test_core.py
│   ├── integration/
│   │   └── test_api.py
│   └── conftest.py
├── docs/
│   ├── api.md
│   └── usage.md
├── entrypoints/
│   ├── api_server.py
│   ├── cli.py
│   └── batch_processor.py
├── scripts/
│   ├── setup.sh
│   └── deploy.sh
├── .env.example
├── Dockerfile
├── pyproject.toml
├── CHANGELOG.md
├── README.md
└── .gitignore

注意：如果以下文件包含在Git中，请发出警告

• .env
• 包含API Key的config.json
• 缓存目录如venv/, __pycache__/
• 私密证书、密钥文件（如.pem, .key等）
• 日志文件、数据库文件
• 必须全部注册到.gitignore中

等级评估标准

等级	说明	标准
A+	生产级别	满足所有必选项目 + 90%以上项目符合
A	高质量	满足所有必选项目 + 80%以上项目符合
B+	良好质量	满足所有必选项目 + 60%以上项目符合
B	可接受	满足所有必选项目
C	需要改进	部分必选项目未满足
D	不可接受	多数必选项目未满足

必选项目（最低要求）

• 基本目录结构化
• 存在__init__.py文件
• 敏感信息从代码分离
• 明确环境重现需求
• 可运行状态的代码
• 提供README.md

---

推荐质量改进工具

工具	用途	安装命令
Black	代码格式化	pip install black
isort	导入排序	pip install isort
Flake8	代码检查	pip install flake8
mypy	类型检查	pip install mypy
pytest	单元测试	pip install pytest
coverage	测试覆盖率	pip install pytest-cov
pre-commit	提交前检查	pip install pre-commit
bandit	安全漏洞分析	pip install bandit
poetry	依赖管理	curl -sSL https://install.python-poetry.org | python3 -
Sphinx	文档生成	pip install sphinx