mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-07-28 03:07:56 +00:00
tukuaiai
695 lines
13 KiB
Markdown
695 lines
13 KiB
Markdown
<a id="reference-engineering-practice-通用-python-项目骨架"></a>
|
|
# 通用 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 项目根目录设计。
|