Migrate project from typing_practiceweb

2026-05-14 16:04:14 +08:00
parent dbc5425706
commit 0e87d5546d
225 changed files with 92811 additions and 0 deletions
--- a/api-documentation.md
+++ b/api-documentation.md
@@ -0,0 +1,501 @@
+# D1KT平台API接口调用文档
+
+## 目录
+
+- [简介](#简介)
+- [基础信息](#基础信息)
+- [登录API](#登录api)
+- [注册API](#注册api)
+- [代码调用示例](#代码调用示例)
+- [错误处理](#错误处理)
+- [安全建议](#安全建议)
+
+## 简介
+
+本文档提供了D1KT平台用户认证系统API的详细调用说明，帮助开发者在第三方应用中集成D1KT的用户登录和注册功能。
+
+## 基础信息
+
+- **基础URL**: `https://d1kt.cn/api/api`
+- **API版本**: v1
+- **内容类型**: application/json
+- **字符编码**: UTF-8
+- **认证方式**: JWT (JSON Web Token)
+
+## 登录API
+
+### 接口描述
+
+此接口用于验证用户身份并获取访问令牌。
+
+### 请求详情
+
+- **URL**: `/auth/login`
+- **方法**: POST
+- **内容类型**: application/json
+
+### 请求参数
+
+| 参数名 | 类型 | 必填 | 描述 | 验证规则 |
+|--------|------|------|------|---------|
+| username | String | 是 | 用户名 | 长度2-20个字符 |
+| password | String | 是 | 密码 | 长度至少6个字符 |
+
+### 请求示例
+
+```json
+{
+  "username": "testuser",
+  "password": "password123"
+}
+```
+
+### 响应参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| token | String | JWT令牌，用于后续请求的认证 |
+| user | Object | 用户信息对象 |
+| user._id | String | 用户唯一标识符 |
+| user.username | String | 用户名 |
+| user.fullname | String | 用户姓名 |
+| user.email | String | 用户邮箱 |
+| user.isAdmin | Boolean | 是否为管理员 |
+
+### 成功响应示例
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "_id": "60d21b4667d0d8992e610c85",
+    "username": "testuser",
+    "fullname": "测试用户",
+    "email": "test@example.com",
+    "isAdmin": false
+  }
+}
+```
+
+### 可能的错误
+
+| HTTP状态码 | 错误消息 | 描述 |
+|------------|----------|------|
+| 400 | 请填写所有字段 | 用户名或密码为空 |
+| 400 | 用户名长度应在2-20个字符之间 | 用户名长度不符合要求 |
+| 400 | 密码长度至少6个字符 | 密码长度不符合要求 |
+| 401 | 用户不存在 | 提供的用户名不存在 |
+| 401 | 密码错误 | 提供的密码与用户名不匹配 |
+| 500 | 服务器内部错误 | 服务器处理请求时出错 |
+
+## 注册API
+
+### 接口描述
+
+此接口用于创建新用户账户并获取访问令牌。
+
+### 请求详情
+
+- **URL**: `/auth/register`
+- **方法**: POST
+- **内容类型**: application/json
+
+### 请求参数
+
+| 参数名 | 类型 | 必填 | 描述 | 验证规则 |
+|--------|------|------|------|---------|
+| username | String | 是 | 用户名 | 长度2-20个字符 |
+| email | String | 是 | 电子邮箱 | 有效的邮箱格式 |
+| fullname | String | 是 | 姓名 | 长度2-50个字符 |
+| password | String | 是 | 密码 | 长度至少6个字符 |
+
+### 请求示例
+
+```json
+{
+  "username": "newuser",
+  "email": "newuser@example.com",
+  "fullname": "新用户",
+  "password": "password123"
+}
+```
+
+### 响应参数
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| token | String | JWT令牌，用于后续请求的认证 |
+| user | Object | 用户信息对象 |
+| user._id | String | 用户唯一标识符 |
+| user.username | String | 用户名 |
+| user.fullname | String | 用户姓名 |
+| user.isAdmin | Boolean | 是否为管理员 |
+
+### 成功响应示例
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "user": {
+    "_id": "60d21b4667d0d8992e610c85",
+    "username": "newuser",
+    "fullname": "新用户",
+    "isAdmin": false
+  }
+}
+```
+
+### 可能的错误
+
+| HTTP状态码 | 错误消息 | 描述 |
+|------------|----------|------|
+| 400 | 请填写必填字段 | 有必填字段为空 |
+| 400 | 用户名长度应在2-20个字符之间 | 用户名长度不符合要求 |
+| 400 | 密码长度至少6个字符 | 密码长度不符合要求 |
+| 400 | 请输入有效的邮箱地址 | 邮箱格式不正确 |
+| 400 | 姓名长度应在2-50个字符之间 | 姓名长度不符合要求 |
+| 409 | 用户名已存在 | 提供的用户名已被注册 |
+| 409 | 邮箱已被使用 | 提供的邮箱已被注册 |
+| 500 | 服务器内部错误 | 服务器处理请求时出错 |
+
+## 代码调用示例
+
+### JavaScript (Fetch API)
+
+```javascript
+// 登录API调用示例
+async function login(username, password) {
+  try {
+    const response = await fetch('https://d1kt.cn/api/api/auth/login', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ username, password })
+    });
+    
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData.message || '登录失败');
+    }
+    
+    const data = await response.json();
+    // 保存token和用户信息
+    localStorage.setItem('token', data.token);
+    localStorage.setItem('user', JSON.stringify(data.user));
+    
+    return data;
+  } catch (error) {
+    console.error('登录失败:', error);
+    throw error;
+  }
+}
+
+// 注册API调用示例
+async function register(username, email, fullname, password) {
+  try {
+    const response = await fetch('https://d1kt.cn/api/api/auth/register', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ username, email, fullname, password })
+    });
+    
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData.message || '注册失败');
+    }
+    
+    const data = await response.json();
+    // 保存token和用户信息
+    localStorage.setItem('token', data.token);
+    localStorage.setItem('user', JSON.stringify(data.user));
+    
+    return data;
+  } catch (error) {
+    console.error('注册失败:', error);
+    throw error;
+  }
+}
+
+// 带身份验证的API调用示例
+async function callAuthenticatedAPI(endpoint) {
+  const token = localStorage.getItem('token');
+  if (!token) {
+    throw new Error('未登录，请先登录');
+  }
+  
+  try {
+    const response = await fetch(`https://d1kt.cn/api/api${endpoint}`, {
+      method: 'GET', // 或其他方法
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+    
+    if (!response.ok) {
+      // 如果token过期或无效
+      if (response.status === 401) {
+        localStorage.removeItem('token');
+        localStorage.removeItem('user');
+        throw new Error('会话已过期，请重新登录');
+      }
+      
+      const errorData = await response.json();
+      throw new Error(errorData.message || '请求失败');
+    }
+    
+    return await response.json();
+  } catch (error) {
+    console.error('API调用失败:', error);
+    throw error;
+  }
+}
+```
+
+### Python (Requests)
+
+```python
+import requests
+import json
+
+# API基础URL
+BASE_URL = "https://d1kt.cn/api/api"
+
+# 登录API调用示例
+def login(username, password):
+    url = f"{BASE_URL}/auth/login"
+    headers = {"Content-Type": "application/json"}
+    payload = {"username": username, "password": password}
+    
+    try:
+        response = requests.post(url, json=payload, headers=headers)
+        response.raise_for_status()  # 如果请求失败，抛出异常
+        
+        data = response.json()
+        # 在实际应用中，您可能需要保存token和用户信息
+        return data
+    except requests.exceptions.HTTPError as e:
+        error_msg = "未知错误"
+        try:
+            error_data = response.json()
+            error_msg = error_data.get("message", "登录失败")
+        except:
+            pass
+        print(f"登录失败: {error_msg}")
+        raise Exception(error_msg)
+    except Exception as e:
+        print(f"请求异常: {str(e)}")
+        raise
+
+# 注册API调用示例
+def register(username, email, fullname, password):
+    url = f"{BASE_URL}/auth/register"
+    headers = {"Content-Type": "application/json"}
+    payload = {
+        "username": username,
+        "email": email,
+        "fullname": fullname,
+        "password": password
+    }
+    
+    try:
+        response = requests.post(url, json=payload, headers=headers)
+        response.raise_for_status()  # 如果请求失败，抛出异常
+        
+        data = response.json()
+        # 在实际应用中，您可能需要保存token和用户信息
+        return data
+    except requests.exceptions.HTTPError as e:
+        error_msg = "未知错误"
+        try:
+            error_data = response.json()
+            error_msg = error_data.get("message", "注册失败")
+        except:
+            pass
+        print(f"注册失败: {error_msg}")
+        raise Exception(error_msg)
+    except Exception as e:
+        print(f"请求异常: {str(e)}")
+        raise
+
+# 带身份验证的API调用示例
+def call_authenticated_api(endpoint, token):
+    url = f"{BASE_URL}{endpoint}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+    
+    try:
+        response = requests.get(url, headers=headers)  # 或其他方法
+        response.raise_for_status()
+        
+        return response.json()
+    except requests.exceptions.HTTPError as e:
+        if response.status_code == 401:
+            raise Exception("会话已过期，请重新登录")
+        
+        error_msg = "未知错误"
+        try:
+            error_data = response.json()
+            error_msg = error_data.get("message", "请求失败")
+        except:
+            pass
+        print(f"API调用失败: {error_msg}")
+        raise Exception(error_msg)
+    except Exception as e:
+        print(f"请求异常: {str(e)}")
+        raise
+```
+
+### Java (OkHttp)
+
+```java
+import com.squareup.okhttp.*;
+import org.json.JSONObject;
+import java.io.IOException;
+
+public class D1ktApiClient {
+    private static final String BASE_URL = "https://d1kt.cn/api/api";
+    private static final MediaType JSON = MediaType.parse("application/json; charset=utf-8");
+    private final OkHttpClient client = new OkHttpClient();
+    
+    // 登录API调用示例
+    public JSONObject login(String username, String password) throws Exception {
+        JSONObject requestBody = new JSONObject();
+        requestBody.put("username", username);
+        requestBody.put("password", password);
+        
+        Request request = new Request.Builder()
+                .url(BASE_URL + "/auth/login")
+                .post(RequestBody.create(JSON, requestBody.toString()))
+                .build();
+                
+        try (Response response = client.newCall(request).execute()) {
+            String responseBody = response.body().string();
+            
+            if (!response.isSuccessful()) {
+                JSONObject errorJson = new JSONObject(responseBody);
+                String errorMessage = errorJson.optString("message", "登录失败");
+                throw new Exception(errorMessage);
+            }
+            
+            return new JSONObject(responseBody);
+        } catch (IOException e) {
+            throw new Exception("网络请求异常: " + e.getMessage());
+        }
+    }
+    
+    // 注册API调用示例
+    public JSONObject register(String username, String email, String fullname, String password) throws Exception {
+        JSONObject requestBody = new JSONObject();
+        requestBody.put("username", username);
+        requestBody.put("email", email);
+        requestBody.put("fullname", fullname);
+        requestBody.put("password", password);
+        
+        Request request = new Request.Builder()
+                .url(BASE_URL + "/auth/register")
+                .post(RequestBody.create(JSON, requestBody.toString()))
+                .build();
+                
+        try (Response response = client.newCall(request).execute()) {
+            String responseBody = response.body().string();
+            
+            if (!response.isSuccessful()) {
+                JSONObject errorJson = new JSONObject(responseBody);
+                String errorMessage = errorJson.optString("message", "注册失败");
+                throw new Exception(errorMessage);
+            }
+            
+            return new JSONObject(responseBody);
+        } catch (IOException e) {
+            throw new Exception("网络请求异常: " + e.getMessage());
+        }
+    }
+    
+    // 带身份验证的API调用示例
+    public JSONObject callAuthenticatedAPI(String endpoint, String token) throws Exception {
+        Request request = new Request.Builder()
+                .url(BASE_URL + endpoint)
+                .header("Authorization", "Bearer " + token)
+                .build();
+                
+        try (Response response = client.newCall(request).execute()) {
+            String responseBody = response.body().string();
+            
+            if (!response.isSuccessful()) {
+                if (response.code() == 401) {
+                    throw new Exception("会话已过期，请重新登录");
+                }
+                
+                JSONObject errorJson = new JSONObject(responseBody);
+                String errorMessage = errorJson.optString("message", "请求失败");
+                throw new Exception(errorMessage);
+            }
+            
+            return new JSONObject(responseBody);
+        } catch (IOException e) {
+            throw new Exception("网络请求异常: " + e.getMessage());
+        }
+    }
+}
+```
+
+## 错误处理
+
+所有API错误响应都会返回HTTP错误状态码和JSON格式的错误信息：
+
+```json
+{
+  "message": "错误描述信息"
+}
+```
+
+### 常见HTTP状态码
+
+| 状态码 | 描述 |
+|--------|------|
+| 200 | 请求成功 |
+| 400 | 无效请求（如参数错误、格式错误等） |
+| 401 | 认证失败（如令牌无效或过期） |
+| 403 | 权限不足 |
+| 404 | 资源不存在 |
+| 409 | 资源冲突（如用户名已存在） |
+| 500 | 服务器内部错误 |
+
+### 错误处理最佳实践
+
+1. 始终捕获并处理API调用中可能发生的异常
+2. 为用户提供有意义的错误消息
+3. 在认证失败时，引导用户重新登录
+4. 实现适当的重试机制，处理临时性网络问题
+
+## 安全建议
+
+1. **HTTPS通信**: 所有API请求都必须使用HTTPS协议，确保数据传输安全
+2. **安全存储令牌**: 在客户端安全存储用户令牌，避免XSS攻击
+3. **令牌过期处理**: 当令牌过期时，引导用户重新登录
+4. **敏感信息处理**: 敏感信息不应明文存储在客户端
+5. **防CSRF**: 实现适当的CSRF防护机制
+6. **限制登录尝试**: 实现账户锁定机制，防止暴力破解
+
+## 集成流程
+
+1. **实现登录/注册界面**: 创建符合您应用风格的登录和注册表单
+2. **表单验证**: 在客户端进行基本的表单验证，确保数据符合API要求
+3. **调用API**: 使用上述代码示例实现API调用
+4. **处理响应**: 根据API响应更新UI和应用状态
+5. **令牌管理**: 实现令牌的存储、使用和更新机制
+6. **用户会话**: 维护用户会话状态，处理登录/登出逻辑
+
+## 联系与支持
+
+如有任何问题或需要进一步的支持，请联系D1KT技术支持团队。
+
+---
+
+© 2023 D1KT平台 - 保留所有权利