From 8ef7eabec8cc2ed24118c79b98d498d8acad5d0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BD=95=E5=86=A0=E5=B3=B0?= Date: Tue, 20 Jan 2026 18:02:04 +0800 Subject: [PATCH] =?UTF-8?q?refactor=20:=20=E9=87=8D=E6=9E=84=E4=BB=A3?= =?UTF-8?q?=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../DiagnosticSystem/DiagnosticBundleInfo.cs | 2 +- .../DiagnosticOperationInfo.cs | 6 ++-- .../DiagnosticProviderInfo.cs | 4 +-- .../DiagnosticSystem/DiagnosticReport.cs | 8 ++++-- .../DiagnosticSystem/EDebugCommandType.cs | 3 ++ .../DiagnosticSystem/RemoteDebugCommand.cs | 8 ++++-- .../DownloadSystem/DownloadFailureCounter.cs | 14 +++++++++- .../DownloadSystem/DownloadRequestArgs.cs | 28 +++++++++++++++++++ .../DownloadSystem/DownloadSystemTools.cs | 16 +++++++++-- .../DownloadSystem/EDownloadRequestStatus.cs | 3 ++ .../Interface/IDownloadBackend.cs | 4 +++ .../Interface/IDownloadRequest.cs | 6 ++++ .../UnityWebBackend/UnityWebRequestCreator.cs | 9 +++++- .../UnityWebRequest/UnityWebRequestBase.cs | 2 +- 14 files changed, 97 insertions(+), 16 deletions(-) diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticBundleInfo.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticBundleInfo.cs index 5f43a0b9..10382121 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticBundleInfo.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticBundleInfo.cs @@ -21,7 +21,7 @@ namespace YooAsset public int ReferenceCount; /// - /// 当前状态 + /// 资源包的加载状态 /// public string Status; diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticOperationInfo.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticOperationInfo.cs index 9bdd66df..76c3edac 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticOperationInfo.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticOperationInfo.cs @@ -21,7 +21,7 @@ namespace YooAsset public string OperationDesc; /// - ///异步操作的优先级 + /// 异步操作的优先级 /// public uint Priority; @@ -36,12 +36,12 @@ namespace YooAsset public long ElapsedMS; /// - /// 当前进度 + /// 异步操作的执行进度 /// public float Progress; /// - /// 当前状态 + /// 异步操作的执行状态 /// public string Status; diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticProviderInfo.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticProviderInfo.cs index 44999439..2065fbf2 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticProviderInfo.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticProviderInfo.cs @@ -16,7 +16,7 @@ namespace YooAsset public string AssetPath; /// - /// 资源出生的场景 + /// 资源加载时所在的场景 /// public string OriginScene; @@ -36,7 +36,7 @@ namespace YooAsset public int ReferenceCount; /// - /// 当前状态 + /// 资源的加载状态 /// public string Status; diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticReport.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticReport.cs index 811a1e00..1757db46 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticReport.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/DiagnosticReport.cs @@ -28,16 +28,20 @@ namespace YooAsset public List PackageDataList = new List(10); /// - /// 序列化 + /// 序列化诊断报告为字节数组 /// + /// 要序列化的诊断报告 + /// UTF-8 编码的 JSON 字节数组 public static byte[] Serialize(DiagnosticReport report) { return Encoding.UTF8.GetBytes(JsonUtility.ToJson(report)); } /// - /// 反序列化 + /// 从字节数组反序列化诊断报告 /// + /// UTF-8 编码的 JSON 字节数组 + /// 反序列化后的诊断报告 public static DiagnosticReport Deserialize(byte[] data) { return JsonUtility.FromJson(Encoding.UTF8.GetString(data)); diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/EDebugCommandType.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/EDebugCommandType.cs index 9da5c9e7..6dd71ad5 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/EDebugCommandType.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/EDebugCommandType.cs @@ -1,6 +1,9 @@  namespace YooAsset { + /// + /// 远程调试命令类型 + /// internal enum EDebugCommandType { /// diff --git a/Assets/YooAsset/Runtime/DiagnosticSystem/RemoteDebugCommand.cs b/Assets/YooAsset/Runtime/DiagnosticSystem/RemoteDebugCommand.cs index 4dbc8446..f1384bba 100644 --- a/Assets/YooAsset/Runtime/DiagnosticSystem/RemoteDebugCommand.cs +++ b/Assets/YooAsset/Runtime/DiagnosticSystem/RemoteDebugCommand.cs @@ -23,16 +23,20 @@ namespace YooAsset /// - /// 序列化 + /// 序列化命令为字节数组 /// + /// 要序列化的远程调试命令 + /// UTF-8 编码的 JSON 字节数组 public static byte[] Serialize(RemoteDebugCommand command) { return Encoding.UTF8.GetBytes(JsonUtility.ToJson(command)); } /// - /// 反序列化 + /// 从字节数组反序列化命令 /// + /// UTF-8 编码的 JSON 字节数组 + /// 反序列化后的远程调试命令 public static RemoteDebugCommand Deserialize(byte[] data) { return JsonUtility.FromJson(Encoding.UTF8.GetString(data)); diff --git a/Assets/YooAsset/Runtime/DownloadSystem/DownloadFailureCounter.cs b/Assets/YooAsset/Runtime/DownloadSystem/DownloadFailureCounter.cs index 968d5c99..8031d8bf 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/DownloadFailureCounter.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/DownloadFailureCounter.cs @@ -3,8 +3,12 @@ using System.Collections.Generic; namespace YooAsset { /// - /// 网络请求失败计数器 + /// 网络请求失败计数器（诊断用） /// + /// + /// 线程安全：内部使用 Dictionary 且未加锁，约定只在 Unity 主线程调用。 + /// 如需在多线程/回调线程调用，请在外层加锁或改为并发容器实现。 + /// internal class DownloadFailureCounter { #if UNITY_EDITOR @@ -18,11 +22,16 @@ namespace YooAsset /// /// 失败计数记录表 /// + /// + /// Key 格式：$"{packageName}_{eventName}" + /// private static readonly Dictionary _failureRecords = new Dictionary(1000); /// /// 记录一次失败 /// + /// 资源包名称 + /// 事件名称 public static void RecordFailure(string packageName, string eventName) { string key = $"{packageName}_{eventName}"; @@ -34,6 +43,9 @@ namespace YooAsset /// /// 获取失败次数 /// + /// 资源包名称 + /// 事件名称 + /// 失败次数，如果未记录过则返回 0 public static int GetFailureCount(string packageName, string eventName) { string key = $"{packageName}_{eventName}"; diff --git a/Assets/YooAsset/Runtime/DownloadSystem/DownloadRequestArgs.cs b/Assets/YooAsset/Runtime/DownloadSystem/DownloadRequestArgs.cs index f2c661b0..710f1d23 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/DownloadRequestArgs.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/DownloadRequestArgs.cs @@ -66,11 +66,22 @@ namespace YooAsset /// /// 自定义请求头（可选） /// + /// + /// 使用 AddRequestHeader 方法添加请求头。 + /// 注意：相同 key 重复添加会抛出异常。 + /// public Dictionary Headers; /// /// 构造文件下载请求参数 /// + /// 请求地址 + /// 文件保存路径 + /// 响应超时时间（秒），0 表示不应用超时 + /// 看门狗超时时间（秒），0 表示禁用 + /// 是否追加写入文件（用于断点续传） + /// 中止时是否删除目标文件 + /// 断点续传的起始字节位置 public DownloadFileRequestArgs( string url, string savePath, @@ -139,11 +150,18 @@ namespace YooAsset /// /// 自定义请求头（可选） /// + /// + /// 使用 AddRequestHeader 方法添加请求头。 + /// 注意：相同 key 重复添加会抛出异常。 + /// public Dictionary Headers; /// /// 构造数据下载请求参数 /// + /// 请求地址 + /// 响应超时时间（秒），0 表示不应用超时 + /// 看门狗超时时间（秒），0 表示禁用 public DownloadDataRequestArgs(string url, int timeout, int watchdogTimeout) { URL = url; @@ -219,11 +237,21 @@ namespace YooAsset /// /// 自定义请求头（可选） /// + /// + /// 使用 AddRequestHeader 方法添加请求头。 + /// 注意：相同 key 重复添加会抛出异常。 + /// public Dictionary Headers; /// /// 构造 AssetBundle 下载请求参数 /// + /// 请求地址 + /// 响应超时时间（秒），0 表示不应用超时 + /// 看门狗超时时间（秒），0 表示禁用 + /// 是否禁用 Unity 内置缓存 + /// 文件哈希（启用缓存时必须提供） + /// Unity CRC 校验值 public DownloadAssetBundleRequestArgs( string url, int timeout, diff --git a/Assets/YooAsset/Runtime/DownloadSystem/DownloadSystemTools.cs b/Assets/YooAsset/Runtime/DownloadSystem/DownloadSystemTools.cs index 7abad2e1..145aad0c 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/DownloadSystemTools.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/DownloadSystemTools.cs @@ -1,11 +1,19 @@ - + namespace YooAsset { + /// + /// 下载系统工具类 + /// + /// + /// 提供跨平台的 URL 转换和判断功能。 + /// internal class DownloadSystemTools { /// /// 转换为本地文件请求地址 /// + /// 本地文件路径 + /// 可用于 UnityWebRequest 的文件协议 URL public static string ToLocalURL(string path) { string url; @@ -58,13 +66,15 @@ namespace YooAsset throw new System.NotSupportedException($"Platform '{UnityEngine.Application.platform}' is not supported."); #endif - // For some special cases when users have special characters in their devices, url paths can not be identified correctly. + // 处理特殊字符：用户设备路径可能包含特殊字符导致 URL 无法正确识别 return url.Replace("+", "%2B").Replace("#", "%23").Replace("?", "%3F"); } /// - /// 是否请求的本地文件 + /// 判断是否为本地文件 URL /// + /// 要判断的 URL + /// 如果是本地文件 URL 返回 true，否则返回 false public static bool IsLocalFileURL(string url) { //TODO UNITY_STANDALONE_OSX平台目前无法确定 diff --git a/Assets/YooAsset/Runtime/DownloadSystem/EDownloadRequestStatus.cs b/Assets/YooAsset/Runtime/DownloadSystem/EDownloadRequestStatus.cs index 76d6ecca..357ad62b 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/EDownloadRequestStatus.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/EDownloadRequestStatus.cs @@ -29,6 +29,9 @@ namespace YooAsset /// /// 已中止 /// + /// + /// 可能由用户主动调用 AbortRequest() 或看门狗超时触发。 + /// Aborted, } } diff --git a/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadBackend.cs b/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadBackend.cs index ae056bc6..09bd7138 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadBackend.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadBackend.cs @@ -5,6 +5,10 @@ namespace YooAsset /// /// 下载后台接口 /// + /// + /// 不同网络库（UnityWebRequest / BestHTTP / 自研）实现该接口，用于创建具体下载请求。 + /// 每个后台实例是独立的，不共享全局状态。 + /// internal interface IDownloadBackend : IDisposable { /// diff --git a/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadRequest.cs b/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadRequest.cs index 73b1af31..f7712ac6 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadRequest.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/Interface/IDownloadRequest.cs @@ -5,6 +5,9 @@ namespace YooAsset /// /// 可轮询的下载请求接口 /// + /// + /// 上层通常在每帧检查 IsDone 属性，完成后读取结果并调用 Dispose() 释放资源。 + /// internal interface IDownloadRequest : IDisposable { /// @@ -15,6 +18,9 @@ namespace YooAsset /// /// 是否完成（成功/失败/中止） /// + /// + /// 注意：访问此属性时会自动调用 PollingRequest() 进行轮询。 + /// bool IsDone { get; } /// diff --git a/Assets/YooAsset/Runtime/DownloadSystem/UnityWebBackend/UnityWebRequestCreator.cs b/Assets/YooAsset/Runtime/DownloadSystem/UnityWebBackend/UnityWebRequestCreator.cs index 75880dfb..dca8a8f9 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/UnityWebBackend/UnityWebRequestCreator.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/UnityWebBackend/UnityWebRequestCreator.cs @@ -3,7 +3,14 @@ using UnityEngine.Networking; namespace YooAsset { /// - /// 自定义下载器的请求委托 + /// 自定义 UnityWebRequest 创建委托 /// + /// + /// 用于自定义 UnityWebRequest 的创建方式，例如添加证书验证、代理设置等。 + /// 通过 UnityWebRequestBackend 构造函数传入。 + /// + /// 请求地址 + /// HTTP 方法（如 GET、HEAD） + /// 自定义配置的 UnityWebRequest 实例 public delegate UnityWebRequest UnityWebRequestCreator(string url, string method); } diff --git a/Assets/YooAsset/Runtime/DownloadSystem/UnityWebRequest/UnityWebRequestBase.cs b/Assets/YooAsset/Runtime/DownloadSystem/UnityWebRequest/UnityWebRequestBase.cs index 18136bd6..92790b40 100644 --- a/Assets/YooAsset/Runtime/DownloadSystem/UnityWebRequest/UnityWebRequestBase.cs +++ b/Assets/YooAsset/Runtime/DownloadSystem/UnityWebRequest/UnityWebRequestBase.cs @@ -273,7 +273,7 @@ namespace YooAsset } /// - /// 释放资源 + /// 清理 WebRequest 资源 /// private void CleanupWebRequest() {