From 4d0d8620a4456683b0f0e54f2ceab4d807d23c44 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Tue, 19 May 2026 15:29:41 +0800 Subject: [PATCH] docs: references - add python project skeleton --- docs/references/README.md | 698 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 698 insertions(+) diff --git a/docs/references/README.md b/docs/references/README.md index 88335b7..1b613f5 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -15,6 +15,7 @@ | 目标 | 直接跳转 | |:---|:---| | 新项目结构怎么搭 | [项目架构模板](#reference-engineering-practice-1-项目架构模板) | +| Python 项目骨架怎么搭 | [通用 Python 项目骨架](#reference-engineering-practice-通用-python-项目骨架) | | AI 代码质量怎么卡住 | [AI 编程质量门禁与常见坑](#quality-gates) | | 系统提示词怎么写 | [系统提示词构建原则](#reference-engineering-practice-1-系统提示词构建原则) | | 强前置条件怎么约束 | [强前置条件约束](#reference-engineering-practice-2-强前置条件约束) | @@ -36,6 +37,7 @@ - [1. 项目架构模板](#reference-engineering-practice-1-项目架构模板) - [1. 使用原则](#reference-engineering-practice-1-使用原则) - [2. 快速选型](#reference-engineering-practice-2-快速选型) + - [通用 Python 项目骨架](#reference-engineering-practice-通用-python-项目骨架) - [3. Python Web/API 项目结构](#reference-engineering-practice-3-python-webapi-项目结构) - [4. 数据科学 / 量化项目结构](#reference-engineering-practice-4-数据科学-量化项目结构) - [5. Monorepo 项目结构](#reference-engineering-practice-5-monorepo-项目结构) @@ -418,12 +420,708 @@ | 项目类型 | 推荐模板 | | --- | --- | +| Python 应用 / 服务 / 脚本工具 / 库项目 | 通用 Python 项目骨架 | | Web API / 后端服务 | Python Web/API 项目结构 | | 数据分析 / 量化 / 机器学习 | 数据科学项目结构 | | 多服务 / 大型系统 | Monorepo 项目结构 | | 前后端一体项目 | Full-Stack Web 应用结构 | | 长期运行的数据采集服务 | Dataset First 数据服务结构 | + +#### 通用 Python 项目骨架 + +适合大多数应用型项目、服务型项目、脚本工具项目，也可以轻微调整后用于 Python 库项目 + +--- + +#### Python 通用项目骨架说明文档 + +##### 1. 推荐目录结构示意图 + +```text +project/ +├── src/ +│ └── your_package/ +│ ├── __init__.py +│ ├── main.py +│ ├── core/ +│ │ ├── __init__.py +│ │ └── service.py +│ ├── api/ +│ │ ├── __init__.py +│ │ └── routes.py +│ ├── models/ +│ │ ├── __init__.py +│ │ └── user.py +│ ├── utils/ +│ │ ├── __init__.py +│ │ └── helpers.py +│ └── config.py +│ +├── tests/ +│ ├── __init__.py +│ ├── test_main.py +│ ├── test_service.py +│ └── fixtures/ +│ └── sample_data.json +│ +├── scripts/ +│ ├── dev.sh +│ ├── lint.sh +│ ├── test.sh +│ └── release.sh +│ +├── config/ +│ ├── default.toml +│ ├── development.toml +│ ├── production.toml +│ └── logging.yaml +│ +├── docs/ +│ ├── index.md +│ ├── architecture.md +│ ├── development.md +│ └── deployment.md +│ +├── .github/ +│ └── workflows/ +│ └── ci.yml +│ +├── .env.example +├── .gitignore +├── .python-version +├── AGENTS.md +├── Makefile +├── pyproject.toml +├── README.md +├── requirements.txt +├── requirements-dev.txt +└── requirements.lock.txt +``` + +--- + +##### 2. 本地生成目录，不应提交到 Git + +这些文件或目录可以存在于项目根目录，但不属于仓库骨架的一部分： + +```text +project/ +├── .venv/ +├── .env +├── .pytest_cache/ +├── .ruff_cache/ +├── __pycache__/ +├── .coverage +├── htmlcov/ +├── dist/ +├── build/ +└── *.egg-info/ +``` + +它们应该写进 `.gitignore`。 + +--- + +##### 3. 各目录与文件说明 + +###### `src/` + +项目源码目录。 + +推荐使用 `src` 布局，而不是把业务代码直接放在项目根目录。这样可以避免本地开发时错误导入根目录下的代码。 + +示例： + +```text +src/ +└── your_package/ + ├── __init__.py + ├── main.py + ├── core/ + ├── api/ + ├── models/ + └── utils/ +``` + +其中： + +| 路径 | 说明 | +| --------------- | --------------------- | +| `your_package/` | 项目的主 Python 包名 | +| `main.py` | 应用入口，可用于 CLI、服务启动或主流程 | +| `core/` | 核心业务逻辑 | +| `api/` | API 路由、接口层代码 | +| `models/` | 数据模型、领域模型、ORM 模型 | +| `utils/` | 工具函数、通用辅助模块 | +| `config.py` | 配置读取与解析逻辑 | + +--- + +###### `tests/` + +测试目录。 + +```text +tests/ +├── test_main.py +├── test_service.py +└── fixtures/ + └── sample_data.json +``` + +建议规则： + +| 项 | 建议 | +| ------ | -------------------- | +| 测试框架 | `pytest` | +| 测试文件命名 | `test_*.py` | +| 测试函数命名 | `test_*` | +| 测试数据 | 放入 `tests/fixtures/` | +| 覆盖率 | 可使用 `pytest-cov` | + +--- + +###### `scripts/` + +项目辅助脚本目录。 + +```text +scripts/ +├── dev.sh +├── lint.sh +├── test.sh +└── release.sh +``` + +常见用途： + +| 脚本 | 说明 | +| ------------ | ------- | +| `dev.sh` | 启动开发环境 | +| `lint.sh` | 执行代码检查 | +| `test.sh` | 执行测试 | +| `release.sh` | 发布或打包流程 | + +如果项目简单，也可以只用 `Makefile`，不一定需要 `scripts/`。 + +--- + +###### `config/` + +配置文件目录。 + +```text +config/ +├── default.toml +├── development.toml +├── production.toml +└── logging.yaml +``` + +注意： + +| 文件 | 是否提交 | 说明 | +| -------------- | ---: | ------ | +| 默认配置 | 是 | 可以提交 | +| 环境模板配置 | 是 | 可以提交 | +| 密钥、Token、密码 | 否 | 不应提交 | +| `.env` | 否 | 本地私密配置 | +| `.env.example` | 是 | 环境变量示例 | + +--- + +###### `docs/` + +项目文档目录。 + +```text +docs/ +├── index.md +├── architecture.md +├── development.md +└── deployment.md +``` + +推荐至少包含： + +| 文档 | 说明 | +| ----------------- | ---- | +| `index.md` | 文档首页 | +| `architecture.md` | 架构说明 | +| `development.md` | 开发说明 | +| `deployment.md` | 部署说明 | + +小项目可以只保留 `README.md`，不用单独建 `docs/`。 + +--- + +###### `.github/workflows/` + +GitHub Actions 自动化目录。 + +```text +.github/ +└── workflows/ + └── ci.yml +``` + +常见用途： + +| 文件 | 说明 | +| ------------- | ------------ | +| `ci.yml` | 自动测试、Lint、构建 | +| `release.yml` | 自动发布 | +| `docs.yml` | 自动构建文档 | + +如果项目不用 GitHub，可以没有这个目录。 + +--- + +##### 4. 根目录核心文件说明 + +###### `pyproject.toml` + +现代 Python 项目的核心配置文件。 + +建议把这些工具配置集中放在里面： + +```text +[project] +[build-system] +[tool.pytest.ini_options] +[tool.ruff] +[tool.mypy] +[tool.coverage] +``` + +它可以统一管理： + +| 内容 | 说明 | +| ------- | -------------------------------- | +| 项目元数据 | 名称、版本、作者、描述 | +| 构建系统 | setuptools、hatchling、poetry、uv 等 | +| 依赖声明 | 运行依赖、可选依赖 | +| 测试配置 | pytest | +| Lint 配置 | ruff | +| 类型检查 | mypy、pyright | +| 覆盖率配置 | coverage | + +--- + +###### `requirements.txt` + +运行依赖文件。 + +适合应用型项目，例如： + +```text +fastapi +uvicorn +pydantic +requests +``` + +如果项目依赖已经完全放进 `pyproject.toml`，这个文件可以由工具导出，而不是手写维护。 + +--- + +###### `requirements-dev.txt` + +开发依赖文件。 + +例如： + +```text +pytest +pytest-cov +ruff +mypy +pre-commit +``` + +用于开发、测试、格式化、类型检查。 + +--- + +###### `requirements.lock.txt` + +锁定依赖版本的文件。 + +例如： + +```text +fastapi==0.115.0 +uvicorn==0.30.6 +pydantic==2.8.2 +``` + +作用是保证不同机器、不同环境安装到一致的依赖版本。 + +如果使用 `uv`、`poetry`、`pdm` 等工具，也可以换成： + +```text +uv.lock +poetry.lock +pdm.lock +pylock.toml +``` + +--- + +###### `.env.example` + +环境变量模板。 + +应该提交到仓库。 + +示例： + +```env +APP_ENV=development +APP_DEBUG=true +DATABASE_URL=postgresql://user:password@localhost:5432/app +REDIS_URL=redis://localhost:6379/0 +SECRET_KEY=change-me +``` + +注意：这里可以放假值、示例值，但不能放真实密钥。 + +--- + +###### `.env` + +本地真实环境变量。 + +不应提交。 + +示例： + +```env +APP_ENV=development +APP_DEBUG=true +DATABASE_URL=postgresql://real_user:real_password@localhost:5432/app +SECRET_KEY=real-secret +``` + +--- + +###### `.gitignore` + +推荐内容： + +```gitignore +#### Python cache +__pycache__/ +*.py[cod] +*$py.class + +#### Virtual environments +.venv/ +venv/ +env/ + +#### Environment variables +.env +.env.* +!.env.example + +#### Test / coverage +.pytest_cache/ +.coverage +htmlcov/ + +#### Ruff +.ruff_cache/ + +#### Build artifacts +build/ +dist/ +*.egg-info/ + +#### IDE +.vscode/ +.idea/ + +#### OS files +.DS_Store +Thumbs.db + +#### Logs +*.log +logs/ +``` + +--- + +###### `.python-version` + +用于声明项目推荐 Python 版本。 + +示例： + +```text +3.12 +``` + +适合团队统一 Python 版本，尤其是使用 `pyenv`、`uv` 等工具时。 + +--- + +###### `Makefile` + +统一开发命令入口。 + +示例： + +```makefile +.PHONY: install dev test lint format clean + +install: + pip install -r requirements.txt + +dev: + pip install -r requirements-dev.txt + +test: + pytest + +lint: + ruff check src tests + +format: + ruff format src tests + +clean: + rm -rf .pytest_cache .ruff_cache .coverage htmlcov dist build +``` + +这样团队成员可以直接执行： + +```bash +make install +make dev +make test +make lint +make format +make clean +``` + +--- + +###### `README.md` + +项目入口说明文档。 + +建议包含： + +```text +#### Project Name + +##### Introduction +项目简介。 + +##### Features +核心功能。 + +##### Requirements +运行要求。 + +##### Installation +安装方法。 + +##### Usage +使用方法。 + +##### Development +开发说明。 + +##### Testing +测试说明。 + +##### Deployment +部署说明。 + +##### License +许可证。 +``` + +--- + +###### `AGENTS.md` + +给 AI 编程助手、自动化代理或协作工具看的项目说明。 + +不是 Python 官方标准文件，但现在越来越常见。 + +建议内容包括： + +```text +#### AGENTS.md + +##### Project Overview +本项目的目标、技术栈、代码边界。 + +##### Coding Rules +代码风格、命名规范、禁止事项。 + +##### Test Commands +如何运行测试。 + +##### Lint Commands +如何运行代码检查。 + +##### Project Structure +目录说明。 + +##### Notes +开发注意事项。 +``` + +--- + +##### 5. 推荐的最小可用版本 + +如果项目不复杂，可以使用这个精简版： + +```text +project/ +├── src/ +│ └── your_package/ +│ ├── __init__.py +│ └── main.py +├── tests/ +│ └── test_main.py +├── .env.example +├── .gitignore +├── .python-version +├── Makefile +├── pyproject.toml +├── README.md +├── requirements.txt +└── requirements-dev.txt +``` + +这个版本适合： + +| 类型 | 是否适合 | +| ----------- | ---: | +| 小型工具项目 | 是 | +| 内部脚本项目 | 是 | +| FastAPI 小服务 | 是 | +| 数据处理项目 | 是 | +| 命令行工具 | 是 | +| 大型平台项目 | 需要扩展 | + +--- + +##### 6. 推荐的完整企业/团队版本 + +如果是团队协作、后端服务、AI 应用、数据平台或长期维护项目，推荐使用完整版本： + +```text +project/ +├── src/ +│ └── your_package/ +│ ├── __init__.py +│ ├── main.py +│ ├── core/ +│ ├── api/ +│ ├── models/ +│ ├── services/ +│ ├── repositories/ +│ ├── schemas/ +│ ├── utils/ +│ └── config.py +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── fixtures/ +├── scripts/ +├── config/ +├── docs/ +├── .github/ +│ └── workflows/ +├── .env.example +├── .gitignore +├── .python-version +├── AGENTS.md +├── Makefile +├── pyproject.toml +├── README.md +├── requirements.txt +├── requirements-dev.txt +└── requirements.lock.txt +``` + +额外模块说明： + +| 目录 | 说明 | +| -------------------- | ---------------- | +| `services/` | 应用服务层，组织业务流程 | +| `repositories/` | 数据访问层，封装数据库、外部存储 | +| `schemas/` | 请求、响应、校验模型 | +| `tests/unit/` | 单元测试 | +| `tests/integration/` | 集成测试 | +| `.github/workflows/` | CI/CD 自动化 | + +--- + +##### 7. 最终推荐原则 + +这套骨架遵循几个原则： + +| 原则 | 说明 | +| ------- | --------------------------------- | +| 源码隔离 | 业务代码统一放入 `src/` | +| 测试独立 | 测试代码统一放入 `tests/` | +| 配置分层 | 示例配置进仓库，真实密钥不进仓库 | +| 工具集中 | 主要工具配置尽量放入 `pyproject.toml` | +| 本地文件不提交 | `.venv/`、`.env`、缓存目录全部忽略 | +| 命令统一 | 用 `Makefile` 或脚本统一开发命令 | +| 文档随仓库维护 | `README.md` 负责入口说明，`docs/` 负责详细文档 | +| 可扩展 | 小项目可精简，大项目可扩展 | + +--- + +##### 8. 最终结论 + +这份项目骨架可以作为通用 Python 仓库模板： + +```text +project/ +├── src/ +├── tests/ +├── scripts/ +├── config/ +├── docs/ +├── .github/ +├── .env.example +├── .gitignore +├── .python-version +├── AGENTS.md +├── Makefile +├── pyproject.toml +├── README.md +├── requirements.txt +├── requirements-dev.txt +└── requirements.lock.txt +``` + +其中： + +```text +.venv/ +.env +.pytest_cache/ +.ruff_cache/ +__pycache__/ +``` + +只属于本地环境，不应进入仓库。 + +这就是一个比较稳妥、通用、可维护的 Python 项目根目录设计。 + #### 3. Python Web/API 项目结构