python项目结构设计核心是按规模渐进演进：小脚本扁平化，中大型服务工程化分层；基础结构含src/、tests/、scripts/等，生产级则按领域拆分模块并隔离配置与部署。
Python项目结构设计核心是分离关注点、便于测试与部署、支持团队协作。不是越复杂越好，而是按项目规模和生命周期渐进演进——小脚本无需分层，中大型服务必须工程化。
基础可维护结构（适合大多数CLI/小Web服务）
从一个清晰的根目录开始，避免把所有文件堆在顶层：
-
src/：真正可安装的Python包（如
myapp/），含__init__.py和核心模块 -
tests/：与
src/平级，用pytest运行，结构尽量镜像src/（如tests/test_core.py对应src/myapp/core.py） -
scripts/：运维或数据预处理等一次性脚本（不导入
src，避免隐式依赖） -
requirements.txt 或 pyproject.toml：明确声明依赖，推荐用
pip-tools或poetry管理锁文件 - README.md、.gitignore、.pre-commit-config.yaml：基础工程素养标配
生产级分层结构（适合Django/Flask/FastAPI服务）
当业务逻辑变多、需长期迭代时，按职责拆分模块比按技术分层更可持续：
-
src/myapp/ 下不再用
models/、views/、utils/大杂烩，改用领域驱动思路：
→src/myapp/users/（含models.py、api.py、services.py）
→src/myapp/orders/（同理）
→src/myapp/common/（跨域工具、异常定义、配置基类） -
config/：环境隔离配置（
base.py、dev.py、prod.py），用python-decouple或pydantic-settings加载 - migrations/（SQLAlchemy/Django）或 alembic/：数据库变更单独管理
- docker/ 和 deploy/：容器构建文件、K8s YAML 或 CI/CD 脚本，与代码解耦
关键避坑细节
很多项目结构“看着规范”，上线后却踩坑不断：
立即学习“Python免费学习笔记（深入）”；
-
不要在
src/外写业务代码：避免main.py直接调用./utils.py，导致无法 pip install 或测试失败 -
测试路径必须能 import src：运行
pytest tests/前确保 Python path 包含src/（通过pyproject.toml的[tool.pytest.ini_options]配置pythonpath = ["src"]） -
敏感配置不进代码：.env 文件只放开发环境变量，生产用 Secret Manager 或 K8s Secrets，代码里统一走
os.getenv("DB_URL") -
type stubs 和 mypy 配置早接入：在
pyproject.toml中配[tool.mypy]，给核心模块加类型注解，比后期补文档高效得多
自动化加持工程化
结构只是骨架，靠工具链让它活起来：
- 用
pre-commit自动格式化（black）、检查（ruff）、类型校验（mypy） - CI 流水线跑
pytest --cov=src+bandit（安全扫描）+codespell（拼写检查） - 发布流程走
build（生成 wheel）→twine check（校验包元数据）→twine upload（推 PyPI） - 本地开发用
direnv或pipenv隔离环境，避免 “在我机器上能跑” 问题
不复杂但容易忽略。结构定型后，团队成员花10分钟就能理解模块边界，新功能加在哪、测试怎么写、配置怎么改，一目了然。
