fastapi-crud-api/README.md

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

安装

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

启动服务

# 方式一：使用启动脚本
./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}	获取单个项目	-

示例请求

# 健康检查
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"}

测试

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 - 现代 Python Web 框架
• Pydantic - 数据验证
• Uvicorn - ASGI 服务器
• pytest - 测试框架
• httpx - HTTP 客户端

License

MIT