# FastAPI

**Repository Path**: duanzhao0265/fast-api

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 学习项目与 Toutiao MVP

这是一个以 FastAPI 为主线的学习仓库，同时包含一个可运行的 Toutiao 新闻资讯 MVP。
课程 Demo 用于按天学习；`backend/app` 与 `frontend` 则是当前可联调的前后端应用。

产品范围、优先级与验收依据见 [Toutiao 需求规格](docs/toutiao-requirements.md)；技术选型、架构、部署和接口契约见 [Toutiao 技术设计与接口规范](docs/toutiao-technical-design.md)。本文档只描述当前仓库已经落地、可以运行和验证的实现。

## 当前状态

已实现：

- FastAPI + SQLAlchemy + SQLite 后端，按 `config`、`models`、`schemas`、`crud`、`routers`、`cache`、`utils` 分层。
- Vue 3 + Vite + Vant 4 移动端界面，包含新闻、认证、收藏、历史、资料、设置和 AI 问答页面。
- `/api` 统一响应、Bearer Token、CORS、分页、SSE 流式响应、本地 TTL 缓存和自动化测试。
- 七天 FastAPI 学习资料和独立 Demo。

当前不包含：MySQL 迁移、Redis、真实大模型供应商、英文 UI 全量翻译、Docker/Nginx 生产配置。这些能力不能视为已交付功能。

## 快速启动

