Python项目结构如何设计_工程化实践

python项目结构设计核心是分层清晰、职责明确、便于测试与部署，推荐以src为源码根目录，按业务域（如orders/payments）而非技术层组织模块，用pyproject.toml统一管理依赖与构建，并通过pre-commit、pytest、venv等机制保障工程化落地。

Python项目结构设计核心是“分层清晰、职责明确、便于测试与部署”。不是越复杂越好，而是让新成员能快速理解、CI/CD流程能稳定运行、本地开发和生产环境行为一致。

基础目录骨架：从src开始隔离源码

避免把模块直接放在项目根目录（即不推荐 myproject/xxx.py），而是用 src/ 显式包裹源码：

• src/myapp/：主包，含 __init__.py，所有业务逻辑、API、模型放这里
• tests/：与 src/ 平级，用绝对导入（如 from myapp.core import Calculator），确保测试代码不依赖路径hack
• scripts/：存放运维脚本（如数据初始化、DB迁移触发）、非正式工具，不打包进发布包
• configs/：配置文件按环境拆分（base.toml, dev.yaml, prod.env），通过环境变量加载，不硬编码

模块划分原则：按领域而非技术分层

少用“models / views / utils”这种纯技术分层（易导致职责扩散）。优先按业务域组织：

• src/myapp/orders/：订单创建、状态机、退款逻辑
• src/myapp/payments/：对接支付网关、异步对账、风控回调处理
• src/myapp/shared/：跨域复用的类型定义（types.py）、通用异常（errors.py）、ID生成器等
• 每个子包内可含 __init__.py 汇总对外接口，隐藏内部实现细节（如 from .service import process_order）

依赖与构建：用pyproject.toml统一管理

弃用 setup.py，全部收敛到 pyproject.toml：

立即学习“Python免费学习笔记（深入）”；

• [build-system] 指定 setuptools-build-backend 或 hatchling
• [project] 声明 dependencies 和 optional-dependencies（如 dev = ["pytest", "black"]）
• [project.optional-dependencies] 分组管理：测试、文档、部署工具等，按需安装（pip install ".[dev,docs]"）
• 配合 poetry 或 hatch 可自动同步依赖、生成锁文件、构建发行包

工程化支撑点：让结构“活”起来

结构本身不产生价值，配套机制才关键：

• 预提交钩子：用 pre-commit 统一执行 black 格式化、isort 导入排序、pylint 静态检查，保证代码风格一致
• 测试即文档：每个核心模块配 test_*.py，用 pytest --doctest-modules src/ 自动运行模块docstring中的示例
• 环境隔离：CI中用 python -m venv .venv && source .venv/bin/activate 确保干净环境；本地推荐 direnv 自动激活对应 .envrc
• 可观察性入口：在 src/myapp/__main__.py 提供 CLI 入口（python -m myapp serve），支持 --config、--log-level 等标准参数