hertz_django/docs/API接口文档/验证码模块接口文档.md

Hertz Studio Django 验证码模块接口文档

• 基础路径: /api/captcha/
• 统一响应: 使用 HertzResponse，结构如下（参考 hertz_studio_django_utils/responses/HertzResponse.py）

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {}
  }
  

• 路由挂载: 项目主路由中已通过 path('api/captcha/', include('hertz_studio_django_captcha.urls')) 挂载（hertz_server_django/urls.py:28）。
• 认证说明: 接口允许匿名访问（AllowAny），不需要登录（hertz_studio_django_captcha/api_views.py:18, hertz_studio_django_captcha/api_views.py:60）。
• 验证接口说明: 独立的验证码验证接口已删除，验证逻辑集成到具体业务接口（hertz_studio_django_captcha/api_views.py:54）。

一、生成验证码

生成新的验证码

• 方法: POST
• 路径: /api/captcha/generate/
• 认证: 不需要登录
• 实现: CaptchaGenerateAPIView.post（hertz_studio_django_captcha/api_views.py:38）
• 请求示例:

  curl -X POST "http://localhost:8000/api/captcha/generate/"
  

• 返回示例:

  {
    "success": true,
    "code": 200,
    "message": "验证码生成成功",
    "data": {
      "captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "image_data": "data:image/png;base64,iVBORw0KGgo...",
      "expires_in": 300
    }
  }
  

二、刷新验证码

刷新已有验证码，生成新图像

• 方法: POST
• 路径: /api/captcha/refresh/
• 认证: 不需要登录
• 请求体: application/json
• 字段: captcha_id 旧验证码ID
• 实现: CaptchaRefreshAPIView.post（hertz_studio_django_captcha/api_views.py:84）
• 请求示例:

  POST /api/captcha/refresh/
  Content-Type: application/json
  
  {"captcha_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"}
  

• 返回示例:

  {
    "success": true,
    "code": 200,
    "message": "验证码刷新成功",
    "data": {
      "captcha_id": "f2b3c4d5-e6f7-8901-bcde-0123456789ab",
      "image_data": "data:image/png;base64,iVBORw0KGgo...",
      "expires_in": 300
    }
  }
  

三、错误响应示例

• 参数不完整（刷新接口）:

  {"success": false, "code": 400, "message": "参数不完整"}
  

• 生成/刷新失败（异常信息）：

  {"success": false, "code": 500, "message": "验证码生成失败", "error": "<错误信息>"}