381 lines
8.6 KiB
Markdown
381 lines
8.6 KiB
Markdown
# API 视图文档
|
||
|
||
## 📋 **目录**
|
||
|
||
### 1. [GetIPDataView](#getipdataview)
|
||
### 2. [BaiduFanyiView](#baidufanyiview)
|
||
### 3. [用户视图](#user-views)
|
||
|
||
---
|
||
|
||
## <a name="getipdataview"></a> 🌐 GetIPDataView
|
||
|
||
### **文件位置**
|
||
`api/views/GetIPDataView.py`
|
||
|
||
### **概述**
|
||
从各种 HTTP 头部和服务器变量中获取客户端 IP 地址信息。
|
||
|
||
### **类详情**
|
||
|
||
```python
|
||
@permission_classes([AllowAny])
|
||
class GetIPDataView(APIView):
|
||
def get(self, request):
|
||
# 实现...
|
||
```
|
||
|
||
### **方法: GET**
|
||
|
||
#### **参数**
|
||
- 无需参数
|
||
|
||
#### **响应格式**
|
||
```json
|
||
{
|
||
"ip_info": {
|
||
"remote_addr": "字符串",
|
||
"http_x_forwarded_for": "字符串",
|
||
"http_x_real_ip": "字符串",
|
||
"http_client_ip": "字符串",
|
||
"http_x_forwarded": "字符串",
|
||
"http_x_cluster_client_ip": "字符串",
|
||
"http_forwarded_for": "字符串",
|
||
"http_forwarded": "字符串"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### **检查的HTTP头部**
|
||
该视图从以下 HTTP 头部提取 IP 信息：
|
||
|
||
| 头部名称 | 映射变量 | 描述 |
|
||
|---------|----------|------|
|
||
| `REMOTE_ADDR` | `request.META.get('REMOTE_ADDR')` | 直接连接 IP（最可靠） |
|
||
| `X-Forwarded-For` | `request.META.get('HTTP_X_FORWARDED_FOR')` | 代理/负载均衡器转发 IP |
|
||
| `X-Real-IP` | `request.META.get('HTTP_X_REAL_IP')` | 反向代理看到的真实客户端 IP |
|
||
| `Client-Ip` | `request.META.get('HTTP_CLIENT_IP')` | 客户端 IP 头部 |
|
||
| `X-Forwarded` | `request.META.get('HTTP_X_FORWARDED')` | 转发头部 |
|
||
| `X-Cluster-Client-Ip` | `request.META.get('HTTP_X_CLUSTER_CLIENT_IP')` | 集群客户端 IP |
|
||
| `Forwarded-For` | `request.META.get('HTTP_FORWARDED_FOR')` | 标准转发 for 头部 |
|
||
| `Forwarded` | `request.META.get('HTTP_FORWARDED')` | 标准转发头部 |
|
||
|
||
### **使用示例**
|
||
|
||
```bash
|
||
curl -X GET http://your-api.com/api/get-ip-data/
|
||
```
|
||
|
||
**响应:**
|
||
```json
|
||
{
|
||
"ip_info": {
|
||
"remote_addr": "192.168.1.100",
|
||
"http_x_forwarded_for": "203.0.113.50, 198.51.100.25",
|
||
"http_x_real_ip": "203.0.113.50",
|
||
"http_client_ip": "",
|
||
"http_x_forwarded": "",
|
||
"http_x_cluster_client_ip": "",
|
||
"http_forwarded_for": "",
|
||
"http_forwarded": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
### **错误处理**
|
||
- 返回 HTTP 200，缺失头部返回空字符串
|
||
- 无需认证 (`@permission_classes([AllowAny])`)
|
||
|
||
---
|
||
|
||
## <a name="baidufanyiview"></a> 🌍 BaiduFanyiView
|
||
|
||
### **文件位置**
|
||
`api/views/BaiduFanyiView.py`
|
||
|
||
### **概述**
|
||
使用百度翻译 API 提供翻译和语言识别服务。所有视图都已转换为异步操作以获得更好的 Daphne ASGI 服务器性能。
|
||
|
||
### **类详情**
|
||
|
||
```python
|
||
# 所有视图的异步方法
|
||
async def post(self, request): # 文本和语言识别
|
||
async def post(self, request): # 图片翻译
|
||
async def post(self, request): # 语音识别
|
||
```
|
||
|
||
### **1. BaiduFanyiView (文本翻译)**
|
||
|
||
#### **端点**: `POST /api/translate/`
|
||
|
||
##### **参数**
|
||
```json
|
||
{
|
||
"q": "要翻译的文本", // 必需：文本内容（最多 3000 字符）
|
||
"from_lang": "en", // 必需：源语言代码
|
||
"to_lang": "zh" // 必需：目标语言代码
|
||
}
|
||
```
|
||
|
||
##### **支持的语言**
|
||
从 `info.baidu_lang_info` 加载语言：
|
||
- 查看 `languages` 获取支持的语言对
|
||
- 使用 `"auto"` 自动检测源语言
|
||
|
||
##### **响应示例**
|
||
```json
|
||
{
|
||
"message": "Success",
|
||
"code": "10000",
|
||
"data": {
|
||
"trans_result": [
|
||
{
|
||
"src": "Hello world",
|
||
"dst": "你好世界"
|
||
}
|
||
],
|
||
"from": "en",
|
||
"to": "zh"
|
||
}
|
||
}
|
||
```
|
||
|
||
### **2. RecognizeLangTypeViews (语言识别)**
|
||
|
||
#### **端点**: `POST /api/recognize-language/`
|
||
|
||
##### **参数**
|
||
```json
|
||
{
|
||
"q": "要识别的文本" // 必需：要识别语言的文本
|
||
}
|
||
```
|
||
|
||
##### **响应示例**
|
||
```json
|
||
{
|
||
"message": "Success",
|
||
"code": "10000",
|
||
"data": {
|
||
"lang": "en"
|
||
}
|
||
}
|
||
```
|
||
|
||
### **3. PictureRecognizeViews (图片翻译)**
|
||
|
||
#### **端点**: `POST /api/picture-translate/`
|
||
|
||
##### **参数**
|
||
- 通过 multipart/form-data 上传文件
|
||
- 查询参数：
|
||
- `from_lang`: 源语言
|
||
- `to_lang`: 目标语言
|
||
- `picture`: 图片格式类型
|
||
|
||
##### **请求格式**
|
||
```bash
|
||
curl -X POST http://your-api.com/api/picture-translate/ \
|
||
-H "Content-Type: multipart/form-data" \
|
||
-F "file=@image.jpg" \
|
||
-G --data-urlencode "from_lang=en" \
|
||
--data-urlencode "to_lang=zh" \
|
||
--data-urlencode "picture=jpg"
|
||
```
|
||
|
||
### **4. SpeechRecognitionView (语音识别)**
|
||
|
||
#### **端点**: `POST /api/speech-recognition/`
|
||
|
||
##### **参数**
|
||
- 通过 multipart/form-data 上传语音文件
|
||
- 查询参数：
|
||
- `speech_type`: 音频格式（如 "pcm"）
|
||
- `from_lang`: 源语言
|
||
- `to_lang`: 目标语言
|
||
|
||
##### **错误代码**
|
||
| 代码 | 描述 |
|
||
|------|------|
|
||
| 10000 | 成功 |
|
||
| 20001 | 不支持的语言 |
|
||
| 20002 | 无效的音频格式 |
|
||
| 20003 | 服务暂时不可用 |
|
||
|
||
### **异步实现优势**
|
||
- ✅ 非阻塞 I/O 操作
|
||
- ✅ 更好的并发处理
|
||
- ✅ 改进的响应时间
|
||
- ✅ 完整的 Daphne ASGI 兼容性
|
||
|
||
---
|
||
|
||
## <a name="user-views"></a> 👤 用户视图
|
||
|
||
### **文件位置**
|
||
`user/views/user.py`
|
||
|
||
### **概述**
|
||
处理用户认证和邮件验证。现在完全转换为异步操作并使用标准化响应代码。
|
||
|
||
### **类详情**
|
||
|
||
```python
|
||
@permission_classes([AllowAny])
|
||
class SendUserEmailAPIView(APIView):
|
||
async def post(self, request): # 发送邮件
|
||
|
||
@permission_classes([AllowAny])
|
||
class UserLoginOrRegisterAPIView(APIView):
|
||
async def post(self, request): # 登录/注册
|
||
```
|
||
|
||
### **1. SendUserEmailAPIView**
|
||
|
||
#### **端点**: `POST /api/send-email/`
|
||
|
||
##### **参数**
|
||
```json
|
||
{
|
||
"to_email": "user@example.com" // 必需：收件人邮箱地址
|
||
}
|
||
```
|
||
|
||
##### **响应示例**
|
||
|
||
**注册邮件:**
|
||
```json
|
||
{
|
||
"message": "账号未注册，已发送注册邮件",
|
||
"code": "10001",
|
||
"data": {
|
||
"email_sent": true,
|
||
"type": "register"
|
||
}
|
||
}
|
||
```
|
||
|
||
**登录邮件:**
|
||
```json
|
||
{
|
||
"message": "邮件发送成功",
|
||
"code": "10002",
|
||
"data": {
|
||
"email_sent": true,
|
||
"type": "login"
|
||
}
|
||
}
|
||
```
|
||
|
||
### **2. UserLoginOrRegisterAPIView**
|
||
|
||
#### **端点**: `POST /api/login-register/`
|
||
|
||
##### **参数**
|
||
```json
|
||
{
|
||
"email": "user@example.com", // 必需：用户邮箱
|
||
"code": "12345678" // 必需：验证码
|
||
}
|
||
```
|
||
|
||
##### **响应示例**
|
||
|
||
**注册成功:**
|
||
```json
|
||
{
|
||
"message": "注册成功",
|
||
"code": "10003",
|
||
"data": {
|
||
"user": { /* 用户数据 */ },
|
||
"refresh": "jwt_refresh_token",
|
||
"access": "jwt_access_token",
|
||
"token_type": "bearer",
|
||
"expires_in": 604800
|
||
}
|
||
}
|
||
```
|
||
|
||
**登录成功:**
|
||
```json
|
||
{
|
||
"message": "登录成功",
|
||
"code": "10004",
|
||
"data": {
|
||
"user": { /* 用户数据 */ },
|
||
"refresh": "jwt_refresh_token",
|
||
"access": "jwt_access_token",
|
||
"token_type": "bearer",
|
||
"expires_in": 604800
|
||
}
|
||
}
|
||
```
|
||
|
||
##### **错误响应**
|
||
```json
|
||
{
|
||
"message": "邮箱地址不能为空",
|
||
"code": "20002",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### **标准化响应格式**
|
||
所有响应都遵循统一结构:
|
||
```json
|
||
{
|
||
"message": "可读消息",
|
||
"code": "10000", // 5位数字零填充字符串
|
||
"data": { // 可选，错误时为null
|
||
// 响应载荷
|
||
}
|
||
}
|
||
```
|
||
|
||
### **异步实现特性**
|
||
- ✅ 使用 `sync_to_async` 包装数据库操作
|
||
- ✅ 邮件发送作为异步操作
|
||
- ✅ 完整的 try-catch 块错误处理
|
||
- ✅ 代码/消息的类型安全枚举使用
|
||
|
||
---
|
||
|
||
## 📊 **统计摘要**
|
||
|
||
| 视图类 | 方法 | 异步? | 错误代码 | 状态码 |
|
||
|--------|------|-------|----------|--------|
|
||
| GetIPDataView | GET | ❌ 同步 | N/A | 200 |
|
||
| BaiduFanyiView | POST | ✅ 异步 | 多个 | 200, 400, 503 |
|
||
| RecognizeLangTypeViews | POST | ✅ 异步 | 多个 | 200, 400, 503 |
|
||
| PictureRecognizeViews | POST | ✅ 异步 | 多个 | 200, 400, 503 |
|
||
| SpeechRecognitionView | POST | ✅ 异步 | 多个 | 200, 503 |
|
||
| SendUserEmailAPIView | POST | ✅ 异步 | 3+ | 200, 201, 400, 500 |
|
||
| UserLoginOrRegisterAPIView | POST | ✅ 异步 | 6+ | 200, 400, 500 |
|
||
|
||
---
|
||
|
||
## 🚀 **快速开始指南**
|
||
|
||
### **测试端点:**
|
||
|
||
```bash
|
||
# 获取IP数据
|
||
curl -X GET http://localhost:8000/api/get-ip-data/
|
||
|
||
# 发送邮件
|
||
curl -X POST http://localhost:8000/api/send-email/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"to_email":"test@example.com"}'
|
||
|
||
# 文本翻译
|
||
curl -X POST http://localhost:8000/api/translate/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"q":"Hello","from_lang":"en","to_lang":"zh"}'
|
||
```
|
||
|
||
### **使用Daphne运行:**
|
||
```bash
|
||
pip install aiohttp
|
||
daphne chunyu_project.asgi:application --port 8000
|
||
``` |