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等标准参数
