chunyu_project/DOCUMENTATION_SimplifiedChinese.md

API 视图文档

📋 目录

1. GetIPDataView

2. BaiduFanyiView

3. 用户视图

---

🌐 GetIPDataView

文件位置

api/views/GetIPDataView.py

概述

从各种 HTTP 头部和服务器变量中获取客户端 IP 地址信息。

类详情

@permission_classes([AllowAny])
class GetIPDataView(APIView):
    def get(self, request):
        # 实现...

方法: GET

参数

• 无需参数

响应格式

{
    "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')	标准转发头部

使用示例

curl -X GET http://your-api.com/api/get-ip-data/

响应:

{
    "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 服务器性能。

类详情

# 所有视图的异步方法
async def post(self, request):  # 文本和语言识别
async def post(self, request):  # 图片翻译
async def post(self, request):  # 语音识别

1. BaiduFanyiView (文本翻译)

端点: POST /api/translate/

参数

{
    "q": "要翻译的文本",           // 必需：文本内容（最多 3000 字符）
    "from_lang": "en",                  // 必需：源语言代码
    "to_lang": "zh"                     // 必需：目标语言代码
}

支持的语言

从 info.baidu_lang_info 加载语言：

• 查看 languages 获取支持的语言对
• 使用 "auto" 自动检测源语言

响应示例

{
    "message": "Success",
    "code": "10000",
    "data": {
        "trans_result": [
            {
                "src": "Hello world",
                "dst": "你好世界"
            }
        ],
        "from": "en",
        "to": "zh"
    }
}

2. RecognizeLangTypeViews (语言识别)

端点: POST /api/recognize-language/

参数

{
    "q": "要识别的文本"            // 必需：要识别语言的文本
}

响应示例

{
    "message": "Success",
    "code": "10000",
    "data": {
        "lang": "en"
    }
}

3. PictureRecognizeViews (图片翻译)

端点: POST /api/picture-translate/

参数

• 通过 multipart/form-data 上传文件
• 查询参数：
  • from_lang: 源语言
  • to_lang: 目标语言
  • picture: 图片格式类型

请求格式

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

概述

处理用户认证和邮件验证。现在完全转换为异步操作并使用标准化响应代码。

类详情

@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/

参数

{
    "to_email": "user@example.com"      // 必需：收件人邮箱地址
}

响应示例

注册邮件:

{
    "message": "账号未注册，已发送注册邮件",
    "code": "10001",
    "data": {
        "email_sent": true,
        "type": "register"
    }
}

登录邮件:

{
    "message": "邮件发送成功",
    "code": "10002",
    "data": {
        "email_sent": true,
        "type": "login"
    }
}

2. UserLoginOrRegisterAPIView

端点: POST /api/login-register/

参数

{
    "email": "user@example.com",        // 必需：用户邮箱
    "code": "12345678"                  // 必需：验证码
}

响应示例

注册成功:

{
    "message": "注册成功",
    "code": "10003",
    "data": {
        "user": { /* 用户数据 */ },
        "refresh": "jwt_refresh_token",
        "access": "jwt_access_token",
        "token_type": "bearer",
        "expires_in": 604800
    }
}

登录成功:

{
    "message": "登录成功",
    "code": "10004",
    "data": {
        "user": { /* 用户数据 */ },
        "refresh": "jwt_refresh_token",
        "access": "jwt_access_token",
        "token_type": "bearer",
        "expires_in": 604800
    }
}

错误响应

{
    "message": "邮箱地址不能为空",
    "code": "20002",
    "data": {}
}

标准化响应格式

所有响应都遵循统一结构:

{
    "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

---

🚀 快速开始指南

测试端点:

# 获取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运行:

pip install aiohttp
daphne chunyu_project.asgi:application --port 8000