# AI掘金头条新闻系统 (Toutiao News)

一个基于 FastAPI 和 SQLAlchemy 构建的现代化新闻系统，支持用户注册登录、新闻浏览、收藏和历史记录等功能。

## 1-1 项目概述

这是一个仿今日头条的新闻系统后端API服务，采用异步Python框架FastAPI开发，使用MySQL作为数据库存储，通过SQLAlchemy ORM进行数据访问。系统提供完整的用户管理、新闻浏览、收藏和历史记录功能。

## 1-2 技术栈

- **后端框架**: FastAPI
- **数据库**: MySQL
- **ORM**: SQLAlchemy (异步)
- **数据库驱动**: aiomysql
- **密码加密**: passlib + bcrypt
- **缓存系统**: Redis
- **异步支持**: Python asyncio

## 1-3 项目结构

```
toutiao_backend/                          # 项目根目录
├── crud/                              # 数据访问层（CRUD操作）
│   ├── favorite.py                  # 收藏相关数据库操作
│   ├── history.py                   # 历史记录相关数据库操作
│   ├── news.py                      # 新闻相关数据库操作
│   └── users.py                     # 用户相关数据库操作
│
├── models/                            # 数据模型定义
│   ├── favorite.py                  # 收藏数据模型
│   ├── history.py                   # 历史记录数据模型
│   ├── news.py                      # 新闻数据模型
│   └── users.py                     # 用户数据模型
│
├── routers/                           # API路由定义
│   ├── favorite.py                  # 收藏相关API路由
│   ├── history.py                   # 历史记录相关API路由
│   ├── news.py                      # 新闻相关API路由
│   └── users.py                     # 用户相关API路由
│
├── schemas/                         # 数据验证模型（Pydantic模型）
│   ├── favorite.py                  # 收藏数据验证模型
│   ├── history.py                   # 历史记录数据验证模型
│   ├── news.py                      # 新闻数据验证模型
│   └── users.py                     # 用户数据验证模型
│
├── utils/                             # 工具函数目录
│
├── config/                             # 配置相关
│   ├── db_conf.py                    # 数据库配置文件
│   ├── cache_conf.py                 # Redis缓存配置
│ 
├── main.py                           # 应用入口文件
└── test_main.http                    # HTTP接口测试文件
```

## 1-4 功能模块

### 1. 用户管理模块

- 用户注册
- 用户登录
- 用户信息获取
- 用户信息更新
- 用户密码修改

### 2. 新闻模块

- 新闻分类获取
- 新闻列表获取（支持分页和分类筛选）
- 新闻详情获取
- 浏览量统计

### 3. 收藏模块

- 添加收藏
- 取消收藏
- 收藏列表获取
- 清空所有收藏
- 检查收藏状态

### 4. 浏览历史模块

- 添加浏览记录
- 浏览历史列表获取
- 删除单条浏览记录
- 清空浏览历史

### 5. 缓存模块

- 新闻详情缓存
- 新闻列表缓存
- 分类数据缓存
- 用户历史记录缓存

## 1-5 数据库设计

### 主要数据表

1. **用户表 (user)**
    - 用户基本信息存储
    - 包含用户名、密码(加密)、昵称、头像等字段

2. **用户令牌表 (user_token)**
    - 用户认证令牌管理
    - 支持令牌过期机制

3. **新闻分类表 (news_category)**
    - 新闻分类信息

4. **新闻表 (news)**
    - 新闻内容存储
    - 包含标题、内容、作者、浏览量等字段

5. **收藏表 (favorite)**
    - 用户收藏记录
    - 关联用户和新闻

6. **浏览历史表 (history)**
    - 用户浏览历史记录
    - 关联用户和新闻

## 1-6 缓存设计

### 缓存策略

系统采用 Redis 作为缓存层，对高频访问的数据进行缓存，以提升系统性能和响应速度。

### 缓存数据类型

1. **新闻详情缓存**
    - 缓存键: `news:detail:{news_id}`
    - 过期时间: 1小时
    - 提升新闻详情页面访问速度

2. **新闻列表缓存**
    - 缓存键: `news:list:{category_id}:{page}:{size}`
    - 过期时间: 30分钟
    - 减少首页和分类页面的数据库查询压力

3. **分类数据缓存**
    - 缓存键: `news:categories`
    - 过期时间: 2小时
    - 加速导航栏分类数据加载

4. **用户历史记录缓存**
    - 缓存键: `history:list:{user_id}`
    - 过期时间: 1小时
    - 提高用户历史记录访问性能

### 缓存更新机制

- 数据更新时自动清除相关缓存
- 采用缓存失效而非主动更新策略
- 支持批量清除特定模式的缓存

### 缓存配置

在 cache_conf.py 中配置 Redis 连接信息：

```python
REDIS_HOST = "localhost"
REDIS_PORT = 6379
REDIS_DB = 0
```

## 1-7 API 接口说明

### 用户相关接口

| 接口                 | 方法 | 说明         |
| -------------------- | ---- | ------------ |
| `/api/user/register` | POST | 用户注册     |
| `/api/user/login`    | POST | 用户登录     |
| `/api/user/info`     | GET  | 获取用户信息 |
| `/api/user/update`   | PUT  | 更新用户信息 |
| `/api/user/password` | PUT  | 修改用户密码 |

### 新闻相关接口

| 接口                   | 方法 | 说明             |
| ---------------------- | ---- | ---------------- |
| `/api/news/categories` | GET  | 获取新闻分类列表 |
| `/api/news/list`       | GET  | 获取新闻列表     |
| `/api/news/detail`     | GET  | 获取新闻详情     |

### 收藏相关接口

| 接口                   | 方法   | 说明             |
| ---------------------- | ------ | ---------------- |
| `/api/favorite/check`  | GET    | 检查新闻收藏状态 |
| `/api/favorite/add`    | POST   | 添加收藏         |
| `/api/favorite/remove` | DELETE | 取消收藏         |
| `/api/favorite/list`   | GET    | 获取收藏列表     |
| `/api/favorite/clear`  | DELETE | 清空所有收藏     |

### 浏览历史相关接口

| 接口                               | 方法   | 说明             |
| ---------------------------------- | ------ | ---------------- |
| `/api/history/add`                 | POST   | 添加浏览记录     |
| `/api/history/list`                | GET    | 获取浏览历史列表 |
| `/api/history/delete/{history_id}` | DELETE | 删除单条浏览记录 |
| `/api/history/clear`               | DELETE | 清空浏览历史     |



## 1-8 认证机制

系统使用基于令牌(Token)的认证机制：

1. 用户登录成功后返回访问令牌
2. 需要认证的接口在请求头中添加 `Authorization: token值`
3. 令牌有效期为7天

## 1-9 错误处理

系统提供统一的错误处理机制：

- 用户认证失败返回 401 状态码
- 资源不存在返回 404 状态码
- 服务器内部错误返回 500 状态码

## 1-10 开发规范

- 使用异步数据库操作
- 所有密码均加密存储
- 接口返回统一的 JSON 格式
- 详细的接口文档和示例
- 缓存操作封装成独立函数便于调用

## 1-11 性能优化

- 使用 Redis 缓存热点数据
- 异步数据库操作提升并发性能
- 合理的数据库索引设计
- 连接池管理减少连接开销

