fastapi-demo/项目文档.md

# 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流程
- 容器化部署支持