forked from datawhale/whale-town-front
docs：为核心管理器添加详细中文注释
- GameManager.gd：游戏状态管理注释 - NetworkManager.gd：网络请求管理注释 - SceneManager.gd：场景切换管理注释 - StringUtils.gd：字符串工具函数注释 按照docs注释规范，添加文件头、函数说明、参数描述和使用示例 方便协同开发者快速理解和调用
This commit is contained in:
@@ -1,45 +1,96 @@
|
||||
extends Node
|
||||
|
||||
# 网络请求管理器 - 统一处理所有HTTP请求
|
||||
# ============================================================================
|
||||
# NetworkManager.gd - 网络请求管理器
|
||||
# ============================================================================
|
||||
# 全局单例管理器，统一处理所有HTTP请求
|
||||
#
|
||||
# 核心职责:
|
||||
# - 统一的HTTP请求接口 (GET, POST, PUT, DELETE, PATCH)
|
||||
# - 认证相关API封装 (登录、注册、验证码等)
|
||||
# - 请求状态管理和错误处理
|
||||
# - 支持API v1.1.1规范的响应处理
|
||||
#
|
||||
# 使用方式:
|
||||
# NetworkManager.login("user@example.com", "password", callback)
|
||||
# var request_id = NetworkManager.get_request("/api/data", callback)
|
||||
#
|
||||
# 注意事项:
|
||||
# - 作为自动加载单例，全局可访问
|
||||
# - 所有请求都是异步的，通过回调函数或信号处理结果
|
||||
# - 支持请求超时和取消功能
|
||||
# - 自动处理JSON序列化和反序列化
|
||||
# ============================================================================
|
||||
|
||||
# 信号定义
|
||||
# ============ 信号定义 ============
|
||||
|
||||
# 请求完成信号
|
||||
# 参数:
|
||||
# request_id: String - 请求唯一标识符
|
||||
# success: bool - 请求是否成功
|
||||
# data: Dictionary - 响应数据
|
||||
signal request_completed(request_id: String, success: bool, data: Dictionary)
|
||||
|
||||
# 请求失败信号
|
||||
# 参数:
|
||||
# request_id: String - 请求唯一标识符
|
||||
# error_type: String - 错误类型名称
|
||||
# message: String - 错误消息
|
||||
signal request_failed(request_id: String, error_type: String, message: String)
|
||||
|
||||
# API配置
|
||||
# ============ 常量定义 ============
|
||||
|
||||
# API基础URL - 所有请求的根地址
|
||||
const API_BASE_URL = "https://whaletownend.xinghangee.icu"
|
||||
|
||||
# 默认请求超时时间（秒）
|
||||
const DEFAULT_TIMEOUT = 30.0
|
||||
|
||||
# 请求类型枚举
|
||||
# ============ 枚举定义 ============
|
||||
|
||||
# HTTP请求方法枚举
|
||||
enum RequestType {
|
||||
GET,
|
||||
POST,
|
||||
PUT,
|
||||
DELETE,
|
||||
PATCH
|
||||
GET, # 获取数据
|
||||
POST, # 创建数据
|
||||
PUT, # 更新数据
|
||||
DELETE, # 删除数据
|
||||
PATCH # 部分更新数据
|
||||
}
|
||||
|
||||
# 错误类型枚举
|
||||
# 用于分类不同类型的网络错误
|
||||
enum ErrorType {
|
||||
NETWORK_ERROR, # 网络连接错误
|
||||
TIMEOUT_ERROR, # 请求超时
|
||||
PARSE_ERROR, # JSON解析错误
|
||||
HTTP_ERROR, # HTTP状态码错误
|
||||
BUSINESS_ERROR # 业务逻辑错误
|
||||
NETWORK_ERROR, # 网络连接错误 - 无法连接到服务器
|
||||
TIMEOUT_ERROR, # 请求超时 - 服务器响应时间过长
|
||||
PARSE_ERROR, # JSON解析错误 - 服务器返回格式错误
|
||||
HTTP_ERROR, # HTTP状态码错误 - 4xx, 5xx状态码
|
||||
BUSINESS_ERROR # 业务逻辑错误 - API返回的业务错误
|
||||
}
|
||||
|
||||
# 请求状态
|
||||
# ============ 请求信息类 ============
|
||||
|
||||
# 请求信息封装类
|
||||
# 存储单个HTTP请求的所有相关信息
|
||||
class RequestInfo:
|
||||
var id: String
|
||||
var url: String
|
||||
var method: RequestType
|
||||
var headers: PackedStringArray
|
||||
var body: String
|
||||
var timeout: float
|
||||
var start_time: float
|
||||
var http_request: HTTPRequest
|
||||
var callback: Callable
|
||||
var id: String # 请求唯一标识符
|
||||
var url: String # 完整的请求URL
|
||||
var method: RequestType # HTTP请求方法
|
||||
var headers: PackedStringArray # 请求头数组
|
||||
var body: String # 请求体内容
|
||||
var timeout: float # 超时时间（秒）
|
||||
var start_time: float # 请求开始时间戳
|
||||
var http_request: HTTPRequest # Godot HTTPRequest节点引用
|
||||
var callback: Callable # 完成时的回调函数
|
||||
|
||||
# 构造函数
|
||||
#
|
||||
# 参数:
|
||||
# request_id: String - 请求唯一标识符
|
||||
# request_url: String - 请求URL
|
||||
# request_method: RequestType - HTTP方法
|
||||
# request_headers: PackedStringArray - 请求头（可选）
|
||||
# request_body: String - 请求体（可选）
|
||||
# request_timeout: float - 超时时间（可选，默认使用DEFAULT_TIMEOUT）
|
||||
func _init(request_id: String, request_url: String, request_method: RequestType,
|
||||
request_headers: PackedStringArray = [], request_body: String = "",
|
||||
request_timeout: float = DEFAULT_TIMEOUT):
|
||||
@@ -49,40 +100,107 @@ class RequestInfo:
|
||||
headers = request_headers
|
||||
body = request_body
|
||||
timeout = request_timeout
|
||||
# 记录请求开始时间（简化版时间戳）
|
||||
start_time = Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second
|
||||
|
||||
# 活动请求管理
|
||||
var active_requests: Dictionary = {}
|
||||
var request_counter: int = 0
|
||||
# ============ 成员变量 ============
|
||||
|
||||
# 活动请求管理
|
||||
var active_requests: Dictionary = {} # 存储所有活动请求 {request_id: RequestInfo}
|
||||
var request_counter: int = 0 # 请求计数器，用于生成唯一ID
|
||||
|
||||
# ============ 生命周期方法 ============
|
||||
|
||||
# 初始化网络管理器
|
||||
# 在节点准备就绪时调用
|
||||
func _ready():
|
||||
print("NetworkManager 已初始化")
|
||||
|
||||
# ============ 公共API接口 ============
|
||||
|
||||
# 发送GET请求
|
||||
#
|
||||
# 参数:
|
||||
# endpoint: String - API端点路径（如: "/api/users"）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
# timeout: float - 超时时间（可选，默认30秒）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID，可用于取消请求或跟踪状态
|
||||
#
|
||||
# 使用示例:
|
||||
# var request_id = NetworkManager.get_request("/api/users", my_callback)
|
||||
func get_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
||||
return send_request(endpoint, RequestType.GET, [], "", callback, timeout)
|
||||
|
||||
# 发送POST请求
|
||||
#
|
||||
# 参数:
|
||||
# endpoint: String - API端点路径
|
||||
# data: Dictionary - 要发送的数据（将自动转换为JSON）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
# timeout: float - 超时时间（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 使用示例:
|
||||
# var data = {"name": "张三", "age": 25}
|
||||
# var request_id = NetworkManager.post_request("/api/users", data, my_callback)
|
||||
func post_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
||||
var body = JSON.stringify(data)
|
||||
var headers = ["Content-Type: application/json"]
|
||||
return send_request(endpoint, RequestType.POST, headers, body, callback, timeout)
|
||||
|
||||
# 发送PUT请求
|
||||
#
|
||||
# 参数:
|
||||
# endpoint: String - API端点路径
|
||||
# data: Dictionary - 要更新的数据
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
# timeout: float - 超时时间（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
func put_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
||||
var body = JSON.stringify(data)
|
||||
var headers = ["Content-Type: application/json"]
|
||||
return send_request(endpoint, RequestType.PUT, headers, body, callback, timeout)
|
||||
|
||||
# 发送DELETE请求
|
||||
#
|
||||
# 参数:
|
||||
# endpoint: String - API端点路径
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
# timeout: float - 超时时间（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
func delete_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
||||
return send_request(endpoint, RequestType.DELETE, [], "", callback, timeout)
|
||||
|
||||
# ============ 认证相关API ============
|
||||
|
||||
# 用户登录
|
||||
#
|
||||
# 参数:
|
||||
# identifier: String - 用户标识符（邮箱或手机号）
|
||||
# password: String - 用户密码
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 回调函数签名:
|
||||
# func callback(success: bool, data: Dictionary, error_info: Dictionary)
|
||||
#
|
||||
# 使用示例:
|
||||
# NetworkManager.login("user@example.com", "password123", func(success, data, error):
|
||||
# if success:
|
||||
# print("登录成功: ", data)
|
||||
# else:
|
||||
# print("登录失败: ", error.message)
|
||||
# )
|
||||
func login(identifier: String, password: String, callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"identifier": identifier,
|
||||
@@ -91,6 +209,18 @@ func login(identifier: String, password: String, callback: Callable = Callable()
|
||||
return post_request("/auth/login", data, callback)
|
||||
|
||||
# 验证码登录
|
||||
#
|
||||
# 参数:
|
||||
# identifier: String - 用户标识符（邮箱或手机号）
|
||||
# verification_code: String - 验证码
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 使用场景:
|
||||
# - 用户忘记密码时的替代登录方式
|
||||
# - 提供更安全的登录选项
|
||||
func verification_code_login(identifier: String, verification_code: String, callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"identifier": identifier,
|
||||
@@ -99,11 +229,39 @@ func verification_code_login(identifier: String, verification_code: String, call
|
||||
return post_request("/auth/verification-code-login", data, callback)
|
||||
|
||||
# 发送登录验证码
|
||||
#
|
||||
# 参数:
|
||||
# identifier: String - 用户标识符（邮箱或手机号）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 向已注册用户发送登录验证码
|
||||
# - 支持邮箱和手机号
|
||||
# - 有频率限制保护
|
||||
func send_login_verification_code(identifier: String, callback: Callable = Callable()) -> String:
|
||||
var data = {"identifier": identifier}
|
||||
return post_request("/auth/send-login-verification-code", data, callback)
|
||||
|
||||
# 用户注册
|
||||
#
|
||||
# 参数:
|
||||
# username: String - 用户名
|
||||
# password: String - 密码
|
||||
# nickname: String - 昵称
|
||||
# email: String - 邮箱地址（可选）
|
||||
# email_verification_code: String - 邮箱验证码（可选）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 注意事项:
|
||||
# - 如果提供邮箱，建议同时提供验证码
|
||||
# - 用户名和邮箱必须唯一
|
||||
# - 密码需要符合安全要求
|
||||
func register(username: String, password: String, nickname: String, email: String = "",
|
||||
email_verification_code: String = "", callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
@@ -112,6 +270,7 @@ func register(username: String, password: String, nickname: String, email: Strin
|
||||
"nickname": nickname
|
||||
}
|
||||
|
||||
# 可选参数处理
|
||||
if email != "":
|
||||
data["email"] = email
|
||||
if email_verification_code != "":
|
||||
@@ -120,11 +279,35 @@ func register(username: String, password: String, nickname: String, email: Strin
|
||||
return post_request("/auth/register", data, callback)
|
||||
|
||||
# 发送邮箱验证码
|
||||
#
|
||||
# 参数:
|
||||
# email: String - 邮箱地址
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 向指定邮箱发送验证码
|
||||
# - 用于注册时的邮箱验证
|
||||
# - 支持测试模式（开发环境）
|
||||
func send_email_verification(email: String, callback: Callable = Callable()) -> String:
|
||||
var data = {"email": email}
|
||||
return post_request("/auth/send-email-verification", data, callback)
|
||||
|
||||
# 验证邮箱
|
||||
#
|
||||
# 参数:
|
||||
# email: String - 邮箱地址
|
||||
# verification_code: String - 验证码
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 验证邮箱验证码的有效性
|
||||
# - 通常在注册流程中使用
|
||||
func verify_email(email: String, verification_code: String, callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"email": email,
|
||||
@@ -133,20 +316,66 @@ func verify_email(email: String, verification_code: String, callback: Callable =
|
||||
return post_request("/auth/verify-email", data, callback)
|
||||
|
||||
# 获取应用状态
|
||||
#
|
||||
# 参数:
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 检查API服务器状态
|
||||
# - 获取应用基本信息
|
||||
# - 用于网络连接测试
|
||||
func get_app_status(callback: Callable = Callable()) -> String:
|
||||
return get_request("/", callback)
|
||||
|
||||
# 重新发送邮箱验证码
|
||||
#
|
||||
# 参数:
|
||||
# email: String - 邮箱地址
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 使用场景:
|
||||
# - 用户未收到验证码时重新发送
|
||||
# - 验证码过期后重新获取
|
||||
func resend_email_verification(email: String, callback: Callable = Callable()) -> String:
|
||||
var data = {"email": email}
|
||||
return post_request("/auth/resend-email-verification", data, callback)
|
||||
|
||||
# 忘记密码 - 发送重置验证码
|
||||
#
|
||||
# 参数:
|
||||
# identifier: String - 用户标识符（邮箱或手机号）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 向用户发送密码重置验证码
|
||||
# - 用于密码找回流程的第一步
|
||||
func forgot_password(identifier: String, callback: Callable = Callable()) -> String:
|
||||
var data = {"identifier": identifier}
|
||||
return post_request("/auth/forgot-password", data, callback)
|
||||
|
||||
# 重置密码
|
||||
#
|
||||
# 参数:
|
||||
# identifier: String - 用户标识符
|
||||
# verification_code: String - 重置验证码
|
||||
# new_password: String - 新密码
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 使用验证码重置用户密码
|
||||
# - 密码找回流程的第二步
|
||||
func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"identifier": identifier,
|
||||
@@ -156,6 +385,19 @@ func reset_password(identifier: String, verification_code: String, new_password:
|
||||
return post_request("/auth/reset-password", data, callback)
|
||||
|
||||
# 修改密码
|
||||
#
|
||||
# 参数:
|
||||
# user_id: String - 用户ID
|
||||
# old_password: String - 旧密码
|
||||
# new_password: String - 新密码
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 已登录用户修改密码
|
||||
# - 需要验证旧密码
|
||||
func change_password(user_id: String, old_password: String, new_password: String, callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"user_id": user_id,
|
||||
@@ -165,6 +407,21 @@ func change_password(user_id: String, old_password: String, new_password: String
|
||||
return put_request("/auth/change-password", data, callback)
|
||||
|
||||
# GitHub OAuth登录
|
||||
#
|
||||
# 参数:
|
||||
# github_id: String - GitHub用户ID
|
||||
# username: String - GitHub用户名
|
||||
# nickname: String - 显示昵称
|
||||
# email: String - GitHub邮箱
|
||||
# avatar_url: String - 头像URL（可选）
|
||||
# callback: Callable - 完成时的回调函数（可选）
|
||||
#
|
||||
# 返回值:
|
||||
# String - 请求ID
|
||||
#
|
||||
# 功能:
|
||||
# - 通过GitHub账号登录或注册
|
||||
# - 支持第三方OAuth认证
|
||||
func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String = "", callback: Callable = Callable()) -> String:
|
||||
var data = {
|
||||
"github_id": github_id,
|
||||
@@ -173,6 +430,7 @@ func github_login(github_id: String, username: String, nickname: String, email:
|
||||
"email": email
|
||||
}
|
||||
|
||||
# 可选头像URL
|
||||
if avatar_url != "":
|
||||
data["avatar_url"] = avatar_url
|
||||
|
||||
|
||||
Reference in New Issue
Block a user