环境要求：Python 3.11、[uv](https://docs.astral.sh/uv/)、Node.js 18+、npm。

在两个终端分别启动后端和前端：

```powershell
# 终端 1：后端
cd E:\codes\fastapi\backend
uv sync
uv run uvicorn main:app --reload --host 127.0.0.1 --port 8000
```

```powershell
# 终端 2：前端
cd E:\codes\fastapi\frontend
npm.cmd install
npm.cmd run dev -- --host 127.0.0.1 --port 5173
```

打开以下地址：

- Web UI：<http://127.0.0.1:5173/>
- Swagger UI：<http://127.0.0.1:8000/docs>
- ReDoc：<http://127.0.0.1:8000/redoc>
- OpenAPI：<http://127.0.0.1:8000/openapi.json>

前端开发服务器会把 `/api/*` 自动代理到 `http://127.0.0.1:8000`。部署到其他 API 地址时，可在 `frontend/.env` 设置：

```dotenv
VITE_API_BASE_URL=https://api.example.com/api
```

示例见 `frontend/.env.example`。本地 SQLite 数据库默认写入 `backend/toutiao.db`；可通过 `TOUTIAO_DATABASE_URL` 覆盖：

```powershell
$env:TOUTIAO_DATABASE_URL = 'sqlite:///E:/data/toutiao.db'
```

## 验证

```powershell
cd E:\codes\fastapi\backend
uv run python -m compileall app main.py toutiao_api.py tests
uv run pytest

cd E:\codes\fastapi\frontend
npm.cmd run build
```

当前后端测试覆盖新闻、认证、收藏、历史、AI SSE、CORS 和改密后的 Token 失效。前端构建会验证所有页面路由和 Vant 组件导入。

## 项目结构

```text
fastapi/
├── backend/
│   ├── app/
│   │   ├── config/          # 数据库 URL、Engine、Session、ORM Base
│   │   ├── models/          # SQLAlchemy 实体
│   │   ├── schemas/         # Pydantic 请求模型
│   │   ├── crud/            # 用户、新闻、互动、AI 的业务与持久化逻辑
│   │   ├── routers/         # 按业务模块划分的 APIRouter
│   │   ├── cache/           # 本地 TTL 缓存抽象
│   │   ├── utils/           # 响应、认证、Token、密码工具
│   │   └── main.py          # FastAPI 组合根、CORS、生命周期、路由注册
│   ├── demos/               # Day 1 - Day 7 学习 Demo
│   ├── tests/               # FastAPI TestClient 测试
│   ├── main.py              # 兼容 ASGI 入口，导出 app.main:app
│   └── pyproject.toml
├── frontend/
│   └── src/
│       ├── api/             # Axios、SSE、Token 和统一错误处理
│       ├── components/      # 可复用展示组件
│       ├── composables/     # 主题和格式化逻辑
│       ├── layouts/         # 顶部导航与 TabBar
│       ├── router/          # 路由与登录守卫
│       ├── stores/          # Pinia 领域状态
│       └── views/           # 路由页面
├── docs/                    # 七天学习资料与课件
└── README.md
```

## 后端架构

请求处理路径如下：

```text
HTTP Request
  -> CORS / validation / exception handler
  -> routers/                路由和依赖注入
  -> crud/                   业务逻辑与数据库查询
  -> models/ / cache/        SQLAlchemy ORM 与本地 TTL 缓存
  -> utils/response.py       { code, message, data }
```

### 分层职责

| 目录 | 职责 |
| --- | --- |
| `app/config` | 读取 `TOUTIAO_DATABASE_URL`，创建 SQLAlchemy Engine、Session 和 Base。 |
| `app/models` | 用户、Token、新闻分类、新闻、收藏和历史的 ORM 映射。 |
| `app/schemas` | 请求体校验，例如用户名、密码、资料、新闻 ID 与 AI 消息。 |
| `app/crud` | 查询、分页、Token 更新、收藏历史变更、种子数据和 AI 演示逻辑。 |
| `app/routers` | `/api/user`、`/api/news`、`/api/favorite`、`/api/history`、`/api/ai`。 |
| `app/cache` | 默认 600 秒本地内存缓存，缓存分类和新闻列表；可替换为 Redis 实现。 |
| `app/utils` | PBKDF2-HMAC-SHA256 密码散列、Bearer Token、统一成功和错误响应。 |

`backend/toutiao_api.py` 仅为历史测试和课程示例提供兼容导出，新代码不应继续写入该文件。

### 数据与认证

- 首次启动会建表并写入三类、六条演示新闻。
- 用户名唯一；收藏和历史记录在数据库层按 `(user_id, news_id)` 唯一。
- Token 有效期为 7 天；同一用户新登录会覆盖旧 Token。
- 修改密码会撤销该用户所有旧 Token，客户端必须重新登录。
- 密码使用 PBKDF2-HMAC-SHA256 存储，不保存明文。

## API 约定

基础路径：`/api`。除 SSE 外，所有接口均使用：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

受保护接口请求头：

```http
Authorization: Bearer <token>
```

| 模块 | 方法 | 路径 | 是否认证 | 说明 |
| --- | --- | --- | --- | --- |
| 用户 | POST | `/api/user/register` | 否 | 注册并返回 Token |
| 用户 | POST | `/api/user/login` | 否 | 登录并返回新 Token |
| 用户 | GET | `/api/user/info` | 是 | 获取当前用户资料 |
| 用户 | PUT | `/api/user/update` | 是 | 部分更新昵称、简介、头像、性别、手机号 |
| 用户 | PUT | `/api/user/password` | 是 | 修改密码并撤销旧 Token |
| 新闻 | GET | `/api/news/categories` | 否 | `skip`、`limit` 分页分类 |
| 新闻 | GET | `/api/news/list` | 否 | `categoryId`、`page`、`pageSize` 新闻列表 |
| 新闻 | GET | `/api/news/detail` | 否 | `id` 新闻详情与相关推荐 |
| 收藏 | POST | `/api/favorite/add` | 是 | 请求体 `{ "newsId": 1 }` |
| 收藏 | DELETE | `/api/favorite/remove` | 是 | 请求体 `{ "newsId": 1 }` |
| 收藏 | GET | `/api/favorite/list` | 是 | 收藏分页列表 |
| 收藏 | GET | `/api/favorite/check` | 是 | `newsId` 收藏状态 |
| 历史 | POST | `/api/history/add` | 是 | 添加或更新阅读历史 |
| 历史 | GET | `/api/history/list` | 是 | 历史分页列表 |
| 历史 | DELETE | `/api/history/delete/{history_id}` | 是 | 删除单条历史 |
| 历史 | DELETE | `/api/history/clear` | 是 | 清空当前用户历史 |
| AI | POST | `/api/ai/chat` | 否 | 普通 JSON 或 `stream: true` 的 SSE 响应 |

API 的可执行参数和示例以 Swagger UI 为准。

## 前端架构

前端采用 Vue 3、Vue Router、Pinia、Axios 与 Vant 4。

- `App.vue` 只挂载 `AppLayout`；页面不再集中在单一组件。
- 路由页面按需加载；受保护页面由路由元数据统一守卫。
- API 模块统一注入 Bearer Token，处理超时、统一响应和 401 跳转。
- AI 流式响应在 `api` 层处理 SSE，页面卸载时中止未完成请求。
- Pinia 划分 `user`、`news`、`favorite`、`history`、`theme`、`language` 状态。
- 图片使用 Vant 懒加载、加载态和缺图占位；列表使用 `List`、`PullRefresh`、`Skeleton`、`Empty` 与 `SwipeCell`。
- Vant 在 `main.js` 显式注册实际使用的组件和样式，不再全量注册。

当前界面全部为简体中文。语言状态已持久化，但英文翻译字典和完整切换尚未实现。

## 七天学习课程

学习 Demo 与完整 MVP 独立，按日学习时请运行对应目录的应用，不要直接修改完整 MVP 代码。

| Day | 主题 | Demo |
| --- | --- | --- |
| 1 | API、HTTP、路由与状态码 | `backend/demos/lesson_01_api_basics/` |
| 2 | 路径、查询、请求体与 Pydantic | `backend/demos/lesson_02_request_validation/` |
| 3 | 响应模型、异常与 CRUD | `backend/demos/lesson_03_response_crud/` |
| 4 | APIRouter、Depends 与项目结构 | `backend/demos/lesson_04_structure_dependencies/` |
| 5 | SQLAlchemy 与 SQLite | `backend/demos/lesson_05_database/` |
| 6 | Token、权限与 pytest | `backend/demos/lesson_06_auth_testing/` |
| 7 | 异步、部署与综合实践 | `backend/demos/lesson_07_deployment_capstone/` |

更多学习安排见：

- [七天快速入门](docs/7-day-fastapi-quickstart.md)
- [课程总览](docs/README.md)
- [每日课程目标](docs/courseware/README.md)
- [学习进度](docs/progress.md)

## 开发约定

- 新后端功能按 `router -> schema -> crud -> model` 的边界实现，避免回写到 `toutiao_api.py`。
- 前端新增页面放入 `views/`，共享 UI 放入 `components/`，跨页状态放入 `stores/`，HTTP 调用只能通过 `api/`。
- 运行测试前不要删除本地 `.venv`、`uv.lock` 或课程 Demo。
- 不提交 `backend/toutiao.db`、虚拟环境、缓存、`node_modules`、本地 `.env` 或密钥。