# API 视图文档
## 📋 **目录**
### 1. [GetIPDataView](#getipdataview)
### 2. [BaiduFanyiView](#baidufanyiview)
### 3. [用户视图](#user-views)
---
## 🌐 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])`)
---
## 🌍 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 兼容性
---
## 👤 用户视图
### **文件位置**
`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
```