Python大型项目包结构优化：src布局避免测试污染

本文深入剖析了Python大型项目中采用src布局的核心价值与实践要点，揭示其如何通过强制统一开发态与安装态的导入路径来根治测试污染这一顽疾——当pip install -e .后import始终精确指向src/mypackage，测试便无法绕过真实安装环境而误加载本地未安装代码，从而彻底避免CI和生产环境的行为不一致；文章不仅强调pyproject.toml中packages声明的不可省略性、tests目录必须严格镜像src层级结构以保障绝对导入可靠性，更点明scripts/应作为纯粹的运维门面，将业务逻辑完全收敛至src内，最终指出src布局的本质不是目录套娃，而是以清晰不可渗透的职责边界守护项目的长期可维护性与环境一致性。

为什么 src/ 布局能解决测试时的模块导入污染

因为不加 src/，Python 会把项目根目录（当前工作目录）自动塞进 sys.path 开头，导致 import mypackage 可能加载到未安装的本地源码，也可能意外覆盖已安装的同名包——测试跑通了，但线上行为不一致，CI 和生产环境就容易翻车。

src/ 的作用不是多套一层文件夹，而是让「开发态」和「运行态」的导入路径对齐：pip install -e . 后，import mypackage 永远指向 src/mypackage/；测试时也必须走这条路，而不是靠 sys.path.append("./src") 这种临时补丁。

• pyproject.toml 中必须声明 packages = [{include = "mypackage", from = "src"}]
• 测试命令统一用 pytest（不加 -m 或 python -m pytest），且在项目根目录下执行
• 所有测试文件里写 from mypackage.utils import helper，而不是 from src.mypackage.utils import helper

pyproject.toml 怎么配才让 src/ 真正生效

光建 src/ 目录没用，关键在构建配置。现代 Python 项目应弃用 setup.py，用 pyproject.toml 明确告诉打包工具“源码在哪、包叫什么”。

常见错误是只写了 [build-system] 却漏掉 [project] 的 packages 声明，结果 pip install -e . 仍找不到包。

• 必须包含 [project] 段，并设 name = "mypackage"
• 必须显式声明 packages = [{include = "mypackage", from = "src"}]（若包名是 mypackage）
• [build-system] 推荐用 "hatchling" 或 "setuptools>=61"，避免旧版 setuptools 解析失败
• 验证是否生效：pip install -e . && python -c "import mypackage; print(mypackage.__file__)" 输出路径应含 src/

tests/ 目录结构怎么镜像 src/ 才不踩导入坑

tests/ 和 src/ 平级是底线，但仅此不够。如果 tests/ 下直接写 test_utils.py，而 src/mypackage/utils.py 依赖 src/mypackage/core/engine.py，测试里 import 就可能失败——不是路径问题，是相对导入链断裂。

正确做法是让 tests/ 的子目录结构严格对应 src/mypackage/ 的层级，这样每个测试文件都能用绝对导入，且与运行时路径完全一致。

• src/mypackage/core/engine.py → 对应 tests/test_core/test_engine.py
• src/mypackage/api/server.py → 对应 tests/test_api/test_server.py
• 所有测试文件都用 from mypackage.core.engine import Engine，不用 ..core 或 sys.path
• 避免在 tests/ 下放 __init__.py（pytest 不需要，反而可能干扰包发现）

为什么 scripts/ 不能 import src/ 里的模块

scripts/ 是运维入口，比如 scripts/init_db.py 或 scripts/export_report.py。它们要能独立运行，不能依赖当前工作目录或开发环境的导入上下文。

一旦在 scripts/ 里写 from mypackage.services import sync_data，就等于把业务逻辑和运维脚本耦合死：部署时得确保 mypackage 已安装，调试时又得反复 pip install -e .，CI 流程也得额外处理。

• scripts/ 应只做三件事：解析参数、调用 CLI 入口、打印状态——真正的逻辑全放在 src/mypackage/cli.py 里
• 推荐模式：scripts/init_db.py 内容只有 from mypackage.cli import init_db; init_db()
• 所有 scripts/ 文件头部加 #!/usr/bin/env python3，并设可执行权限，方便直接 ./scripts/init_db.py
• scripts/ 绝对不要出现在 pyproject.toml 的 [project.scripts] 之外的任何导入路径中

真正难的不是建几个文件夹，而是让每个目录的职责不可渗透：src/ 是唯一真相源，tests/ 是它的镜像反射，scripts/ 是它对外暴露的窄门。一旦某个脚本开始从 src/ 里“偷”模块来用，边界就开始模糊，后面所有人改代码都会下意识绕过测试、跳过配置、硬编码路径。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python大型项目包结构优化：src布局避免测试污染》文章吧，也可关注golang学习网公众号了解相关技术文章。