# fastApi基础项目模板

**Repository Path**: adent_sun/fastapi_template

## Basic Information

- **Project Name**: fastApi基础项目模板
- **Description**: FastApi模板，用于快速构建项目
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-21
- **Last Updated**: 2025-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fastapi模板项目

这是一个基于 FastAPI 和 MySQL 构建的 RESTful API 项目，实现了用户(User)和物品(Item)的基本 CRUD 操作。

## 目录结构

```
.
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   ├── items.py
│   │       │   └── users.py
│   │       └── router.py
│   ├── core/
│   │   ├── dependencies.py
│   │   └── settings.py
│   ├── db/
│   │   ├── base.py
│   │   └── session.py
│   ├── models/
│   │   ├── item.py
│   │   └── user.py
│   ├── schemas/
│   │   ├── item.py
│   │   ├── response.py
│   │   └── user.py
│   └── services/
│       ├── impl/
│       │   ├── ItemServiceImpl.py
│       │   └── UserServiceImpl.py
│       ├── ItemService.py
│       └── UserService.py
├── main.py
└── requirements.txt
```

## 功能特性

1. 使用 FastAPI 构建高性能异步 API
2. 使用 SQLAlchemy ORM 操作 MySQL 数据库
3. 实现用户和物品的完整 CRUD 操作
4. 使用 Pydantic 进行数据校验和序列化
5. 采用分层架构设计（MVC-like）：
   - Models: 数据模型定义
   - Schemas: 数据校验和序列化
   - Services: 业务逻辑实现
   - APIs: 路由和接口定义
6. 统一响应格式
7. 数据库连接池管理
8. 环境变量配置管理

## 技术栈

- Python 3.8+
- FastAPI - 高性能 Web 框架
- SQLAlchemy - ORM 工具
- Pydantic - 数据校验和设置管理
- MySQL - 关系型数据库
- Uvicorn - ASGI 服务器

## 安装与运行

### 环境要求

- Python 3.11 版本
- MySQL 数据库

### 安装步骤

1. 克隆项目代码：

```bash
git clone <repository-url>
cd fastapi-mysql-project
```

2. 使用conda创建虚拟环境并激活：

```bash
conda create -n fastapi-template python=3.11
conda activate fastapi-template
```

3. 安装依赖：

```bash
pip install -r requirements.txt
```

或者使用conda安装依赖：

```bash
conda install --file requirements.txt
```

4. 配置环境变量：

在项目根目录下创建 `.env` 文件，并添加以下内容：

```env
DB_USER=your_mysql_username
DB_PASSWORD=your_mysql_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database_name
```

5. 在 MySQL 中创建数据库：

```sql
CREATE DATABASE your_database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

6. 启动应用：

```bash
python main.py
```

或者使用 uvicorn：

```bash
uvicorn main:app --reload
```

应用将在 `http://localhost:8000` 上运行。

## API 接口说明

### 用户相关接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/users/` | 获取所有用户 |
| POST | `/api/v1/users/` | 创建新用户 |
| GET | `/api/v1/users/{id}` | 根据 ID 获取用户 |
| PUT | `/api/v1/users/{id}` | 根据 ID 更新用户 |
| DELETE | `/api/v1/users/{id}` | 根据 ID 删除用户 |

### 物品相关接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/items/` | 获取所有物品 |
| POST | `/api/v1/items/` | 创建新物品 |
| GET | `/api/v1/items/{id}` | 根据 ID 获取物品 |
| PUT | `/api/v1/items/{id}` | 根据 ID 更新物品 |
| DELETE | `/api/v1/items/{id}` | 根据 ID 删除物品 |

## 项目架构详解

### 核心组件

#### 1. 主应用入口 (`main.py`)

这是整个应用程序的入口点，负责初始化 FastAPI 应用并注册路由。

#### 2. 配置管理 (`app/core/settings.py`)

使用 Pydantic 的 `BaseSettings` 来管理应用配置，支持从环境变量读取敏感信息如数据库连接信息。

#### 3. 数据库连接 (`app/db/session.py`)

配置 SQLAlchemy 数据库引擎和会话管理器，包含连接池设置以提高性能。

#### 4. 数据模型 (`app/models/`)

使用 SQLAlchemy 定义数据库表结构：
- User 模型：存储用户信息（id, name, email）
- Item 模型：存储物品信息（id, title, owner_id）

#### 5. 数据传输对象 (`app/schemas/`)

使用 Pydantic 定义数据验证和序列化模式：
- UserCreate, UserUpdate, UserResponse：用户相关的数据模式
- ItemCreate, ItemUpdate, ItemResponse：物品相关的数据模式

#### 6. 服务层 (`app/services/`)

采用面向接口编程的设计模式：
- 抽象服务接口：UserService, ItemService
- 具体实现类：UserServiceImpl, ItemServiceImpl

#### 7. API 层 (`app/api/v1/`)

实现 RESTful API 接口，处理 HTTP 请求和响应：
- 路由配置：router.py
- 用户接口：users.py
- 物品接口：items.py

#### 8. 依赖管理 (`app/core/dependencies.py`)

提供数据库会话等依赖项注入功能。

#### 9. 响应格式 (`app/schemas/response.py`)

统一 API 响应格式，包括成功和错误响应。

## 数据库设计

### 用户表 (users)

| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INTEGER | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| name | VARCHAR(50) | NOT NULL | 用户名 |
| email | VARCHAR(100) | UNIQUE, NOT NULL | 邮箱地址 |

### 物品表 (items)

| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INTEGER | PRIMARY KEY, AUTO_INCREMENT | 物品ID |
| title | VARCHAR(100) | NOT NULL | 物品标题 |
| owner_id | INTEGER | FOREIGN KEY (users.id) ON DELETE CASCADE | 所属用户ID |

### 索引优化

- 用户表：在 name 和 email 字段上分别创建索引
- 物品表：在 owner_id 字段上创建索引以优化关联查询

## 开发规范

1. 遵循 RESTful API 设计原则
2. 使用 Pydantic 进行输入验证
3. 采用分层架构，保持代码清晰分离
4. 统一错误处理和响应格式
5. 添加必要的注释和文档

## 许可证

本项目仅供学习和参考使用。