Python工程化系统学习路线第549讲_核心原理与实战案例详解【指导】

Python工程化=项目结构+依赖管理+测试闭环+可部署性，需强制pyproject.toml、src/布局、CI三检（pytest/mypy/black）、type hint与__all__，淘汰setup.py和requirements.txt，用poetry+hatchling保障可复现性。

这标题没有实际指导价值，别被“第549讲”“核心原理”“实战案例”这类词带偏——Python工程化不是靠追课学出来的，是靠踩坑、重构、读生产代码、改CI配置一点点堆出来的。

Python工程化 = 项目结构 + 依赖管理 + 测试闭环 + 可部署性

所谓“工程化”，本质是让多人能协作、代码能长期维护、新功能能快速上线且不出错。它不依赖某个“高深原理”，而取决于你是否在每个环节做了最小但有效的约束：

• pyproject.toml 必须存在，且只用 poetry 或 pip-tools 管理依赖，禁用 requirements.txt 手动维护
• 包结构必须含 src/ 目录（避免本地 import 冲突），tests/ 与 src/ 平级
• CI 脚本里必须跑 pytest --cov + black --check + mypy，缺一不可
• 所有非 trivial 的函数必须有 type hint，所有 public 模块必须有 __all__

为什么 setup.py 已淘汰，但很多人还在用？

因为没遇到过 pip install -e . 在不同 Python 版本下解析失败、或 import mypkg 突然变成 ImportError: cannot import name 'X' from partially initialized module 这类问题。现代 Python 工程只认 pyproject.toml：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "myapp"
version = "0.1.0"
dependencies = [
  "requests>=2.28",
  "pydantic>=2.0"
]

注意：hatchling 比 setuptools 更轻、更确定；requires 里不能写 setuptools，否则会回退到旧模式。

poetry export -f requirements.txt 是个危险操作

它生成的 requirements.txt 是扁平快照，丢失了依赖树层级和约束逻辑，CI 中一旦用它装依赖，就等于放弃可复现性。正确做法是：

• 开发时：用 poetry install（保证 lock 文件生效）
• CI/CD 构建镜像时：用 poetry export -f constraints.txt --without-hashes，再 pip install --constraint constraints.txt -r requirements.txt
• 永远不在 git 中提交自动生成的 requirements.txt

测试不是“覆盖率高就行”，而是要测边界、测副作用、测 import 顺序

很多团队卡在“写了 test 但上线还是崩”，问题常出在没测真实加载路径。比如：

• 模块 A 依赖模块 B，B 里有 atexit.register() —— 单测不 reload 就发现不了资源泄漏
• if TYPE_CHECKING: 块里的 import，在运行时根本不会执行，但 mypy 会检查，得单独写 type-checking test
• 用 patch mock 了 requests.get，但忘了 side_effect 抛异常的分支，导致超时逻辑从没被执行过

真正可靠的测试套件，至少包含三类文件：test_unit/（纯函数）、test_integration/（跨模块调用）、test_e2e/（启动最小服务收请求）。

工程化的复杂点从来不在语法或框架，而在你愿不愿意为 import 顺序多写一个 test，愿不愿意把 __init__.py 里那行 from .core import X 拆成显式导入，愿不愿意在 PR 描述里写清楚“这个改动影响了 CI 中的 Docker 多阶段构建缓存”。这些事没人教，但每件都决定你的代码能不能活过三个月。