# fast-api-test

**Repository Path**: rplees/fast-api-test

## Basic Information

- **Project Name**: fast-api-test
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 基础项目框架

这是一个基于 FastAPI 框架搭建的后端服务基础项目，提供了完整的 RESTful API 开发结构和常用功能组件。

## 技术栈

- **Python 3.9+**
- **FastAPI 0.104+** - 高性能的异步 Web 框架
- **SQLAlchemy 2.0+** - ORM 数据库操作
- **Pydantic V2** - 数据验证和设置管理
- **MySQL** - 关系型数据库
- **PyJWT** - JWT 认证
- **PyYAML** - 配置文件解析
- **python-multipart** - 表单数据处理

## 项目结构

```
fast-api-test/
├── app/
│   ├── api/           # API 路由层
│   ├── core/          # 核心配置和中间件
│   ├── database/      # 数据库连接和操作
│   ├── exception/     # 异常处理
│   ├── models/        # 数据模型
│   ├── schemas/       # 数据传输对象
│   ├── services/      # 业务逻辑层
│   └── utils/         # 工具函数
├── application.yml    # 配置文件
├── main.py           # 应用入口
├── start.py          # 启动脚本
├── requirements.txt  # 依赖列表
└── README.md         # 项目说明
```

## 主要功能

- ✅ **统一响应格式** - 基于 RR 模型的标准响应结构
- ✅ **异常处理机制** - 自定义异常类型和错误码系统
- ✅ **配置管理** - 基于 YAML 的配置文件系统
- ✅ **数据库连接池** - 优化的数据库连接管理
- ✅ **请求日志中间件** - API 请求日志记录
- ✅ **CORS 支持** - 跨域资源共享配置
- ✅ **JWT 认证** - 基于令牌的身份验证
- ✅ **分页功能** - 数据分页查询支持

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd fast-api-test
```

### 2. 安装依赖

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

### 3. 配置数据库

编辑 `application.yml` 文件，配置数据库连接信息：

```yaml
database:
  url: mysql+pymysql://root:password@localhost:3306/fastapi-test
  pool:
    size: 10
    max_overflow: 20
    recycle: 3600
```

### 4. 启动服务

```bash
python start.py --port 8001
```

### 5. 访问文档

启动成功后，可以访问以下地址查看 API 文档：

- Swagger UI: http://localhost:8001/docs
- ReDoc: http://localhost:8001/redoc

## API 示例

### 健康检查

```bash
GET /api/health
```

### 用户管理

```bash
# 获取用户列表
GET /api/users

# 获取单个用户
GET /api/users/{user_id}

# 创建用户
POST /api/users

# 更新用户
PUT /api/users/{user_id}

# 删除用户
DELETE /api/users/{user_id}
```

## 开发指南

### 添加新 API

1. 在 `app/api/` 目录下创建新的 API 模块
2. 在 `app/schemas/` 中定义请求和响应模型
3. 在 `app/services/` 中实现业务逻辑
4. 在 `app/api/__init__.py` 中注册路由

### 添加新数据模型

1. 在 `app/models/models.py` 中定义 SQLAlchemy 模型
2. 在 `app/schemas/` 中创建对应的 Pydantic 模型

## 部署说明

### 使用 Docker (示例)

```dockerfile
FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8001

CMD ["python", "start.py", "--port", "8001"]
```

### 生产环境注意事项

- 使用 Gunicorn + Uvicorn 作为 ASGI 服务器
- 配置环境变量覆盖配置文件中的敏感信息
- 设置合适的日志级别和轮转策略
- 启用 HTTPS

## 许可证

本项目采用 MIT 许可证 - 详情请查看 LICENSE 文件