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 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
|
||||
# 创建虚拟环境并安装依赖
|
||||
# 创建虚拟环境
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 启动服务
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
# 方式一：使用启动脚本
|
||||
./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 端点
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
|------|------|------|
|
||||
| GET | /health | 健康检查 |
|
||||
| GET | /items | 列出所有项目 |
|
||||
| POST | /items | 创建新项目 |
|
||||
| GET | /items/{id} | 获取单个项目 |
|
||||
| 方法 | 路径 | 描述 | 请求体 |
|
||||
|------|------|------|--------|
|
||||
| GET | /health | 健康检查 | - |
|
||||
| GET | /items | 列出所有项目 | - |
|
||||
| POST | /items | 创建新项目 | `{"name": "string", "description": "string?"}` |
|
||||
| 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
|
||||
```
|
||||
|
||||
## 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 示例项目实现计划
|
||||
|
||||
日期：2026-05-07
|
||||
状态：✅ 已完成
|
||||
|
||||
## 目标
|
||||
搭建一个最小可运行的 FastAPI REST API 示例项目。
|
||||
@ -8,31 +9,41 @@
|
||||
## 任务清单
|
||||
|
||||
### 批次 1：项目基础
|
||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
||||
|---|------|------|------|----------|
|
||||
| 1 | 创建 requirements.txt | requirements.txt | 文件存在 | 1min |
|
||||
| 2 | 创建项目目录结构 | app/, tests/ | 目录存在 | 1min |
|
||||
| 3 | 编写数据模型 | app/models.py | 导入成功 | 2min |
|
||||
| # | 任务 | 文件 | 验证 | 状态 |
|
||||
|---|------|------|------|------|
|
||||
| 1 | 创建 requirements.txt | requirements.txt | 文件存在 | ✅ |
|
||||
| 2 | 创建项目目录结构 | app/, tests/ | 目录存在 | ✅ |
|
||||
| 3 | 编写数据模型 | app/models.py | 导入成功 | ✅ |
|
||||
|
||||
### 批次 2：核心实现（TDD）
|
||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
||||
|---|------|------|------|----------|
|
||||
| 4 | 写失败测试：健康检查 | tests/test_api.py | pytest FAIL | 2min |
|
||||
| 5 | 实现健康检查端点 | app/main.py | pytest PASS | 2min |
|
||||
| 6 | 写失败测试：CRUD | tests/test_api.py | pytest FAIL | 3min |
|
||||
| 7 | 实现 CRUD 端点 | app/routes.py | pytest PASS | 5min |
|
||||
| # | 任务 | 文件 | 验证 | 状态 |
|
||||
|---|------|------|------|------|
|
||||
| 4 | 写失败测试：健康检查 | tests/test_api.py | pytest FAIL → PASS | ✅ |
|
||||
| 5 | 实现健康检查端点 | app/main.py | pytest PASS | ✅ |
|
||||
| 6 | 写失败测试：CRUD | tests/test_api.py | pytest FAIL → PASS | ✅ |
|
||||
| 7 | 实现 CRUD 端点 | app/main.py | pytest PASS | ✅ |
|
||||
|
||||
### 批次 3：收尾
|
||||
| # | 任务 | 文件 | 验证 | 预计时间 |
|
||||
|---|------|------|------|----------|
|
||||
| 8 | 添加启动脚本 | run.sh | 脚本可执行 | 1min |
|
||||
| 9 | 更新文档 | README.md | 文件存在 | 2min |
|
||||
| # | 任务 | 文件 | 验证 | 状态 |
|
||||
|---|------|------|------|------|
|
||||
| 8 | 添加启动脚本 | run.sh | 脚本可执行 | ✅ |
|
||||
| 9 | 更新文档 | README.md | 文件存在 | ✅ |
|
||||
|
||||
## 验证命令
|
||||
- 单测：`pytest tests/ -v`
|
||||
- 启动：`uvicorn app.main:app --reload`
|
||||
## 验证结果
|
||||
- ✅ 单测：`pytest tests/ -v` → 5 passed
|
||||
- ✅ API 启动：`uvicorn app.main:app --reload` → 正常响应
|
||||
- ✅ Git 提交：`67d8c6b feat: add FastAPI example project with CRUD API`
|
||||
|
||||
## 完成标准
|
||||
- [ ] 所有测试通过
|
||||
- [ ] API 可启动并响应
|
||||
- [ ] 代码已提交
|
||||
- [x] 所有测试通过
|
||||
- [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