# 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-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 脚手架, Python

## README

# FastAPI Template

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

## 功能特性

- 异步全链路（async/await + SQLAlchemy 2.0 异步引擎）
- JWT 认证（Access Token + Refresh Token）
- 服务端 Session 持久化与吊销
- 用户认证（注册、登录、刷新、登出）
- 管理员后台认证
- 文件上传（按日期/用户分目录存储）
- 统一认证依赖注入（`security.py` 集中管理）
- 统一响应格式 + 全局异常处理
- 请求日志中间件（方法/路径/状态码/耗时）
- 每日滚动日志（自动保留 30 天）
- 环境变量/.env 配置覆盖（默认值 < 环境变量）
- 默认 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（aiomysql） |
| 数据验证 | Pydantic 2.5.2 |
| 配置管理 | pydantic-settings + .env |
| 安全 | python-jose + passlib[bcrypt] |
| 包管理 | 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           # 环境变量配置（默认值 < 环境变量/.env）
│   ├── database.py         # 异步引擎 + 会话管理 + 种子数据
│   ├── models.py           # SQLAlchemy 2.0 数据模型
│   ├── crud.py             # 泛型异步 CRUD 封装
│   ├── security.py         # bcrypt + JWT + 服务端会话 + 认证依赖
│   ├── 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 天）
├── sql/init/               # 初始库结构与种子 SQL
├── static/uploads/         # 上传文件存储
└── ui/index.html           # API 测试页面
```

### 模块职责

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

## 快速开始

### 安装依赖

```bash
uv sync
```

### 初始化环境变量

先复制环境变量模版：

```bash
cp .env.example .env
```

Windows PowerShell 可使用：

```powershell
Copy-Item .env.example .env
```

### 启动服务

**方式一：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`
- 密码：`ChangeMe123!`

## API 文档

启动后访问：

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

### 用户 API

| 方法 | 端点 | 功能 | 认证 |
|------|------|------|------|
| POST | `/api/user/register` | 用户注册 | 无 |
| POST | `/api/user/login` | 用户登录 | 无 |
| POST | `/api/user/refresh` | 刷新令牌 | 无 |
| POST | `/api/user/logout` | 用户登出 | Header: `Authorization: Bearer <access_token>` |
| GET | `/api/user/info` | 获取用户信息 | Header: `Authorization: Bearer <access_token>` |
| POST | `/api/upload` | 文件上传 | Header: `Authorization`（可选，兼容旧 `token` 头） |

### 管理员 API

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

### 统一响应格式

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "access_token": "...",
    "refresh_token": "...",
    "token_type": "Bearer",
    "expires_in": 1800,
    "session_id": "..."
  }
}
```

## 配置说明

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

### 切换数据库

默认使用 SQLite，切换 MySQL 只需配置 `.env` 或系统环境变量：

```env
DB_DRIVER=mysql+aiomysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=my_database
DB_USER=root
DB_PASSWORD=your_password
```

### `.env.example`

项目已提供 `/.env.example`，建议以它为基础复制出 `.env` 后再修改。

常见开发配置示例：

```env
SECRET_KEY=hard_to_guess_string
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
DEBUG=true
HOST=0.0.0.0
PORT=8127
UVICORN_RELOAD=true
BASE_URL=http://localhost:8127
DATABASE_URL=sqlite+aiosqlite:///./data/app.db
```

### 环境变量

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

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SECRET_KEY` | 应用密钥 | `hard_to_guess_string` |
| `JWT_ALGORITHM` | JWT 签名算法 | `HS256` |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Access Token 有效分钟数 | `30` |
| `REFRESH_TOKEN_EXPIRE_DAYS` | Refresh Token 有效天数 | `7` |
| `DATABASE_URL` | 数据库连接 URL（优先级最高） | SQLite 本地文件 |
| `DB_DRIVER` | 数据库驱动（用于拼接连接串） | 空 |
| `DB_HOST` | 数据库主机 | 空 |
| `DB_PORT` | 数据库端口 | `3306` |
| `DB_NAME` | 数据库名称 | 空 |
| `DB_USER` | 数据库用户名 | 空 |
| `DB_PASSWORD` | 数据库密码 | 空 |
| `DEBUG` | 调试模式 | `true` |
| `BASE_URL` | 服务器地址 | `http://localhost:8127` |
| `HOST` | 服务监听地址 | `0.0.0.0` |
| `PORT` | 服务监听端口 | `8127` |
| `UVICORN_RELOAD` | 是否开启热重载 | `true` |
| `STATIC_FOLDER` | 静态文件目录 | 项目内 `static` |
| `UPLOAD_FOLDER` | 上传文件目录 | 项目内 `static/uploads` |
| `MAX_CONTENT_LENGTH` | 上传大小限制（字节） | `16777216` |

### 添加依赖

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

## 扩展指南

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

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

## 初始化 SQL

- 基线 SQL 位于 `sql/init/001_schema.sql`
- 初始管理员种子位于 `sql/init/002_seed.sql`
- 这两份 SQL 默认按 SQLite 编写，切换到 MySQL/PostgreSQL 时请按方言调整

## API 测试页面

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

## License

MIT