5.1 KiB

Raw Permalink Blame History

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. 架构设计

本项目采用了分层架构设计，主要包括以下几层：

API层：处理HTTP请求和响应，定义API路由和端点
服务层：实现业务逻辑，处理数据操作
模型层：定义数据模型和数据库交互
Schema层：处理数据验证、序列化和反序列化

4.1 应用初始化流程

通过main.py中的create_application()函数创建FastAPI应用实例
配置中间件（如CORS）
注册API路由
注册事件处理器（启动和关闭事件）

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 用户模型

class User:
    id: int                   # 用户ID
    username: str             # 用户名
    email: str                # 电子邮件
    full_name: Optional[str]  # 全名（可选）
    is_active: bool           # 是否激活
    created_at: datetime      # 创建时间

7.2 产品模型

class Product:
    id: int                   # 产品ID
    name: str                 # 产品名称
    description: Optional[str] # 产品描述（可选）
    price: float              # 价格
    stock: int                # 库存数量
    is_available: bool        # 是否可用
    created_at: datetime      # 创建时间

8. 启动和运行

8.1 安装依赖

pip install -r requirements.txt

8.2 配置环境变量

创建.env文件，参考.env.example进行配置。

8.3 启动应用

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端点

在app/api/v1/endpoints/目录下创建新的端点文件
在app/api/v1/router.py中注册新的路由

9.2 添加新的数据模型

在app/models/目录下创建新的模型文件
在app/schemas/目录下创建对应的Schema文件
在app/services/目录下创建对应的服务文件

10. 未来扩展

添加数据库集成（如SQLAlchemy）
实现用户认证和授权
添加更多的API端点和功能
实现单元测试和集成测试
添加CI/CD流程
容器化部署支持

5.1 KiB Raw Permalink Blame History Unescape Escape