src/布局通过强制导入路径与安装态一致来解决测试污染：pip install -e .后import始终指向src/mypackage，测试也必须走此路径，需在pyproject.toml中声明packages=[{include="mypackage",from="src"}]并配tests/镜像结构。

为什么 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 就可能失败——不是路径问题，是相对导入链断裂。

python-code-analyz

专业Python代码分析与优化，支持语法检查、安全扫描、性能评估、复杂度分析及重构后优化代码生成。

下载

正确做法是让 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免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！