# fastapi_blog

**Repository Path**: python_90/fastapi_blog

## Basic Information

- **Project Name**: fastapi_blog
- **Description**: fastapi_blog
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI Blog

基于 FastAPI 框架构建的博客系统。

## 技术栈

- Python >= 3.12
- FastAPI + Uvicorn[standard]
- Tortoise ORM + Aerich（异步 ORM 与迁移工具）
- MySQL（aiomysql 异步驱动）
- fastapi-mail（异步邮件发送）
- cachetools（内存 TTL 缓存）
- pydantic-settings（.env 配置加载）
- bcrypt（密码哈希）
- uv（依赖管理，清华镜像源）

## 快速开始

### 安装依赖

```bash
uv sync
```

### 配置环境变量

复制 `.env.example` 为 `.env` 并填入实际值：

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

需配置数据库连接与邮件 SMTP 信息（QQ 邮箱需用授权码而非登录密码）。

### 启动开发服务

方式一：使用启动脚本（推荐）

```bash
uv run python start.py
```

方式二：直接通过 uvicorn 启动

```bash
uv run uvicorn app.main:myapp --reload
```

方式三：Windows 一键启动

```bat
run.bat
```

启动后访问 http://127.0.0.1:8000，API 文档见 http://127.0.0.1:8000/docs。

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 健康检查 |
| POST | `/api/verify_code?email=xxx@qq.com` | 发送邮箱验证码（1 分钟频率限制，3 分钟有效） |
| POST | `/api/register` | 用户注册（校验验证码+邮箱唯一，密码 bcrypt 哈希存储） |

## 数据库迁移

首次初始化 Aerich（生成 `pyproject.toml` 中的 `[tool.tortoise]` 配置）：

```bash
uv run aerich init -t app.core.config.TORTOISE_ORM
```

根据模型首次生成表结构并写入迁移记录（仅首次使用，后续用 `migrate` + `upgrade`）：

```bash
uv run aerich init-db
```

生成迁移文件：

```bash
uv run aerich migrate --name add_table
```

应用迁移到数据库：

```bash
uv run aerich upgrade
```

> 数据库连接配置见 `app/core/config.py`，通过 `pydantic-settings` 从 `.env` 加载，默认连接 `mysql://root:root@127.0.0.1:3306/fapi_blog`（phpEnv MySQL 5.7）。

## 项目结构

```
blog/
├── app/                        # 应用主包
│   ├── main.py                 # FastAPI 入口，创建应用实例与注册路由
│   ├── core/                   # 核心配置与基础设施
│   │   ├── config.py           # pydantic-settings 配置 + Tortoise ORM 连接
│   │   ├── cache.py            # TTL 内存缓存封装（验证码等）
│   │   └── depens.py           # FastAPI 依赖注入函数
│   ├── models/                 # 数据库模型（Tortoise ORM Model）
│   │   └── users.py            # 用户模型（id/username/password/email/is_delete）
│   ├── routers/                # 路由处理器
│   │   └── auth.py             # 认证路由（验证码发送、用户注册）
│   ├── schemas/                # Pydantic 请求/响应模型
│   │   ├── auth.py             # 注册请求参数 RegisterParam
│   │   └── common.py           # 统一响应模型 ApiResult
│   ├── services/               # 业务逻辑层
│   │   └── auth.py             # 认证服务（验证码生成发送、用户注册）
│   └── utils/                  # 工具函数
│       ├── smtp.py             # fastapi-mail 邮件发送封装
│       └── pwd.py              # bcrypt 密码哈希与校验
├── migrations/                 # Aerich 迁移文件目录
├── start.py                    # uvicorn 启动脚本
├── run.bat                     # Windows 启动批处理
├── db.bat                      # Aerich 初始化批处理
├── pyproject.toml              # 项目配置与依赖声明
├── uv.toml                     # uv 镜像源配置（清华源）
├── uv.lock                     # 依赖锁定文件
├── .env.example                # 环境变量模板
└── README.md
```

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DB_HOST` | 数据库主机 | 127.0.0.1 |
| `DB_PORT` | 数据库端口 | 3306 |
| `DB_USER` | 数据库用户 | root |
| `DB_PASSWORD` | 数据库密码 | root |
| `DB_NAME` | 数据库名 | fapi_blog |
| `SMTP_HOST` | SMTP 服务器 | smtp.qq.com |
| `SMTP_PORT` | SMTP 端口 | 465 |
| `SMTP_USER` | SMTP 账号 | - |
| `SMTP_PASSWORD` | SMTP 授权码 | - |
| `SMTP_FROM` | 发件人地址 | - |
| `SMTP_STARTTLS` | 启用 STARTTLS | False |
| `SMTP_SSL_TLS` | 启用 SSL/TLS | True |

## 依赖说明

- `fastapi`：Web 框架
- `uvicorn[standard]`：ASGI 服务器，`[standard]` 额外引入 httptools、websockets、watchfiles、PyYAML 等
- `tortoise-orm`：异步 ORM，类似 Django ORM 的 API 风格
- `aerich[toml]`：Tortoise ORM 数据库迁移工具
- `aiomysql`：MySQL 异步驱动
- `fastapi-mail`：异步邮件发送，封装 SMTP 操作
- `cachetools`：内存缓存，提供 TTLCache（带过期时间）
- `pydantic-settings`：从 `.env` 加载配置到 Pydantic 模型
- `bcrypt`：密码哈希算法，自带随机盐值，抗彩虹表
- `tzdata`：IANA 时区数据库，Windows 平台 `zoneinfo` 依赖

## 开发工具

```bash
# 代码检查
uv run ruff check .

# 代码格式化
uv run ruff format .

# 运行测试
uv run pytest
```