Python项目结构设计_模块划分解析【教程】

Python项目结构设计的核心是可维护、易扩展、便于协作，应按业务边界划分core/、api/、services/、infrastructure/、utils/顶层模块，各模块内遵循接口+实现分层，配置与环境分离，测试与代码同级且分层覆盖。

Python项目结构设计的核心是让代码可维护、易扩展、便于团队协作。模块划分不是越细越好，而是要围绕业务边界和职责单一原则来组织。

按功能域划分顶层模块

避免把所有代码堆在src或app目录下。应根据实际业务划分为清晰的顶层包，比如：

• core/：核心逻辑、领域模型、基础服务（如用户认证基类、订单状态机）
• api/：Web接口层（FastAPI/Flask路由、请求验证、响应封装）
• services/：具体业务服务（支付服务、通知服务、库存校验服务）
• infrastructure/：外部依赖适配（数据库ORM配置、Redis客户端、第三方API SDK封装）
• utils/：通用工具函数（日期处理、字符串编码、日志装饰器），不包含业务逻辑

每个模块内部遵循“接口+实现”分层

以services/payment.py为例，不要直接写一个process_payment()函数调用数据库和微信SDK。应拆解为：

• 定义抽象接口：PaymentService（声明charge()、refund()等方法）
• 实现具体类：WechatPaymentService、AlipayPaymentService
• 通过依赖注入或工厂模式在运行时选择实现，方便测试与替换

配置与环境分离，禁止硬编码

把配置从代码中彻底剥离，推荐结构：

• config/目录下放base.py（通用配置）、dev.py、prod.py
• 使用pydantic.BaseSettings加载环境变量，自动类型校验
• 敏感信息（密钥、数据库密码）不进Git，通过.env文件或K8s Secret挂载

测试与代码同级但隔离

测试不是附属品，而是项目的一等公民：

• 每个模块对应tests/子目录，结构镜像源码（如tests/services/test_payment.py）
• 单元测试聚焦逻辑，用unittest.mock或pytest-mock隔离外部依赖
• 集成测试单独放在tests/integration/，验证模块间协作是否符合预期