# fastapi-template

**Repository Path**: ggxx/fastapi-template

## Basic Information

- **Project Name**: fastapi-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 脚手架, Python

## README

# FastAPI Template

FastAPI 项目模板，异步优先，开箱即用。

## 功能特性

- 异步全链路（async/await + SQLAlchemy 2.0 异步引擎）
- 用户认证（注册、登录、Token 验证）
- 管理员后台认证
- 文件上传（按日期/用户分目录存储）
- 统一认证依赖注入（`security.py` 集中管理）
- 统一响应格式 + 全局异常处理
- 请求日志中间件（方法/路径/状态码/耗时）
- 每日滚动日志（自动保留 30 天）
- 三层配置覆盖（默认值 < config.yaml < 环境变量）
- 默认 SQLite 开发，一行配置切 MySQL
- uv 包管理 + lockfile 精确锁定

## 技术栈

| 类别 | 技术 |
|------|------|
| Web 框架 | FastAPI 0.104.1 |
| ASGI 服务器 | Uvicorn 0.24.0 |
| 生产部署 | Gunicorn 21.2.0 + UvicornWorker |
| ORM | SQLAlchemy 2.0.23（异步） |
| 数据库 | SQLite（默认）/ MySQL（asyncmy） |
| 数据验证 | Pydantic 2.5.2 |
| 配置管理 | pydantic-settings + YAML |
| 包管理 | uv |

## 项目结构

```
fastapi-template/
├── app_dev.py              # PyCharm 启动入口
├── app.bat                 # Windows 开发启动
├── app.sh                  # Linux 生产部署（gunicorn start/stop/restart）
├── pyproject.toml          # 项目依赖声明
├── uv.lock                 # 依赖锁文件
├── app/
│   ├── __init__.py         # 应用工厂 + 日志初始化
│   ├── config.py           # 三层配置（默认值 < YAML < 环境变量）
│   ├── config.yaml         # YAML 配置文件
│   ├── database.py         # 异步引擎 + 会话管理 + 种子数据
│   ├── models.py           # SQLAlchemy 2.0 数据模型
│   ├── crud.py             # 泛型异步 CRUD 封装
│   ├── security.py         # 密码哈希 + Token 生成/验证 + 认证依赖
│   ├── exceptions.py       # 全局异常处理器
│   ├── middleware.py        # 请求日志中间件
│   ├── schemas/
│   │   ├── common.py       # 通用响应模型 ResponseModel[T]
│   │   ├── user.py         # 用户相关 Schema
│   │   └── upload.py       # 上传相关 Schema
│   └── routers/
│       ├── __init__.py     # 路由注册
│       ├── user.py         # 用户路由（注册/登录/信息）
│       ├── upload.py       # 文件上传路由
│       └── admin.py        # 管理员路由
├── gunicorn/config.py      # Gunicorn 生产配置
├── data/                   # SQLite 数据库（运行时自动创建）
├── logs/                   # 日志文件（每日滚动，保留 30 天）
├── static/uploads/         # 上传文件存储
└── ui/index.html           # API 测试页面
```

### 模块职责

| 模块 | 职责 |
|------|------|
| `__init__.py` | 应用工厂，组装中间件/异常/路由/静态文件 |
| `config.py` | 三层配置加载（默认值 → YAML → 环境变量） |
| `database.py` | 引擎创建、会话工厂、建表、种子数据初始化 |
| `models.py` | ORM 模型定义 |
| `crud.py` | 泛型 CRUD（get_by_id / get_one / get_all / add / update / delete） |
| `security.py` | 密码哈希、Token 生成与验证、FastAPI 认证依赖 |
| `exceptions.py` | HTTP 异常、参数验证异常、未捕获异常的统一处理 |
| `middleware.py` | HTTP 请求日志记录 |
| `schemas/` | Pydantic 请求/响应模型 |
| `routers/` | 路由定义，按业务域拆分 |

## 快速开始

### 安装依赖

```bash
uv sync
```

### 启动服务

**方式一：PyCharm**

右键运行 `app_dev.py`

**方式二：命令行开发模式**（热重载）

```bash
# Windows
app.bat

# Linux / macOS
uv run uvicorn app:create_app --factory --host 0.0.0.0 --port 8127 --reload
```

**方式三：Linux 生产部署**

```bash
chmod +x app.sh
./app.sh start    # 启动
./app.sh status   # 状态
./app.sh restart  # 重启
./app.sh stop     # 停止
```

服务默认运行在 `http://localhost:8127`

### 默认管理员

首次启动自动创建：

- 用户名：`admin`
- 密码：`123456`

## API 文档

启动后访问：

- Swagger UI：`http://localhost:8127/docs`
- ReDoc：`http://localhost:8127/redoc`

### 用户 API

| 方法 | 端点 | 功能 | 认证 |
|------|------|------|------|
| POST | `/api/user/register` | 用户注册 | 无 |
| POST | `/api/user/login` | 用户登录 | 无 |
| GET | `/api/user/info` | 获取用户信息 | Header: `token` |
| POST | `/api/upload` | 文件上传 | Header: `token`（可选） |

### 管理员 API

| 方法 | 端点 | 功能 | 认证 |
|------|------|------|------|
| POST | `/admin/api/login` | 管理员登录 | 无 |
| POST | `/admin/api/logout` | 管理员登出 | 无 |
| GET | `/admin/api/info` | 获取管理员信息 | Header: `Authorization` |

### 统一响应格式

```json
{
  "code": 200,
  "message": "成功",
  "data": { ... }
}
```

## 配置说明

配置优先级：**代码默认值 < config.yaml < 环境变量/.env**

### 切换数据库

默认使用 SQLite，切换 MySQL 只需编辑 `app/config.yaml`：

```yaml
database:
  driver: mysql+asyncmy
  host: 127.0.0.1
  port: 3306
  name: my_database
  user: root
  password: your_password
```

### 环境变量

也可通过 `.env` 文件或环境变量覆盖任意配置：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SECRET_KEY` | 应用密钥 | `hard_to_guess_string` |
| `DATABASE_URL` | 数据库连接 URL（直接指定则跳过 YAML 拼接） | SQLite 本地文件 |
| `DEBUG` | 调试模式 | `true` |
| `BASE_URL` | 服务器地址 | `http://localhost:8127` |

### 添加依赖

```bash
uv add <包名>        # 自动更新 pyproject.toml + uv.lock
```

## 扩展指南

模板按"单文件 → 需要时再拆包"的原则组织：

- **新增模型**：在 `models.py` 中添加。模型多了（5+）再拆为 `models/` 包
- **新增路由**：在 `routers/` 下新建文件，在 `routers/__init__.py` 中注册
- **新增中间件**：在 `middleware.py` 中添加。中间件多了再拆为 `middleware/` 包
- **新增 CRUD**：`crud.py` 提供泛型函数，直接复用即可

## API 测试页面

访问 `http://localhost:8127/ui/` 可使用内置测试页面。

## License

MIT