gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-08-01 05:07:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: split docs readmes into topic files

Browse Source
This commit is contained in:
tukuaiai
2026-06-01 00:48:27 +08:00
parent 0f52eb242a
commit e6827939c0
54 changed files with 12565 additions and 13215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/references/python-project-skeleton.md
+694
View File
@@ -0,0 +1,694 @@
<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 项目根目录设计。