Python项目结构设计核心是“可维护、可测试、可部署”，需按职责分层：src/为源码根目录，tests/与之镜像，config/、data/、scripts/物理隔离，依赖分层管理，入口与文档自成体系。

Python项目结构设计核心是“可维护、可测试、可部署”，不是堆文件夹，而是按职责分层、隔离关注点。一个规范的结构能让新成员快速上手，CI流程稳定运行，打包发布不踩坑。

src/ 作为源码根目录（推荐）

避免把模块直接放在项目根目录下（即 不推荐 myproject/ 下直接放 main.py 或 utils.py）。应统一收口到 src/ 中：

• src/myproject/ —— 实际包目录，含 __init__.py，所有业务代码、子模块都在此
• pyproject.toml 中配置 [project] 的 requires-python 和 dependencies，并设 [build-system] 使用 setuptools 或 hatchling
• 安装时用 pip install -e .（开发模式），工具会自动识别 src/ 为源码起点，避免本地路径污染

分离配置、数据与代码

运行时依赖项不能硬编码，需物理隔离：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• config/：存放 base.py、dev.py、prod.py，用 os.getenv() 或 pydantic-settings 加载环境变量覆盖
• data/：只读数据文件（如 CSV、JSON 样本）、模型权重（若小）、缓存目录（data/cache/）—— 不提交大文件，加 .gitignore
• scripts/：非核心但需手动执行的脚本，如数据清洗、DB 初始化，不作为包导入使用

测试与依赖明确分层

测试不是附属，而是工程一等公民：

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

• tests/ 与 src/ 平级，结构镜像（如 tests/test_api/ 对应 src/myproject/api/）
• 用 pytest + pytest-cov，在 pyproject.toml 中配 [tool.pytest.ini_options] 指定 testpaths = ["tests"]
• requirements/ 下拆分依赖：base.txt（核心）、dev.txt（含 black, mypy）、test.txt（含 pytest, responses）

入口、构建与文档自成体系

让项目“开箱即用”：

• app.py 或 cli.py 放在项目根（非 src 内），作为 CLI 入口，仅做参数解析和调度，不写业务逻辑
• Makefile 或 justfile 封装常用命令：make test、make format、make build，降低协作门槛
• docs/ 存放 mkdocs.yml 和源文件；README.md 包含快速启动、环境要求、核心命令三要素