Python工程化系统学习路线第509讲_核心原理与实战案例详解【技巧】_技术教程

真正推进Python工程化需从模块组织、pyproject.toml配置、CI覆盖率校准和Docker构建四大问题入手：src/目录解决包结构混乱，pyproject.toml取代setup.py需满足构建系统与元数据要求，coverage需排除测试文件并启用parallel，Docker中禁用-e安装以保障缓存与稳定性。

这标题不是学习路线，是营销包装出来的信息噪音。真正要推进 Python 工程化，得从具体问题出发：模块怎么组织不混乱？setup.py 和 pyproject.toml 到底该用哪个？CI 流水线里 pytest 怎么跑才不漏测？

Python 包结构设计：为什么 `src/` 目录比平铺更可靠

平铺式结构（myproject/__init__.py、myproject/main.py）在本地能 import，但发布后常出现 ModuleNotFoundError —— 因为安装时 Python 会把整个顶层目录当包名，而开发时又直接运行 python main.py，路径逻辑错位。

src/ 目录强制隔离源码与入口，pip install -e . 只暴露 src/ 下的包，避免“本地可跑、线上报错”
pyproject.toml 中必须声明 packages = [{include = "myproject", from = "src"}]，否则 build 阶段根本不会打包进去
IDE（如 PyCharm）需手动标记 src/ 为 Sources Root，否则代码补全和调试路径会异常

`pyproject.toml` 替代 `setup.py` 的三个硬性条件

不是“推荐用”，而是某些场景下 setup.py 已失效：比如使用 poetry 或 hatch 构建，或需要 PEP 621 元数据支持（如 requires-python = ">=3.9"）。

必须存在 [build-system] 段，且 requires 至少含 setuptools 和 wheel（哪怕只用 pip build）
[project] 下的 dependencies 不支持动态表达式（如 requests>=2.25; python_version >= "3.8" 必须写成 requires-python + 环境标记）
若项目含 C 扩展，setup.py 仍不可替代——pyproject.toml 目前无法完整描述 distutils 编译逻辑

CI 中 `pytest` 覆盖率失真的真实原因

本地 pytest --cov=myproject 显示 92%，CI 流水线却只有 63%——大概率是没排除测试文件本身被计入覆盖率统计。

在 pyproject.toml 的 [tool.coverage.run] 下加 omit = ["*/tests/*", "*/test_*.py"]，否则 test_main.py 里调用 main() 会被算作“已覆盖”，实际是测试代码在执行
coverage run -m pytest 比 pytest --cov 更可控，前者明确以模块方式启动，避免路径解析歧义
多进程测试（如 pytest-xdist）必须启用 parallel = true 并合并报告：coverage combine && coverage report

[tool.coverage.run]
source = ["myproject"]
omit = ["*/tests/*", "*/test_*.py"]
parallel = true

Docker 构建中 `pip install -e .` 的陷阱

开发时习惯 -e 安装，但镜像里用它会导致：每次构建都重新解析依赖、缓存失效、甚至因 git+https 依赖触发认证失败。

生产镜像应改用 pip install .（非 editable），配合 COPY pyproject.toml setup.py . 提前利用 Docker 层缓存
若依赖含 git URL，必须在 pip install 前配置 SSH key 或用 token 替换 URL（如 git+https://${GITHUB_TOKEN}@github.com/user/repo.git）
poetry export -f requirements.txt | pip install -r /dev/stdin 在 Docker 中更稳定，尤其处理 extras 时