cb491e8b87
- Backend: Django 4.2 + DRF + JWT + GraphQL - Frontend: React 18 + MobX + styled-components - Deployment: Docker + Docker Compose + Nginx - Database: PostgreSQL support - Documentation: README, INIT, PROJECT_DOCS, TESTING
262 lines
5.7 KiB
Markdown
262 lines
5.7 KiB
Markdown
# 项目架构文档
|
||
|
||
## 技术栈
|
||
|
||
### 后端 (Django)
|
||
- **框架**: Django 4.2
|
||
- **API 框架**: Django REST Framework
|
||
- **认证**: JWT (djangorestframework-simplejwt)
|
||
- **GraphQL**: graphene-django
|
||
- **数据库**: PostgreSQL
|
||
- **静态文件**: Whitenoise
|
||
- **生产服务器**: Gunicorn
|
||
|
||
### 前端 (React)
|
||
- **框架**: React 18
|
||
- **构建工具**: Create React App
|
||
- **状态管理**: MobX + mobx-react-lite
|
||
- **样式**: styled-components
|
||
- **路由**: React Router 6
|
||
- **HTTP 客户端**: axios
|
||
|
||
### 部署
|
||
- **容器化**: Docker + Docker Compose
|
||
- **反向代理**: Nginx
|
||
- **进程管理**: Gunicorn
|
||
|
||
## 项目结构
|
||
|
||
### 后端结构
|
||
```
|
||
backend/
|
||
├── config/
|
||
│ ├── settings/
|
||
│ │ ├── base.py # 基础配置
|
||
│ │ ├── dev.py # 开发环境
|
||
│ │ └── prod.py # 生产环境
|
||
│ ├── urls.py # 主路由
|
||
│ ├── wsgi.py # WSGI 配置
|
||
│ └── asgi.py # ASGI 配置
|
||
├── apps/
|
||
│ ├── users/ # 用户管理
|
||
│ │ ├── models.py # User 模型
|
||
│ │ ├── serializers.py
|
||
│ │ ├── views.py # ViewSets
|
||
│ │ └── urls.py
|
||
│ ├── core/ # 核心业务
|
||
│ └── api/ # API 配置
|
||
│ ├── serializers.py
|
||
│ ├── views.py
|
||
│ ├── urls.py
|
||
│ ├── schema.py # GraphQL schema
|
||
│ └── graphql_urls.py
|
||
├── static/ # 静态文件
|
||
├── media/ # 媒体文件
|
||
├── requirements.txt
|
||
├── manage.py
|
||
└── start.sh # 快速启动脚本
|
||
```
|
||
|
||
### 前端结构
|
||
```
|
||
frontend/
|
||
├── src/
|
||
│ ├── components/ # React 组件
|
||
│ ├── stores/ # MobX stores
|
||
│ │ ├── AuthStore.js
|
||
│ │ └── UserStore.js
|
||
│ ├── services/ # API 服务
|
||
│ │ └── api.js # axios 配置
|
||
│ ├── styles/ # 全局样式
|
||
│ │ └── global.js
|
||
│ ├── App.js # 主应用
|
||
│ └── index.js # 入口文件
|
||
├── public/ # 公共资源
|
||
├── package.json
|
||
├── .env.example
|
||
├── nginx.conf # Nginx 配置
|
||
├── Dockerfile
|
||
└── start.sh # 快速启动脚本
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
### 1. 用户认证
|
||
|
||
**JWT 认证流程：**
|
||
1. 用户发送 email + password 到 `/api/auth/login/`
|
||
2. 后端验证并返回 access_token 和 refresh_token
|
||
3. 前端保存 tokens 到 localStorage
|
||
4. 后续请求在 Header 中携带 Bearer token
|
||
5. Token 过期时自动使用 refresh_token 刷新
|
||
|
||
**自定义用户模型：**
|
||
```python
|
||
# apps/users/models.py
|
||
class User(AbstractUser):
|
||
email = models.EmailField(unique=True)
|
||
avatar = models.ImageField(upload_to='avatars/')
|
||
USERNAME_FIELD = 'email'
|
||
```
|
||
|
||
### 2. REST API
|
||
|
||
**端点：**
|
||
- `POST /api/auth/login/` - 登录获取 token
|
||
- `POST /api/auth/token/refresh/` - 刷新 token
|
||
- `GET /api/users/` - 获取用户列表
|
||
- `GET /api/users/me/` - 获取当前用户
|
||
- `GET /api/users/:id/` - 获取特定用户
|
||
|
||
### 3. GraphQL
|
||
|
||
**Schema：**
|
||
```graphql
|
||
type User {
|
||
id: ID!
|
||
email: String!
|
||
username: String!
|
||
}
|
||
|
||
type Query {
|
||
allUsers: [User!]!
|
||
me: User
|
||
}
|
||
```
|
||
|
||
访问 `/graphql/?graphiql` 查看调试界面。
|
||
|
||
### 4. 状态管理 (MobX)
|
||
|
||
**AuthStore：**
|
||
- 管理认证状态
|
||
- 处理登录/登出
|
||
- 保存和读取 tokens
|
||
|
||
**UserStore：**
|
||
- 获取当前用户信息
|
||
- 管理用户数据状态
|
||
|
||
## 开发流程
|
||
|
||
### 1. 添加新的 API 端点
|
||
|
||
```python
|
||
# apps/yourapp/views.py
|
||
class YourViewSet(viewsets.ModelViewSet):
|
||
queryset = YourModel.objects.all()
|
||
serializer_class = YourSerializer
|
||
|
||
# apps/yourapp/urls.py
|
||
router = DefaultRouter()
|
||
router.register(r'endpoint', YourViewSet)
|
||
```
|
||
|
||
### 2. 添加新的 MobX Store
|
||
|
||
```javascript
|
||
// src/stores/YourStore.js
|
||
import { makeAutoObservable } from 'mobx';
|
||
|
||
class YourStore {
|
||
data = null;
|
||
loading = false;
|
||
|
||
constructor() {
|
||
makeAutoObservable(this);
|
||
}
|
||
|
||
async fetchData() {
|
||
this.loading = true;
|
||
// API 调用
|
||
this.loading = false;
|
||
}
|
||
}
|
||
|
||
export default YourStore;
|
||
```
|
||
|
||
### 3. 添加新的 React 组件
|
||
|
||
```javascript
|
||
// src/components/YourComponent.js
|
||
import React from 'react';
|
||
import styled from 'styled-components';
|
||
|
||
const Container = styled.div`
|
||
padding: 20px;
|
||
`;
|
||
|
||
function YourComponent() {
|
||
return <Container>Your content</Container>;
|
||
}
|
||
|
||
export default YourComponent;
|
||
```
|
||
|
||
## 部署配置
|
||
|
||
### Docker Compose 服务
|
||
|
||
**backend：**
|
||
- 基于 Python 3.11
|
||
- 运行 Gunicorn
|
||
- 暴露 8000 端口
|
||
- 挂载 static 和 media 卷
|
||
|
||
**frontend：**
|
||
- 基于 Node 18 构建
|
||
- 使用 nginx 作为服务器
|
||
- 暴露 80 端口
|
||
- 代理 API 请求到 backend
|
||
|
||
**db：**
|
||
- PostgreSQL 15
|
||
- 持久化数据卷
|
||
|
||
### Nginx 配置
|
||
|
||
- `/` → React 应用
|
||
- `/api/*` → Django 后端
|
||
- `/graphql/*` → Django GraphQL
|
||
- `/media/*` → Django media
|
||
- `/static/*` → Django static
|
||
|
||
## 安全注意事项
|
||
|
||
1. **生产环境必须：**
|
||
- 设置 `DJANGO_SECRET_KEY` 为强随机值
|
||
- `DEBUG=False`
|
||
- 配置 `ALLOWED_HOSTS`
|
||
- 启用 HTTPS
|
||
- 设置 `CORS_ALLOWED_ORIGINS`
|
||
|
||
2. **数据库：**
|
||
- 使用强密码
|
||
- 不暴露到公网
|
||
- 定期备份
|
||
|
||
3. **JWT：**
|
||
- Token 过期时间合理配置
|
||
- 刷新 token 轮换
|
||
- 生产环境使用 HTTPS
|
||
|
||
## 下一步开发建议
|
||
|
||
1. **后端：**
|
||
- 添加更多业务 apps
|
||
- 实现权限控制
|
||
- 添加 API 文档 (Swagger)
|
||
- 实现文件上传功能
|
||
|
||
2. **前端：**
|
||
- 创建登录/注册页面
|
||
- 添加路由保护
|
||
- 实现加载状态处理
|
||
- 添加错误处理
|
||
|
||
3. **部署：**
|
||
- 配置 HTTPS (Let's Encrypt)
|
||
- 设置 CI/CD
|
||
- 配置日志收集
|
||
- 实现自动备份 |