📡 API接口文档

三长两短 - CloudKit备用服务器API

版本: v1.0.0 | 协议: REST | 格式: JSON

快速导航： 健康检查 分享码管理 状态请求 碰撞记录

📋 概述

基础信息

Base URL: http://um.dazitai.com/api

内容类型: application/json

字符编码: UTF-8

通用响应格式

成功响应:

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

错误响应:

{
  "error": true,
  "message": "错误描述",
  "details": { ... }
}

HTTP状态码

  • 200 请求成功
  • 400 请求参数错误
  • 404 资源不存在
  • 500 服务器内部错误
  • 503 服务不可用

🏥 健康检查

GET /api/health
检查服务器和数据库连接状态

响应示例 200 OK

{
  "status": "healthy",
  "timestamp": "2024-01-20T10:30:00+08:00",
  "version": "1.0.0",
  "services": {
    "database": {
      "status": "connected",
      "error": null
    },
    "redis": {
      "status": "connected",
      "error": null
    }
  },
  "endpoints": [
    "/api/health",
    "/api/share-code/check",
    "/api/share-code/register",
    "/api/share-code/release",
    "/api/status-request/create",
    "/api/status-request/respond",
    "/api/status-request/list",
    "/api/collision/record"
  ]
}

🔑 分享码管理

POST /api/share-code/check
检查分享码是否已被使用（碰撞检测）

请求参数

参数名 类型 必填 说明
shareCode string 必填 6-12位分享码
codeLength integer 必填 分享码长度（6/8/10/12）

请求示例

POST /api/share-code/check
Content-Type: application/json

{
  "shareCode": "ABC123",
  "codeLength": 6
}

响应示例 200 OK

{
  "success": true,
  "data": {
    "exists": false,
    "shareCode": "ABC123",
    "codeLength": 6
  }
}
POST /api/share-code/register
注册新的分享码

请求参数

参数名 类型 必填 说明
shareCode string 必填 分享码
umid string 必填 用户UMID（SHA256哈希）
codeLength integer 必填 分享码长度
validityMinutes integer 必填 有效期（分钟）

请求示例

POST /api/share-code/register
Content-Type: application/json

{
  "shareCode": "ABC123",
  "umid": "a1b2c3d4e5f6...",
  "codeLength": 6,
  "validityMinutes": 5
}

响应示例 200 OK

{
  "success": true,
  "message": "Share code registered successfully",
  "data": {
    "registered": true,
    "shareCode": "ABC123",
    "expiresAt": "2024-01-20 10:35:00"
  }
}
POST /api/share-code/release
释放（删除）分享码

请求参数

参数名 类型 必填 说明
shareCode string 必填 要释放的分享码

请求示例

POST /api/share-code/release
Content-Type: application/json

{
  "shareCode": "ABC123"
}

响应示例 200 OK

{
  "success": true,
  "message": "Share code released successfully",
  "data": {
    "released": true,
    "shareCode": "ABC123"
  }
}

📬 状态请求

POST /api/status-request/create
创建新的状态查询请求

请求参数

参数名 类型 必填 说明
requestId string 必填 请求ID（UUID）
requesterUmid string 必填 请求方UMID
targetUmid string 必填 目标用户UMID
encryptedPayload string 必填 加密的请求内容（Base64）

请求示例

POST /api/status-request/create
Content-Type: application/json

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "requesterUmid": "abc123...",
  "targetUmid": "xyz789...",
  "encryptedPayload": "base64_encrypted_data..."
}
POST /api/status-request/respond
响应状态请求（批准或拒绝）

请求参数

参数名 类型 必填 说明
requestId string 必填 请求ID
status string 必填 "approved" 或 "denied"
encryptedResponse string 可选 加密的响应内容
GET /api/status-request/list
获取用户的状态请求列表

查询参数

参数名 类型 必填 说明
umid string 必填 用户UMID
status string 可选 筛选状态（pending/approved/denied）

请求示例

GET /api/status-request/list?umid=abc123&status=pending

⚠️ 碰撞记录

POST /api/collision/record
记录分享码碰撞事件（用于统计和分析）

请求参数

参数名 类型 必填 说明
shareCode string 必填 发生碰撞的分享码
codeLength integer 必填 分享码长度
attempts integer 必填 尝试次数
totalUsers integer 可选 当时的总用户数

请求示例

POST /api/collision/record
Content-Type: application/json

{
  "shareCode": "ABC123",
  "codeLength": 6,
  "attempts": 3,
  "totalUsers": 1500
}
← 返回首页