python项目结构合理的关键是按需分层、职责清晰、约定明确，典型结构包括src/（主程序包）、tests/（镜像src的测试）、scripts/（运维脚本）、configs/（多环境配置）、docs/（轻量文档），并采用src布局、绝对导入、pyproject.toml依赖管理、虚拟环境隔离及pre-commit自动化。
Python 项目结构合理的关键，是让代码可维护、易测试、好部署，同时兼顾团队协作和未来扩展。不是越复杂越好，而是按需分层、职责清晰、约定明确。
核心目录划分要体现关注点分离
避免把所有文件堆在根目录下。典型且实用的分层结构如下：
-
src/：存放主程序包（如
myapp/），包含业务逻辑、API、核心类。这是可安装的 Python 包，应有__init__.py和清晰的模块划分（如models/、services/、utils/） -
tests/：与
src/平级，用pytest组织，目录结构尽量镜像src/（如tests/test_models/），方便定位对应测试 - scripts/ 或 bin/：放运维脚本、数据初始化、临时工具等非业务逻辑的可执行文件
-
configs/：配置文件（
dev.yaml、prod.env等），不硬编码，支持环境变量覆盖 - docs/：轻量级说明（架构图、快速上手）、不是必须但强烈建议有 README.md（含安装、运行、测试命令）
包命名和导入路径要一致且可预测
推荐使用 src/ 源码布局，并在 pyproject.toml 中声明：
[project] # … [project.optional-dependencies] dev = ["pytest", "black", "mypy"]
安装时用 pip install -e ".[dev]"，确保本地开发时 import myapp 能直接解析到 src/myapp/。避免在代码里写 sys.path.insert(0, ...) 或相对导入混乱。
立即学习“Python免费学习笔记（深入）”；
跨模块引用统一用绝对导入：
✅ from myapp.models.user import User
❌ from ..models.user import User（难维护、IDE 不友好）
配置、环境与依赖要解耦且可复现
区分三类依赖和配置：
-
依赖管理：用
pyproject.toml（现代标准），而非requirements.txt主文件；生成锁定文件用pip-compile或poetry lock -
环境隔离：每个项目配独立虚拟环境（
python -m venv .venv），不共用全局解释器 -
配置加载：用
pydantic-settings或dynaconf，支持多环境、类型校验、优先级（环境变量 > YAML > 默认值）
测试与自动化要从第一天就嵌入结构
结构本身要为测试服务：
- 把 fixture、mock 数据放在
tests/conftest.py和tests/data/下，不散落在各测试文件中 - 单元测试聚焦函数/类行为，用
unittest.mock或pytest-mock隔离外部依赖（DB、HTTP） - 集成测试单独建
tests/integration/，启动真实 DB 或轻量服务（如pytest-asyncio+testcontainers） - CI 脚本（GitHub Actions / GitLab CI）直接调用
pytest tests/ --cov=myapp，覆盖率报告不绕路
不复杂但容易忽略：结构定下来后，用 pre-commit 固化代码风格（black + isort + ruff），让新成员拉下代码就能跑通，而不是先花半天配环境。
