GGNetwork (内测版)

面向游戏客户端的可插拔网络框架 —— 内置异常重试 / 断线重连 / HttpDNS / 异常上报，HTTP、Socket、域名解析底层均可自由替换。

快速开始

复制框架与依赖目录到你的工程，并在 Packages/manifest.json 添加 GGFramework.Core 依赖（#v0.1.1，基础类单一源），初始化后即可发请求：

using GGFramework.GGNetwork;

// 1. 复制 GGNetwork/Assets/Scripts/GGNetwork/ 与 Dependency/ 到你的工程，并添加 GGFramework.Core UPM 依赖（#v0.1.1）
// 2. 初始化（启动时调用一次）
NetworkConst.InitEx(secretKey: "your-key", deviceUID: SystemInfo.deviceUniqueIdentifier,
    channel: "google-play", clientVersion: Application.version);
GameNetworkSystem.Instance.Init();

// 3. 发请求
JsonObject param = new JsonObject();
param["username"] = "player1";
HttpNetworkSystem.Instance.PostWebRequest("http://api.example.com", "/user/login",
    param, HttpNetworkSystem.ExceptionAction.ConfirmRetry,
    (JsonObject response) => Debug.Log(response.ToString()));

完整接入流程见 如何快速接入? 与 技术手册

简介

它不是一个网络功能的底层实现，它封装了游戏客户端所需的一些网络特性，让游戏网络的稳定性和体验感更好。并且可以很方便地挂载第三方或者自定义的网络底层模块。

框架面向不同业务层级的功能划分：

• 游戏业务层 — 交给游戏业务开发环节处理
• 游戏网络层 — 框架提供异常检查与处理
• 网络通信层 — 框架提供异常检查与处理

目标

为游戏客户端提供：

• 更好的网络稳定性
• 更好的网络交互体验

功能与特性

网络交互体验

• 支持 UI 反馈回调挂载，接入简单，当网络连接、请求发生异常或等待时，获得更好的交互体验
• 支持多线程请求，避免网络卡顿对 UI 产生影响
• 支持请求异常响应，例如失败后自动重试、手动重试、忽略等
• 支持断线重连，包括自动重连、手动重连

网络质量保障

• 支持 HttpDNS，避免玩家端的 DNS 劫持
• 支持网络异常上报，让开发者了解分布各地的玩家的网络状况

第三方支持

• 支持 HTTP/HTTPS 连接（已实现）：默认使用 Unity 原生 UnityWebRequest 作为 HTTP 底层（内部实现，具备超时/Header 注入/状态映射/异常上报，HttpNetworkSystem.UseUnityWebRequest 可回退）；也可挂载自定义或其它第三方 HTTP 模块
• 支持 Socket / 长连接（已实现）：内置基于 WebSocket + Pomelo 协议的客户端（GGFramework.GGNetwork.Socket.WebSocket，传输层用 ClientWebSocket，应用层内化握手/心跳/请求-响应/推送路由）；可通过 BaseNetworkClient 挂载其它第三方长连接模块，并保留 TCP 版 PomeloClient 作为可切换回退（NetworkSystem.UseWebSocket=false）
• 支持 HttpDNS Provider 插拔：预置橙域实现，工厂预留腾讯、阿里

可插拔设计：框架通过 IHTTPFactory（HTTP 底层）、BaseNetworkClient（长连接底层）、UIAdaptor/LogAdaptor（UI 与上报解耦）、HTTPDNSFactory（域名解析）等抽象接口，将各类底层实现与业务解耦，可自由替换或挂载第三方实现。

工程内容

目录	内容	说明
GGNetwork/Assets/Scripts/GGNetwork	框架代码	可以直接复制到目标工程中使用。
GGNetwork/Assets/Demo	演示工程	可以作为框架使用的参考。

核心模块

模块	说明
GameNetworkSystem	系统总入口，按固定顺序完成整体初始化编排
HttpNetworkSystem	HTTP 层总入口：Post/Get 请求、异常处理策略、参数签名、多线程、结果统一分发
NetworkSystem	长连接总入口：客户端连接管理（默认 game / notify 两条）、请求发送、轮询刷新
DownloadSystem	文件下载管理：Unity 原生 DownloadHandlerFile 边下边写、进度/总大小回调、失败自动重试
HTTPDNSSystem	域名解析：本地缓存、TTL 定时刷新、按 IP 替换 host
ServiceCenter	网络服务中心：连接/请求超时参数、服务域名动态刷新

架构

文档

• 如何快速接入?
• 技术手册
• 参考文档(TODO)

交流反馈

使用过程中遇到问题、有改进建议，或是想聊聊游戏客户端网络方面的经验，欢迎加入我们：

渠道	说明
QQ 群 242500383	点击加入游戏研发与技术交流群，群内可即时反馈问题
GitHub Issues	提交 bug / 功能建议，点右上角 New Issue

内测期间，你的每一个反馈都在帮助框架变得更好。

依赖

依赖	性质	说明 / 获取方式
Unity Web Request	内置（默认）	HTTP 底层默认内置 Unity 原生实现（传输层用 UnityEngine.Networking.UnityWebRequest，见 Scripts/GGNetwork/HTTP），不依赖第三方 HTTP 库
Best HTTP (Pro)	可选（第三方适配）	原 HTTP 底层，已迁移；如需回退可选购导入后经 HttpNetworkSystem.UseUnityWebRequest=false 启用，见下方"获取 Best HTTP (Pro)"
PomeloClient / UnityWebSocket	内置（回退）	长连接默认已内置内部 WebSocket 实现（Scripts/GGNetwork/Socket/WebSocket）；外部 TCP 版 PomeloClient 仅作可选回退底层（Assets/LocalPackages，NetworkSystem.UseWebSocket=false 时启用）
GGFramework.Core	UPM（必需）	Singleton / CoroutineUtil / TaskSystem（GTask）的单一源，经 UPM git URL 引用 #v0.1.1；工程内本地副本已删除
Dependency/Utils	内置	GameDebugger / ZipUtil 等通用工具（Singleton / CoroutineUtil / TaskSystem 已移至 GGFramework.Core）

获取 Best HTTP (Pro)

Best HTTP (Pro) 是付费商业插件，出于许可协议考虑不随仓库分发。使用前需：

1. 从 Asset Store - Best HTTP (Pro) 或 官方商店 购买并下载
2. 将插件导入到 GGNetwork/Assets/LocalPackages/Best HTTP (Pro)/
3. 确认与框架引用的版本匹配（框架已适配其公开 API）

说明：框架 HTTP 层与下载系统均已默认使用 Unity 原生实现，无需 Best HTTP (Pro) 即可运行。Best HTTP (Pro) 现为可选回退（HttpNetworkSystem.UseUnityWebRequest=false 时启用）；也可通过 IHTTPFactory 挂载其它第三方 HTTP 实现。

TODO-List

• 把 PomeloClient 充分剥离出来，作为可选插件（已实现：内置 WebSocket + Pomelo 内部实现 GGFramework.GGNetwork.Socket.WebSocket，已作为默认长连接底层；NetworkSystem.UseWebSocket 可回退 TCP）
• 更完整的 Demo 演示（含 WebSocket 长连接联机示例）
• 补充架构分层示意图 (mermaid / SVG)

更多资料

• 游戏开发图谱
  • 客户端网络系统