Python 项目目录结构最佳实践

不能把所有代码塞进一个 main.py，因为会导致运行时导入错误、测试无法隔离、依赖难管理、CI/CD 构建失败，最常见的是 ModuleNotFoundError；必须使用 src/ 目录结构并正确配置 pyproject.toml 和包安装方式。

为什么不能把所有代码塞进一个 main.py

因为运行时导入会出错、测试无法隔离、依赖难管理、CI/CD 构建失败——最常见的是 ModuleNotFoundError: No module named 'xxx'。Python 的模块搜索路径（sys.path）默认只含当前目录和 site-packages，没有自动识别“项目根目录”的逻辑。你手动改 sys.path 或靠 IDE 注入路径，上线后就崩。

src/ 目录不是可选，是必须

把源码统一放在 src/ 下，能彻底切断“当前工作目录决定导入行为”的耦合。安装包时用 setuptools 的 package_dir={"": "src"} 映射，确保 pip install -e . 后，无论从哪执行脚本，import myproject 都指向 src/myproject/。

示例结构：

myproject/
├── pyproject.toml
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── core.py
│       └── cli.py
└── tests/
    └── test_core.py

关键点：

• pyproject.toml 中必须声明 packages = [{include = "myproject", from = "src"}]（或用 find 配置）
• 测试文件不能放在 src/ 里，否则会被打包进 wheel
• 不推荐用 setup.py，它已过时且易绕过 src/ 隔离

配置文件和数据文件放哪？别放 src/ 里

硬编码路径或用 __file__ 往上跳级找配置，会导致单元测试失败、Docker 构建时找不到文件、Windows/macOS 路径分隔符报错。正确做法是：由入口脚本（如 src/myproject/cli.py）接收配置路径参数，或通过环境变量指定，默认值用 pathlib.Path(__file__).parent.parent / "config" 定位到项目根下独立目录。

建议结构：

简单库存管理系统

本系统是一个基于工厂模式的三层架构项目，基于VS2005 开发，结构简洁，配合动软Codematic代码生成器，可以使开发效率事半功倍，倍感轻松。本系统主要功能 1，物品类别管理 实现了物品类别的添加、修改、删除功能，方便库存物品分类管理。 2，物品管理 实现物品添加、修改，管理员可实时对物品做出库、入库记录，也可查看详细历史出入库记录。 3，商家管理 实现商家添加、修改、删除功能，方便公司和客户

myproject/
├── config/
│   ├── dev.yaml
│   └── prod.yaml
├── data/
│   └── sample.csv
├── src/
└── tests/

这样部署时可单独挂载 config/，测试时也能用 tmp_path 模拟。

测试和类型检查要覆盖真实导入路径

如果测试直接 import myproject.core 成功，但 python -m pytest tests/ 报错，说明测试没走 src/ 安装路径。必须确保：

• 测试命令在项目根目录执行（不是 tests/ 子目录）
• pytest.ini 或 pyproject.toml 中设 testpaths = ["tests"]，不加 python_paths 等 hack
• mypy 运行时传 --package myproject，而非对 src/myproject/ 目录扫描

否则类型检查会漏掉跨模块引用错误，比如 myproject.cli 导入 myproject.core 时用了未标注的返回值。

真正卡住人的从来不是目录怎么画，而是第一次 pip install -e . 后，发现 import 不生效、测试跑不通、CI 里路径全错——这些都源于没把 src/ 当成边界，而把它当成可有可无的装饰。