新建或重构 Python 项目时如何组织目录结构…

在从零搭建 Python 项目、整理现有代码库、定义模块公开 API 或规划目录布局时，提供一套可复用的项目结构与模块架构规范。

适用场景

解决思路

1. 按内聚性组织模块：把会一起变更的相关代码放在同一模块，每个模块只承担单一明确职责。
2. 用 `__all__` 显式声明公开接口：在每个模块中列出公开成员，未列出的成员视为内部实现细节。
3. 保持扁平目录结构：优先使用浅层目录，只在存在真实子领域时才增加嵌套深度，避免 `project/core/internal/services/impl/user/` 这类深层嵌套。
4. 每个文件只聚焦一个概念：当一个文件承担多个不相关职责、超过 300-500 行（视复杂度而定），或包含因不同原因变更的类时，就拆分文件，例如把 `user_service.py`、`user_repository.py`、`user_models.py` 分开，避免 `user.py` 这种大杂烩。
5. 统一测试文件组织方式并全项目一致：可选方案 A 测试与源码同目录（`user_service.py` 旁放 `test_user_service.py`），或方案 B 使用并行 `tests/` 目录镜像 `src/` 结构。
6. 用 `__init__.py` 为包消费者提供干净的公开接口：从子模块导入核心类与异常，写入 `__all__`，并设置 `__version__`，使消费者可直接 `from mypackage import MainClass, Settings`。
7. 采用分层架构：按 `api/`、`services/`、`repositories/`、`models/`、`schemas/`、`config/` 等架构层组织代码，且每层只依赖其下层，绝不依赖上层。
8. 复杂应用采用领域驱动结构：按业务领域（如 `users/`、`orders/`）而非技术层组织，每个领域内含 `models.py`、`services.py`、`repository.py`、`api.py`，共享代码放入 `shared/`。
9. 遵循命名约定：文件和模块名统一用 `snake_case`，避免含义不清的缩写（用 `user_repository.py` 而非 `usr_repo.py`），并让类名与文件名对应（`UserService` 放在 `user_service.py`）。
10. 使用绝对导入：优先写 `from myproject.services import UserService`，避免 `from ..services import UserService` 这类相对导入，以免模块移动或重组时出错。
11. 保持一致性：在整个项目中统一应用命名与组织模式。
12. 让名称匹配内容：文件名应清楚描述其用途。
13. 分离关注点：保持各层职责清晰，依赖只朝一个方向流动。
14. 记录项目结构：在 README 中说明目录组织方式。
15. 使用标准项目骨架：采用 `src/myproject/` 布局，配合 `tests/`、`pyproject.toml` 和 `README.md`。