191 lines
6.9 KiB
Markdown
191 lines
6.9 KiB
Markdown
# 项目结构说明
|
||
|
||
本文档详细说明了项目的目录结构和各文件的作用。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
blogweb/
|
||
├── backend/ # 后端代码目录
|
||
│ ├── app/ # FastAPI 应用主目录
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main.py # FastAPI 应用入口
|
||
│ │ │
|
||
│ │ ├── api/ # API 路由模块
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ └── api_v1/ # API v1 版本
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── api.py # API 路由聚合
|
||
│ │ │ └── endpoints/ # API 端点
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── auth.py # 认证相关端点
|
||
│ │ │ ├── users.py # 用户相关端点
|
||
│ │ │ ├── todos.py # 待办事项端点
|
||
│ │ │ └── posts.py # 博客文章端点
|
||
│ │ │
|
||
│ │ ├── core/ # 核心配置模块
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── config.py # 应用配置
|
||
│ │ │ └── security.py # 安全相关（密码哈希、JWT）
|
||
│ │ │
|
||
│ │ ├── db/ # 数据库相关
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── base.py # 数据库基础配置
|
||
│ │ │ ├── session.py # 数据库会话管理
|
||
│ │ │ └── init_db.py # 数据库初始化脚本 ⭐
|
||
│ │ │
|
||
│ │ ├── models/ # 数据模型（SQLModel）
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── user.py # 用户模型
|
||
│ │ │ ├── todo.py # 待办事项模型
|
||
│ │ │ ├── post.py # 博客文章模型
|
||
│ │ │ ├── transaction.py # 记账记录模型
|
||
│ │ │ ├── media.py # 书影音收藏模型
|
||
│ │ │ ├── tag.py # 标签模型
|
||
│ │ │ ├── chat.py # 聊天消息模型
|
||
│ │ │ └── upload.py # 文件上传模型
|
||
│ │ │
|
||
│ │ ├── schemas/ # Pydantic 模式（API 数据验证）
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── user.py # 用户相关模式
|
||
│ │ │ ├── todo.py # 待办事项相关模式
|
||
│ │ │ └── post.py # 博客文章相关模式
|
||
│ │ │
|
||
│ │ └── initial_data/ # 初始数据模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── README.md
|
||
│ │
|
||
│ ├── database.py # （旧文件，可删除）
|
||
│ ├── models.py # （旧文件，可删除）
|
||
│ ├── init_db.py # （旧文件，可删除）
|
||
│ └── README.md # 后端说明文档
|
||
│
|
||
├── frontend/ # 前端代码目录
|
||
│ ├── src/
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ │ ├── Home.vue # 首页
|
||
│ │ │ ├── Login.vue # 登录页
|
||
│ │ │ ├── Register.vue # 注册页
|
||
│ │ │ ├── Todos.vue # 待办事项页
|
||
│ │ │ └── Posts.vue # 博客文章页
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ │ └── auth.js # 认证状态
|
||
│ │ ├── router/ # 路由配置
|
||
│ │ │ └── index.js
|
||
│ │ ├── App.vue # 根组件
|
||
│ │ └── main.js # 前端入口
|
||
│ ├── index.html # HTML 模板
|
||
│ ├── package.json # 前端依赖配置
|
||
│ └── vite.config.js # Vite 配置
|
||
│
|
||
├── main.py # 项目启动入口 ⭐
|
||
├── requirements.txt # Python 依赖
|
||
├── .env.example # 环境变量示例
|
||
├── .gitignore # Git 忽略规则
|
||
├── README.md # 项目说明文档
|
||
├── PROJECT_STRUCTURE.md # 本文件
|
||
└── 数据库设计说明.md # 数据库设计文档
|
||
```
|
||
|
||
## 关键文件说明
|
||
|
||
### ⭐ 重要文件
|
||
|
||
1. **`main.py`** - 项目启动入口
|
||
- 用于开发环境快速启动 FastAPI 应用
|
||
- 使用 uvicorn 运行 `app.main:app`
|
||
|
||
2. **`backend/app/main.py`** - FastAPI 应用主文件
|
||
- 创建 FastAPI 应用实例
|
||
- 配置 CORS 中间件
|
||
- 注册 API 路由
|
||
|
||
3. **`backend/app/db/init_db.py`** - 数据库初始化脚本 ⭐
|
||
- **位置已调整**：从 `backend/init_db.py` 移动到 `backend/app/db/init_db.py`
|
||
- 运行方式：
|
||
```bash
|
||
python -m app.db.init_db # 创建表
|
||
python -m app.db.init_db --reset # 重置数据库
|
||
```
|
||
|
||
## 模块说明
|
||
|
||
### 后端模块
|
||
|
||
#### `app/core/` - 核心配置
|
||
- `config.py`: 应用配置（数据库、安全、CORS 等）
|
||
- `security.py`: 密码哈希、JWT 令牌生成和验证
|
||
|
||
#### `app/db/` - 数据库
|
||
- `base.py`: 数据库基础配置，导入所有模型
|
||
- `session.py`: 数据库会话管理和依赖注入
|
||
- `init_db.py`: 数据库初始化脚本
|
||
|
||
#### `app/models/` - 数据模型
|
||
- 使用 SQLModel 定义数据库表结构
|
||
- 每个模型一个文件，便于维护
|
||
|
||
#### `app/schemas/` - Pydantic 模式
|
||
- 用于 API 请求和响应的数据验证
|
||
- 定义创建、更新、响应等不同场景的模式
|
||
|
||
#### `app/api/` - API 路由
|
||
- `api_v1/api.py`: 聚合所有 API 路由
|
||
- `api_v1/endpoints/`: 各个功能模块的端点
|
||
|
||
### 前端模块
|
||
|
||
#### `src/views/` - 页面组件
|
||
- Vue 3 单文件组件
|
||
- 每个功能对应一个页面
|
||
|
||
#### `src/stores/` - 状态管理
|
||
- 使用 Pinia 管理全局状态
|
||
- `auth.js`: 用户认证状态
|
||
|
||
#### `src/router/` - 路由
|
||
- Vue Router 配置
|
||
- 定义前端路由规则
|
||
|
||
## 开发流程
|
||
|
||
1. **初始化数据库**
|
||
```bash
|
||
python -m app.db.init_db
|
||
```
|
||
|
||
2. **启动后端**
|
||
```bash
|
||
python main.py
|
||
# 或
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
3. **启动前端**
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **数据库初始化脚本位置已调整**
|
||
- 旧位置：`backend/init_db.py`
|
||
- 新位置：`backend/app/db/init_db.py`
|
||
- 运行方式：`python -m app.db.init_db`
|
||
|
||
2. **旧文件清理**
|
||
- `backend/database.py`、`backend/models.py`、`backend/init_db.py` 可以删除
|
||
- 新代码已迁移到 `backend/app/` 目录下
|
||
|
||
3. **环境变量**
|
||
- 复制 `.env.example` 为 `.env`
|
||
- 修改其中的配置项（特别是 `SECRET_KEY`）
|
||
|
||
4. **前后端分离**
|
||
- 后端运行在 `http://localhost:8000`
|
||
- 前端运行在 `http://localhost:5173`
|
||
- 前端通过代理访问后端 API
|
||
|