docs: complete documentation
- Enhance README with project structure, examples, and development guide - Update plan with completion status and verification results - Add memory entries for project context and future reference Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
root
parent
67d8c6bf30
commit
dc463b3bfa
123
README.md
123
README.md
@ -1,30 +1,93 @@
|
|||||||
# FastAPI Example
|
# FastAPI Example
|
||||||
|
|
||||||
一个最小化的 FastAPI REST API 示例项目。
|
一个最小化的 FastAPI REST API 示例项目，演示健康检查和 CRUD 操作。
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── app/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── main.py # FastAPI 应用入口和路由
|
||||||
|
│ └── models.py # Pydantic 数据模型
|
||||||
|
├── tests/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ └── test_api.py # API 测试用例
|
||||||
|
├── docs/
|
||||||
|
│ └── plans/ # 实现计划文档
|
||||||
|
├── memory/ # 工作记忆
|
||||||
|
├── requirements.txt # Python 依赖
|
||||||
|
├── run.sh # 启动脚本
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
|
### 环境要求
|
||||||
|
|
||||||
|
- Python 3.11+
|
||||||
|
- pip
|
||||||
|
|
||||||
|
### 安装
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 创建虚拟环境并安装依赖
|
# 创建虚拟环境
|
||||||
python3 -m venv .venv
|
python3 -m venv .venv
|
||||||
source .venv/bin/activate
|
source .venv/bin/activate
|
||||||
pip install -r requirements.txt
|
|
||||||
|
|
||||||
# 启动服务
|
# 安装依赖
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### 启动服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 方式一：使用启动脚本
|
||||||
./run.sh
|
./run.sh
|
||||||
|
|
||||||
# 或直接运行
|
# 方式二：直接运行
|
||||||
uvicorn app.main:app --reload
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||||
```
|
```
|
||||||
|
|
||||||
|
服务启动后访问：
|
||||||
|
- API: http://localhost:8000
|
||||||
|
- Swagger UI: http://localhost:8000/docs
|
||||||
|
- ReDoc: http://localhost:8000/redoc
|
||||||
|
|
||||||
## API 端点
|
## API 端点
|
||||||
|
|
||||||
| 方法 | 路径 | 描述 |
|
| 方法 | 路径 | 描述 | 请求体 |
|
||||||
|------|------|------|
|
|------|------|------|--------|
|
||||||
| GET | /health | 健康检查 |
|
| GET | /health | 健康检查 | - |
|
||||||
| GET | /items | 列出所有项目 |
|
| GET | /items | 列出所有项目 | - |
|
||||||
| POST | /items | 创建新项目 |
|
| POST | /items | 创建新项目 | `{"name": "string", "description": "string?"}` |
|
||||||
| GET | /items/{id} | 获取单个项目 |
|
| GET | /items/{id} | 获取单个项目 | - |
|
||||||
|
|
||||||
|
### 示例请求
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 健康检查
|
||||||
|
curl http://localhost:8000/health
|
||||||
|
# {"status": "ok"}
|
||||||
|
|
||||||
|
# 创建项目
|
||||||
|
curl -X POST http://localhost:8000/items \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"name": "My Item", "description": "A test item"}'
|
||||||
|
# {"id": 1, "name": "My Item", "description": "A test item"}
|
||||||
|
|
||||||
|
# 列出所有项目
|
||||||
|
curl http://localhost:8000/items
|
||||||
|
# [{"id": 1, "name": "My Item", "description": "A test item"}]
|
||||||
|
|
||||||
|
# 获取单个项目
|
||||||
|
curl http://localhost:8000/items/1
|
||||||
|
# {"id": 1, "name": "My Item", "description": "A test item"}
|
||||||
|
|
||||||
|
# 获取不存在的项目
|
||||||
|
curl http://localhost:8000/items/999
|
||||||
|
# {"detail": "Item not found"}
|
||||||
|
```
|
||||||
|
|
||||||
## 测试
|
## 测试
|
||||||
|
|
||||||
@ -33,8 +96,36 @@ source .venv/bin/activate
|
|||||||
pytest tests/ -v
|
pytest tests/ -v
|
||||||
```
|
```
|
||||||
|
|
||||||
## API 文档
|
测试覆盖：
|
||||||
|
- `test_health_check` - 健康检查端点
|
||||||
|
- `test_create_item` - 创建项目
|
||||||
|
- `test_list_items` - 列出项目
|
||||||
|
- `test_get_item` - 获取单个项目
|
||||||
|
- `test_get_item_not_found` - 404 错误处理
|
||||||
|
|
||||||
启动服务后访问：
|
## 开发指南
|
||||||
- Swagger UI: http://localhost:8000/docs
|
|
||||||
- ReDoc: http://localhost:8000/redoc
|
### 添加新端点
|
||||||
|
|
||||||
|
1. 在 `app/models.py` 添加数据模型
|
||||||
|
2. 在 `app/main.py` 添加路由函数
|
||||||
|
3. 在 `tests/test_api.py` 编写测试
|
||||||
|
4. 运行测试验证
|
||||||
|
|
||||||
|
### 代码风格
|
||||||
|
|
||||||
|
- 使用类型注解
|
||||||
|
- 遵循 PEP 8
|
||||||
|
- 函数添加 docstring
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Python Web 框架
|
||||||
|
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证
|
||||||
|
- [Uvicorn](https://www.uvicorn.org/) - ASGI 服务器
|
||||||
|
- [pytest](https://pytest.org/) - 测试框架
|
||||||
|
- [httpx](https://www.python-httpx.org/) - HTTP 客户端
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|||||||
@ -1,6 +1,7 @@
|
|||||||
# FastAPI 示例项目实现计划
|
# FastAPI 示例项目实现计划
|
||||||
|
|
||||||
日期：2026-05-07
|
日期：2026-05-07
|
||||||
|
状态：✅ 已完成
|
||||||
|
|
||||||
## 目标
|
## 目标
|
||||||
搭建一个最小可运行的 FastAPI REST API 示例项目。
|
搭建一个最小可运行的 FastAPI REST API 示例项目。
|
||||||
@ -8,31 +9,41 @@
|
|||||||
## 任务清单
|
## 任务清单
|
||||||
|
|
||||||
### 批次 1：项目基础
|
### 批次 1：项目基础
|
||||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
| # | 任务 | 文件 | 验证 | 状态 |
|
||||||
|---|------|------|------|----------|
|
|---|------|------|------|------|
|
||||||
| 1 | 创建 requirements.txt | requirements.txt | 文件存在 | 1min |
|
| 1 | 创建 requirements.txt | requirements.txt | 文件存在 | ✅ |
|
||||||
| 2 | 创建项目目录结构 | app/, tests/ | 目录存在 | 1min |
|
| 2 | 创建项目目录结构 | app/, tests/ | 目录存在 | ✅ |
|
||||||
| 3 | 编写数据模型 | app/models.py | 导入成功 | 2min |
|
| 3 | 编写数据模型 | app/models.py | 导入成功 | ✅ |
|
||||||
|
|
||||||
### 批次 2：核心实现（TDD）
|
### 批次 2：核心实现（TDD）
|
||||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
| # | 任务 | 文件 | 验证 | 状态 |
|
||||||
|---|------|------|------|----------|
|
|---|------|------|------|------|
|
||||||
| 4 | 写失败测试：健康检查 | tests/test_api.py | pytest FAIL | 2min |
|
| 4 | 写失败测试：健康检查 | tests/test_api.py | pytest FAIL → PASS | ✅ |
|
||||||
| 5 | 实现健康检查端点 | app/main.py | pytest PASS | 2min |
|
| 5 | 实现健康检查端点 | app/main.py | pytest PASS | ✅ |
|
||||||
| 6 | 写失败测试：CRUD | tests/test_api.py | pytest FAIL | 3min |
|
| 6 | 写失败测试：CRUD | tests/test_api.py | pytest FAIL → PASS | ✅ |
|
||||||
| 7 | 实现 CRUD 端点 | app/routes.py | pytest PASS | 5min |
|
| 7 | 实现 CRUD 端点 | app/main.py | pytest PASS | ✅ |
|
||||||
|
|
||||||
### 批次 3：收尾
|
### 批次 3：收尾
|
||||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
| # | 任务 | 文件 | 验证 | 状态 |
|
||||||
|---|------|------|------|----------|
|
|---|------|------|------|------|
|
||||||
| 8 | 添加启动脚本 | run.sh | 脚本可执行 | 1min |
|
| 8 | 添加启动脚本 | run.sh | 脚本可执行 | ✅ |
|
||||||
| 9 | 更新文档 | README.md | 文件存在 | 2min |
|
| 9 | 更新文档 | README.md | 文件存在 | ✅ |
|
||||||
|
|
||||||
## 验证命令
|
## 验证结果
|
||||||
- 单测：`pytest tests/ -v`
|
- ✅ 单测：`pytest tests/ -v` → 5 passed
|
||||||
- 启动：`uvicorn app.main:app --reload`
|
- ✅ API 启动：`uvicorn app.main:app --reload` → 正常响应
|
||||||
|
- ✅ Git 提交：`67d8c6b feat: add FastAPI example project with CRUD API`
|
||||||
|
|
||||||
## 完成标准
|
## 完成标准
|
||||||
- [ ] 所有测试通过
|
- [x] 所有测试通过
|
||||||
- [ ] API 可启动并响应
|
- [x] API 可启动并响应
|
||||||
- [ ] 代码已提交
|
- [x] 代码已提交
|
||||||
|
|
||||||
|
## 实际耗时
|
||||||
|
约 15 分钟
|
||||||
|
|
||||||
|
## 后续扩展建议
|
||||||
|
1. 添加 PUT/DELETE 端点
|
||||||
|
2. 添加数据库持久化
|
||||||
|
3. 添加认证中间件
|
||||||
|
4. 容器化部署（Docker）
|
||||||
23
memory/2026-05-07.md
Normal file
23
memory/2026-05-07.md
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
# 2026-05-07
|
||||||
|
|
||||||
|
## 纪要
|
||||||
|
|
||||||
|
### 项目完成
|
||||||
|
- 完成 FastAPI 示例项目的完整实现
|
||||||
|
- 采用 Design → Plan → TDD → Execute 工作流
|
||||||
|
- Git 提交: `67d8c6b feat: add FastAPI example project with CRUD API`
|
||||||
|
|
||||||
|
### 实现内容
|
||||||
|
- API 端点: /health, /items (GET/POST), /items/{id}
|
||||||
|
- 测试: 5 个测试用例全部通过
|
||||||
|
- 文档: README.md, 计划文档, API 使用示例
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
- 选择 FastAPI + 内存存储方案
|
||||||
|
- **理由**: 零依赖、快速启动、适合示例项目
|
||||||
|
- **影响**: 数据不持久，重启后丢失
|
||||||
|
|
||||||
|
## 后续建议
|
||||||
|
1. 扩展 API (PUT/DELETE)
|
||||||
|
2. 添加数据库 (SQLite/PostgreSQL)
|
||||||
|
3. 容器化部署
|
||||||
7
memory/MEMORY.md
Normal file
7
memory/MEMORY.md
Normal file
@ -0,0 +1,7 @@
|
|||||||
|
# 长期记忆
|
||||||
|
|
||||||
|
## 项目记忆
|
||||||
|
- [FastAPI 示例项目](2026-05-07.md) — 2026-05-07 完成 FastAPI CRUD API 实现
|
||||||
|
|
||||||
|
## 技术决策
|
||||||
|
- FastAPI + 内存存储作为示例项目方案，零依赖快速启动
|
||||||
Loading…
x
Reference in New Issue
Block a user