# FastAPI Example

一个最小化的 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
```

### 启动服务

```bash
# 方式一：使用启动脚本
./run.sh

# 方式二：直接运行
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 | 创建新项目 | `{"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"}
```

## 测试

```bash
source .venv/bin/activate
pytest tests/ -v
```

测试覆盖：
- `test_health_check` - 健康检查端点
- `test_create_item` - 创建项目
- `test_list_items` - 列出项目
- `test_get_item` - 获取单个项目
- `test_get_item_not_found` - 404 错误处理

## 开发指南

### 添加新端点

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