python-project-structure

本技能提供 Python 项目结构与模块架构方面的最佳实践和模式指导，来源于全栈开发相关技能集合。其定位是帮助开发者设计组织清晰、模块边界明确、公共接口显式、目录结构可维护的 Python 项目，使代码易于发现、变更可预期。

【适用场景】从零开始新建 Python 项目；为提升清晰度而重组现有代码库；使用 all 定义模块公共 API；在扁平与嵌套目录结构之间做出选择；确定测试文件放置策略；创建可复用的库包。

【核心概念】

模块内聚：把一起变化的相关代码分组，一个模块应具有单一、明确的目的。
显式接口：用 all 定义哪些是公开的，未列出的内容均视为内部实现细节。
扁平层级：优先使用较浅的目录结构，只有存在真实子领域时才增加深度。
统一约定：在整个项目中一致地应用命名与组织模式。

【快速上手示例】 myproject/ ├── src/ │ └── myproject/ │ ├── init.py │ ├── services/ │ ├── models/ │ └── api/ ├── tests/ ├── pyproject.toml └── README.md

【主要模式】模式一：一个文件一个概念。每个文件聚焦单一概念或紧密相关的一组函数。当文件承担多个不相关职责、超过 300–500 行（随复杂度而异）、或包含因不同原因变化的类时，考虑拆分。例如 user_service.py 放用户业务逻辑、user_repository.py 放用户数据访问、user_models.py 放用户数据结构；避免把所有内容塞进一个 user.py。

模式二：用 all 定义显式公共 API。为每个模块定义公共接口，未列出的成员即为内部实现细节。示例中在 services/init.py 导入 UserService、OrderService、ServiceError、ValidationError 并写入 all，内部辅助函数不被导出。

模式三：扁平目录结构。优先减少嵌套，过深的层级会让导入冗长、导航困难。推荐按 api、services、models、utils 等平级组织；避免 project/core/internal/services/impl/user/ 这类深层嵌套。只有在确有需要隔离的子领域时才添加子包。

模式四：测试文件组织。选择一种方式并在整个项目中统一使用。方式 A 为就地测试：测试文件与被测代码放在一起（如 test_user_service.py 紧邻 user_service.py），便于发现覆盖缺口。方式 B 为并行测试目录：生产代码在 src/ 下按包组织，测试放在 tests/ 下镜像对应结构，实现生产与测试代码的清晰分离，适合较大项目。

【进阶模式】模式五：包初始化。用 init.py 为包的使用者提供整洁的公共接口，在包级导入核心类、异常与配置，并定义 all 和 version，使使用者可直接 from mypackage import MainClass, Settings。

模式六：分层架构。按架构层次组织代码以清晰分离关注点，例如 api（HTTP 处理器、请求/响应）、services（业务逻辑）、repositories（数据访问）、models（领域实体）、schemas（API 模式，如 Pydantic）、config（配置）。每一层只应依赖其下层，绝不依赖上层。

模式七：领域驱动结构。对复杂应用，按业务领域而非技术层次组织，例如 ecommerce 下分 users、orders 等领域包，各含 models.py、services.py、repository.py、api.py，并设 shared 放公共的 database、exceptions。

【命名与导入约定】文件名与模块名使用 snake_case，如 user_repository.py；避免含义不明的缩写，用 user_repository.py 而非 usr_repo.py；类名与文件名对应，如 user_service.py 中的 UserService。导入方面优先使用绝对导入以保证清晰可靠，如 from myproject.services import UserService；避免相对导入，因为模块移动或重组时容易失效。

【最佳实践总结】保持文件专注（一个概念一个文件，约 300–500 行时考虑拆分，随复杂度而异）；显式定义 all；优先扁平结构，仅在真实子领域时增加深度；使用绝对导入；在整个项目中保持一致；文件名与内容匹配；分离关注点，保持层次分明、依赖单向流动；用 README 记录项目结构。

【能力边界】擅长：全栈开发相关最佳实践、代码架构设计指导、性能优化建议。需要素材：具体的项目上下文、技术栈信息。超出范围：非技术领域的业务决策、具体的代码实现（仅提供指导）。

【工作流程】第 1 步需求分析：理解项目需求与技术约束。第 2 步架构设计：设计系统架构与组件划分。第 3 步实现指导：提供具体的实现建议与代码模式。第 4 步代码审查：审查代码质量与最佳实践遵循情况。第 5 步优化建议：提供性能优化与改进建议。

【注意事项】避免在简单场景中过度设计；不要忽视性能优化，尤其是在生产环境；始终考虑安全性与数据保护；确保足够的测试覆盖，尤其是边界情况；保持文档与代码同步更新。

技能介绍