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/，验证模块间协作是否符合预期
