whale-town-front/docs/03-技术实现/网络管理器设置.md

NetworkManager 设置指南

概述

NetworkManager 是一个统一的网络请求管理器，提供了简洁的API接口和统一的错误处理机制。配合 ResponseHandler，可以大大简化网络请求的处理逻辑。

🚀 快速设置

1. 设置AutoLoad

在Godot编辑器中：

1. 打开 Project → Project Settings
2. 切换到 AutoLoad 标签
3. 添加新的AutoLoad：
   • Path: res://_Core/managers/NetworkManager.gd
   • Name: NetworkManager
   • Singleton: ✅ 勾选

2. 项目设置文件配置

在 project.godot 文件中会自动添加：

[autoload]

NetworkManager="*res://_Core/managers/NetworkManager.gd"

3. 验证设置

在任何脚本中可以直接使用：

func _ready():
    # 直接访问全局单例
    var request_id = NetworkManager.login("username", "password", callback)
    print("请求ID: ", request_id)

📚 使用方法

基本用法

# 1. 简单的GET请求
var request_id = NetworkManager.get_app_status(func(success, data, error_info):
    if success:
        print("应用状态: ", data)
    else:
        print("获取状态失败: ", error_info)
)

# 2. 用户登录
NetworkManager.login("username", "password", func(success, data, error_info):
    if success:
        print("登录成功: ", data.data.user.username)
    else:
        print("登录失败: ", error_info.message)
)

# 3. 发送验证码
NetworkManager.send_email_verification("test@example.com", func(success, data, error_info):
    if success:
        print("验证码已发送")
    else:
        print("发送失败: ", error_info.message)
)

配合ResponseHandler使用

# 在回调函数中使用ResponseHandler处理响应
func _on_login_response(success: bool, data: Dictionary, error_info: Dictionary):
    # 使用ResponseHandler统一处理
    var result = ResponseHandler.handle_login_response(success, data, error_info)
    
    # 显示Toast消息
    show_toast(result.message, result.success)
    
    # 执行自定义动作
    if result.custom_action.is_valid():
        result.custom_action.call()
    
    # 处理成功情况
    if result.success:
        # 登录成功的处理逻辑
        login_success.emit(username)

全局事件监听

func _ready():
    # 监听全局网络事件
    NetworkManager.request_completed.connect(_on_global_request_completed)
    NetworkManager.request_failed.connect(_on_global_request_failed)

func _on_global_request_completed(request_id: String, success: bool, data: Dictionary):
    print("全局请求完成: ", request_id)
    # 可以在这里隐藏全局加载指示器

func _on_global_request_failed(request_id: String, error_type: String, message: String):
    print("全局请求失败: ", request_id, " - ", message)
    # 可以在这里显示全局错误提示

🔧 高级功能

请求管理

# 取消特定请求
var request_id = NetworkManager.login("user", "pass", callback)
NetworkManager.cancel_request(request_id)

# 取消所有请求
NetworkManager.cancel_all_requests()

# 检查请求状态
if NetworkManager.is_request_active(request_id):
    print("请求仍在进行中")

# 获取活动请求数量
print("当前活动请求: ", NetworkManager.get_active_request_count())

自定义请求

# 发送自定义POST请求
var custom_data = {
    "custom_field": "custom_value"
}
var request_id = NetworkManager.post_request("/custom/endpoint", custom_data, func(success, data, error_info):
    print("自定义请求完成")
)

# 发送自定义GET请求
NetworkManager.get_request("/custom/data", func(success, data, error_info):
    print("获取自定义数据")
)

📋 API接口列表

认证相关

方法	参数	说明
login(identifier, password, callback)	用户标识符、密码、回调函数	用户登录
verification_code_login(identifier, code, callback)	用户标识符、验证码、回调函数	验证码登录
send_login_verification_code(identifier, callback)	用户标识符、回调函数	发送登录验证码
register(username, password, nickname, email, code, callback)	注册信息、回调函数	用户注册
send_email_verification(email, callback)	邮箱、回调函数	发送邮箱验证码
verify_email(email, code, callback)	邮箱、验证码、回调函数	验证邮箱

通用请求

方法	参数	说明
get_request(endpoint, callback, timeout)	端点、回调函数、超时时间	GET请求
post_request(endpoint, data, callback, timeout)	端点、数据、回调函数、超时时间	POST请求
put_request(endpoint, data, callback, timeout)	端点、数据、回调函数、超时时间	PUT请求
delete_request(endpoint, callback, timeout)	端点、回调函数、超时时间	DELETE请求

请求管理

方法	参数	说明
cancel_request(request_id)	请求ID	取消特定请求
cancel_all_requests()	无	取消所有请求
is_request_active(request_id)	请求ID	检查请求是否活动
get_active_request_count()	无	获取活动请求数量
get_request_info(request_id)	请求ID	获取请求详细信息

🎯 ResponseHandler 使用

