188 lines
5.1 KiB
Markdown
188 lines
5.1 KiB
Markdown
# FastAPI Demo 项目文档
|
||
|
||
## 1. 项目概述
|
||
|
||
**项目名称**：FastAPI Demo
|
||
**版本**：1.0.0
|
||
**描述**：一个简单的FastAPI学习项目
|
||
|
||
本项目是一个基于FastAPI框架开发的RESTful API示例应用，实现了用户管理和产品管理的基本功能。项目采用了模块化的架构设计，遵循了最佳实践，适合作为FastAPI学习和开发的参考。
|
||
|
||
## 2. 技术栈
|
||
|
||
- **后端框架**：FastAPI
|
||
- **编程语言**：Python
|
||
- **API文档**：Swagger UI (通过FastAPI自动生成)
|
||
- **数据存储**：当前使用内存模拟数据库，可扩展为真实数据库
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
fastapi-demo-git/
|
||
├── app/ # 应用主目录
|
||
│ ├── api/ # API路由定义
|
||
│ │ └── v1/ # API v1版本
|
||
│ │ ├── endpoints/ # API端点实现
|
||
│ │ └── router.py # 路由聚合
|
||
│ ├── core/ # 核心配置和应用创建
|
||
│ │ ├── application.py # 应用工厂
|
||
│ │ └── config.py # 配置管理
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── product.py # 产品模型
|
||
│ │ └── user.py # 用户模型
|
||
│ ├── schemas/ # 数据验证和序列化
|
||
│ │ ├── product.py # 产品Schema
|
||
│ │ └── user.py # 用户Schema
|
||
│ └── services/ # 业务逻辑服务
|
||
│ ├── product_service.py # 产品服务
|
||
│ └── user_service.py # 用户服务
|
||
├── .env.example # 环境变量示例
|
||
├── main.py # 应用入口
|
||
└── requirements.txt # 项目依赖
|
||
```
|
||
|
||
## 4. 架构设计
|
||
|
||
本项目采用了分层架构设计，主要包括以下几层：
|
||
|
||
1. **API层**：处理HTTP请求和响应，定义API路由和端点
|
||
2. **服务层**：实现业务逻辑，处理数据操作
|
||
3. **模型层**：定义数据模型和数据库交互
|
||
4. **Schema层**：处理数据验证、序列化和反序列化
|
||
|
||
### 4.1 应用初始化流程
|
||
|
||
1. 通过`main.py`中的`create_application()`函数创建FastAPI应用实例
|
||
2. 配置中间件（如CORS）
|
||
3. 注册API路由
|
||
4. 注册事件处理器（启动和关闭事件）
|
||
|
||
## 5. 配置管理
|
||
|
||
项目使用Pydantic的`BaseSettings`进行配置管理，支持从环境变量和`.env`文件加载配置。主要配置项包括：
|
||
|
||
- 应用基础配置（项目名称、版本等）
|
||
- 服务器配置（主机、端口等）
|
||
- API配置
|
||
- 数据库配置
|
||
- CORS配置
|
||
- JWT认证配置
|
||
- 邮件配置
|
||
- 文件上传配置
|
||
- 第三方API配置
|
||
- 监控配置
|
||
- 限流配置
|
||
|
||
## 6. API接口文档
|
||
|
||
### 6.1 用户管理API
|
||
|
||
#### 获取所有用户
|
||
|
||
- **URL**: `/api/v1/users/`
|
||
- **方法**: GET
|
||
- **描述**: 获取所有用户列表
|
||
- **响应**: 用户对象数组
|
||
|
||
#### 获取单个用户
|
||
|
||
- **URL**: `/api/v1/users/{user_id}`
|
||
- **方法**: GET
|
||
- **描述**: 根据ID获取单个用户
|
||
- **参数**:
|
||
- `user_id`: 用户ID (路径参数)
|
||
- **响应**: 用户对象
|
||
- **错误**: 404 - 用户不存在
|
||
|
||
### 6.2 产品管理API
|
||
|
||
#### 获取所有产品
|
||
|
||
- **URL**: `/api/v1/products/`
|
||
- **方法**: GET
|
||
- **描述**: 获取所有商品列表
|
||
- **响应**: 产品对象数组
|
||
|
||
#### 获取单个产品
|
||
|
||
- **URL**: `/api/v1/products/{product_id}`
|
||
- **方法**: GET
|
||
- **描述**: 根据ID获取单个商品
|
||
- **参数**:
|
||
- `product_id`: 产品ID (路径参数)
|
||
- **响应**: 产品对象
|
||
- **错误**: 404 - 产品不存在
|
||
|
||
## 7. 数据模型
|
||
|
||
### 7.1 用户模型
|
||
|
||
```python
|
||
class User:
|
||
id: int # 用户ID
|
||
username: str # 用户名
|
||
email: str # 电子邮件
|
||
full_name: Optional[str] # 全名（可选）
|
||
is_active: bool # 是否激活
|
||
created_at: datetime # 创建时间
|
||
```
|
||
|
||
### 7.2 产品模型
|
||
|
||
```python
|
||
class Product:
|
||
id: int # 产品ID
|
||
name: str # 产品名称
|
||
description: Optional[str] # 产品描述（可选）
|
||
price: float # 价格
|
||
stock: int # 库存数量
|
||
is_available: bool # 是否可用
|
||
created_at: datetime # 创建时间
|
||
```
|
||
|
||
## 8. 启动和运行
|
||
|
||
### 8.1 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 8.2 配置环境变量
|
||
|
||
创建`.env`文件，参考`.env.example`进行配置。
|
||
|
||
### 8.3 启动应用
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
默认情况下，应用将在 http://127.0.0.1:8000 上运行。
|
||
|
||
### 8.4 访问API文档
|
||
|
||
- Swagger UI: http://127.0.0.1:8000/docs
|
||
- ReDoc: http://127.0.0.1:8000/redoc
|
||
|
||
## 9. 开发指南
|
||
|
||
### 9.1 添加新的API端点
|
||
|
||
1. 在`app/api/v1/endpoints/`目录下创建新的端点文件
|
||
2. 在`app/api/v1/router.py`中注册新的路由
|
||
|
||
### 9.2 添加新的数据模型
|
||
|
||
1. 在`app/models/`目录下创建新的模型文件
|
||
2. 在`app/schemas/`目录下创建对应的Schema文件
|
||
3. 在`app/services/`目录下创建对应的服务文件
|
||
|
||
## 10. 未来扩展
|
||
|
||
- 添加数据库集成（如SQLAlchemy）
|
||
- 实现用户认证和授权
|
||
- 添加更多的API端点和功能
|
||
- 实现单元测试和集成测试
|
||
- 添加CI/CD流程
|
||
- 容器化部署支持 |