支持的响应类型

方法	说明
handle_login_response()	处理登录响应
handle_verification_code_login_response()	处理验证码登录响应
handle_send_verification_code_response()	处理发送验证码响应
handle_send_login_code_response()	处理发送登录验证码响应
handle_register_response()	处理注册响应
handle_verify_email_response()	处理邮箱验证响应
handle_network_test_response()	处理网络测试响应
handle_response(operation_type, ...)	通用响应处理

ResponseResult 结构

class ResponseResult:
    var success: bool              # 是否成功
    var message: String           # 显示消息
    var toast_type: String        # Toast类型 ("success" 或 "error")
    var data: Dictionary          # 响应数据
    var should_show_toast: bool   # 是否显示Toast
    var custom_action: Callable   # 自定义动作

🔄 迁移指南

从旧版AuthScene迁移

旧代码：

func send_login_request(username: String, password: String):
    var url = API_BASE_URL + "/auth/login"
    var headers = ["Content-Type: application/json"]
    var body = JSON.stringify({
        "username": username,
        "password": password
    })
    
    current_request_type = "login"
    
    var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
    if error != OK:
        show_toast('网络请求失败', false)
        restore_button(login_btn, "密码登录")
        current_request_type = ""

新代码：

func send_login_request(username: String, password: String):
    NetworkManager.login(username, password, _on_login_response)

func _on_login_response(success: bool, data: Dictionary, error_info: Dictionary):
    var result = ResponseHandler.handle_login_response(success, data, error_info)
    show_toast(result.message, result.success)
    
    if result.success:
        login_success.emit(username)

迁移步骤

1. 设置AutoLoad：按照上述步骤设置NetworkManager为AutoLoad
2. 替换请求方法：将直接的HTTP请求替换为NetworkManager调用
3. 统一响应处理：使用ResponseHandler处理所有响应
4. 移除重复代码：删除重复的错误处理和请求构建代码
5. 测试功能：确保所有功能正常工作

🧪 测试

单元测试示例

extends GutTest

func test_network_manager_login():
    var network_manager = NetworkManager.new()
    var callback_called = false
    var callback_success = false
    
    var callback = func(success, data, error_info):
        callback_called = true
        callback_success = success
    
    var request_id = network_manager.login("testuser", "password", callback)
    
    assert_ne(request_id, "", "应该返回有效的请求ID")
    
    # 等待请求完成
    await get_tree().create_timer(2.0).timeout
    
    assert_true(callback_called, "回调函数应该被调用")

集成测试

func test_complete_login_flow():
    # 1. 发送登录验证码
    var code_sent = false
    NetworkManager.send_login_verification_code("test@example.com", func(success, data, error_info):
        code_sent = success
    )
    
    await get_tree().create_timer(1.0).timeout
    assert_true(code_sent, "验证码应该发送成功")
    
    # 2. 使用验证码登录
    var login_success = false
    NetworkManager.verification_code_login("test@example.com", "123456", func(success, data, error_info):
        login_success = success
    )
    
    await get_tree().create_timer(1.0).timeout
    assert_true(login_success, "验证码登录应该成功")

🔍 调试

启用详细日志

在NetworkManager中，所有请求都会输出详细的调试信息：

=== 发送网络请求 ===
请求ID: req_1
URL: https://whaletownend.xinghangee.icu/auth/login
方法: POST
Headers: ["Content-Type: application/json"]
Body: {"username":"testuser","password":"password123"}
发送结果: 0

=== 网络请求完成 ===
请求ID: req_1
结果: 0
状态码: 200
响应头: ["content-type: application/json"]
响应体长度: 156 字节
响应内容: {"success":true,"data":{"user":{"username":"testuser"}}}

常见问题

1. 请求ID为空：检查NetworkManager是否正确设置为AutoLoad
2. 回调未调用：检查网络连接和API地址是否正确
3. 解析错误：检查服务器返回的JSON格式是否正确

📈 性能优化

请求池管理

NetworkManager自动管理请求资源：

• 自动清理完成的请求
• 防止内存泄漏
• 支持请求取消

最佳实践

1. 及时取消不需要的请求
2. 使用合适的超时时间
3. 避免同时发送大量请求
4. 在场景切换时取消活动请求

func _exit_tree():
    # 场景退出时取消所有请求
    NetworkManager.cancel_all_requests()

🎉 总结

使用NetworkManager和ResponseHandler的优势：

• ✅ 代码简洁：一行代码发送请求
• ✅ 统一处理：所有错误情况统一处理
• ✅ 易于维护：网络逻辑与UI逻辑分离
• ✅ 功能强大：支持请求管理、超时、取消等
• ✅ 调试友好：详细的日志和错误信息
• ✅ 类型安全：明确的回调参数类型
• ✅ 可扩展：易于添加新的API接口

通过这套统一的网络管理系统，你的项目将拥有更好的代码结构和更强的可维护性！