跳至主要内容

Requester

重要 注意 提醒

Coding Style wiki​

Requester 是基於 UniTask + UnityWebRequest 的資源請求器，支援 AudioClip、Texture2D、Sprite、byte[]、string 的網路/檔案請求，並可搭配 ARC 或 LRU 快取 (以 URL 為 Key)，具有超時 (預設 180 秒) 與取消 (CancellationTokenSource) 機制；失敗時透過 errorAction 回傳 ErrorInfo。

命名空間OxGKit.Utilities.Requester
類型public class Requester、public struct ErrorInfo
原始碼Requester.cs
using Cysharp.Threading.Tasks;
using OxGKit.Utilities.Requester;

注意 本頁列出的 static 方法皆透過內部懶漢式單例運作；各方法皆有對應 Self 前綴的實例方法 (例如 SelfRequestTexture2D)，可自行 new Requester() 建立獨立快取範圍的實例使用 (詳見靜態調用與實例調用)。

快速上手​

using Cysharp.Threading.Tasks;
using OxGKit.Utilities.Requester;
using System.Threading;
using UnityEngine;

// 啟動時初始各資源類型的快取容量 (ARC 或 LRU 擇一)
Requester.InitARCCacheCapacityForAudio(20);
Requester.InitARCCacheCapacityForTexture2d(60);
Requester.InitARCCacheCapacityForText(100);

// 請求 Texture2D (cached = true 時以 URL 為 Key 快取)
Texture2D t2d = await Requester.RequestTexture2D
(
    url,
    (texture) => Debug.Log($"Loaded: {texture.width}x{texture.height}"),
    (error) => Debug.Log($"Error: {error.message}")
);

// 請求 AudioClip (需指定正確的 AudioType)
AudioClip clip = await Requester.RequestAudio(url, AudioType.OGGVORBIS);

// 搭配 CancellationTokenSource 綁定生命週期
var cts = new CancellationTokenSource();
string text = await Requester.RequestText(url, null, null, cts);
// 物件銷毀時取消請求
cts.Cancel();

通用規則​

靜態調用與實例調用 (Self 系列)​

Requester 的每個靜態方法皆有對應 Self 前綴的實例方法 (RequestTexture2D ↔ SelfRequestTexture2D、InitLRUCacheCapacityForText ↔ SelfInitLRUCacheCapacityForText 等)，參數與行為完全相同，差別只在快取範圍：

  • 靜態調用：透過內部單例運作，全專案共用同一組全域快取，一般情境使用這個即可。
  • 實例調用 (new 方式)：自行 new Requester() 建立實例後調用 Self* 方法，該實例擁有完全獨立的快取範圍 (容量設定、清除、釋放皆互不影響)，適合特定功能需要自管快取生命週期的情境 (例如聊天室頭像、活動頁圖片，離場時整批釋放)。
using OxGKit.Utilities.Requester;

// 靜態調用 (全域共用快取)
var tex = await Requester.RequestTexture2D(url);

// 實例調用 (new 方式，建立獨立快取範圍)
var chatRequester = new Requester();

// 為該實例初始獨立的 LRU 快取容量
chatRequester.SelfInitLRUCacheCapacityForTexture2d(30);

// 以 Self 方法發出請求 (快取只進這個實例)
var avatar = await chatRequester.SelfRequestTexture2D(avatarUrl);

// 離場時整批釋放該實例的快取 (不影響全域快取)
chatRequester.SelfRelease();

提醒 本頁後續章節以靜態簽名列出，所有方法皆有同名的 Self 實例版本，直接加上 Self 前綴即可對應調用。

快取機制​

  • 快取以 URL 為 Key，命中時直接回傳並觸發 successAction (不再發出請求)。
  • 每種資源類型 (Audio / Texture2d / Text) 只允許一種快取策略：初始 ARC 會清除並停用 LRU，反之亦然。
  • 未初始任何快取時，cached 參數不會有作用 (不做快取)。
  • RequestBytes 不提供快取 (每次皆重新請求)。

提醒 RequestSprite 底層快取的是 Texture2D，Sprite 本身每次呼叫都會重新 Sprite.Create，頻繁使用時建議自行持有建立出的 Sprite。

注意 重新呼叫 Init 系列方法會清除並重建該類型的快取 (已快取項目將被淘汰處理)，建議於啟動時初始一次即可。

超時與取消​

  • 未傳入 cts：內部會自行建立 CancellationTokenSource 並套用 timeoutSeconds (未指定時預設 180 秒) 作為超時保護。
  • 傳入自訂 cts：timeoutSeconds 不會生效，完全由呼叫端控制取消時機。

重要 持有請求結果的物件銷毀時，請記得 cts.Cancel() 取消尚未完成的請求，避免回呼觸發在已釋放的物件上。

錯誤處理​

  • URL 為 null 或空字串、請求失敗 (ConnectionError / ProtocolError / DataProcessingError) 或發生例外時，會透過 errorAction 回傳 ErrorInfo，且回傳值為 null (default)。
  • 錯誤同時會透過 OxGKit.LoggingSystem 輸出 (日誌器名稱 OxGKit.Utilities.Logger)。

ErrorInfo​

public struct ErrorInfo
{
    public string url;
    public string message;
    public Exception exception;
}

請求失敗時透過 errorAction 回傳的錯誤資訊。

成員說明
url請求的 URL (URL 缺失時為 null)。
message錯誤訊息 (UnityWebRequest.error)。
exception例外資訊 (非例外錯誤時為 null)。

請求方法​

方法總覽​

方法 (static)Self 實例版本 (new 方式)說明
RequestAudioSelfRequestAudio請求 AudioClip (可快取)。
RequestTexture2DSelfRequestTexture2D請求 Texture2D (可快取)。
RequestSpriteSelfRequestSprite請求並建立 Sprite (底層快取 Texture2D)。
RequestBytesSelfRequestBytes請求檔案 byte[] (不快取)。
RequestTextSelfRequestText請求文字內容 (可快取)。

RequestAudio​

public static async UniTask<AudioClip> RequestAudio(string url, AudioType audioType = AudioType.MPEG, Action<AudioClip> successAction = null, Action<ErrorInfo> errorAction = null, CancellationTokenSource cts = null, bool cached = true, int? timeoutSeconds = null)

請求 AudioClip (串流下載)，需依音訊檔案格式指定正確的 audioType (預設 AudioType.MPEG)。

AudioClip clip = await Requester.RequestAudio
(
    "https://example.com/audio.ogg",
    AudioType.OGGVORBIS,
    (audioClip) => audioSource.PlayOneShot(audioClip),
    (error) => Debug.Log($"Error: {error.message}")
);

注意 audioType 與檔案格式不符會導致解碼失敗；WebGL 平台對串流音訊有限制，請自行驗證支援格式。

RequestTexture2D​

public static async UniTask<Texture2D> RequestTexture2D(string url, Action<Texture2D> successAction = null, Action<ErrorInfo> errorAction = null, CancellationTokenSource cts = null, bool cached = true, int? timeoutSeconds = null)

請求 Texture2D，cached = true 且已初始快取時，同 URL 的第二次請求將直接回傳快取。

Texture2D t2d = await Requester.RequestTexture2D
(
    "https://example.com/image.png",
    (texture) => rawImage.texture = texture
);

RequestSprite​

public static async UniTask<Sprite> RequestSprite(string url, Action<Sprite> successAction = null, Action<ErrorInfo> errorAction = null, Vector2 position = default, Vector2 pivot = default, float pixelPerUnit = 100, uint extrude = 0, SpriteMeshType meshType = SpriteMeshType.FullRect, CancellationTokenSource cts = null, bool cached = true, int? timeoutSeconds = null)

請求 Texture2D 後以 Sprite.Create 建立 Sprite 回傳；pivot 未指定 (為 Vector2.zero) 時自動套用中心點 (0.5f, 0.5f)。

Sprite sprite = await Requester.RequestSprite
(
    "https://example.com/icon.png",
    (sp) => image.sprite = sp
);

RequestBytes​

public static async UniTask<byte[]> RequestBytes(string url, Action<byte[]> successAction = null, Action<ErrorInfo> errorAction = null, CancellationTokenSource cts = null, int? timeoutSeconds = null)

請求檔案的 byte[] 內容，不提供快取 (無 cached 參數)。

byte[] bytes = await Requester.RequestBytes("https://example.com/file.bin");

RequestText​

public static async UniTask<string> RequestText(string url, Action<string> successAction = null, Action<ErrorInfo> errorAction = null, CancellationTokenSource cts = null, bool cached = true, int? timeoutSeconds = null)

請求文字內容 (string)，cached = true 且已初始快取時以 URL 為 Key 快取。

string json = await Requester.RequestText("https://example.com/config.json");

快取管理​

方法總覽​

方法 (static)Self 實例版本 (new 方式)說明
InitARCCacheCapacityFor...SelfInitARCCacheCapacityFor...初始指定資源類型的 ARC 快取容量 (會停用該類型的 LRU 快取)。
InitLRUCacheCapacityFor...SelfInitLRUCacheCapacityFor...初始指定資源類型的 LRU 快取容量 (會停用該類型的 ARC 快取)。
RemoveFromARCCacheFor...SelfRemoveFromARCCacheFor...從指定資源類型的 ARC 快取中移除 URL。
RemoveFromLRUCacheFor...SelfRemoveFromLRUCacheFor...從指定資源類型的 LRU 快取中移除 URL。
ClearARCCacheCapacityFor...SelfClearARCCacheCapacityFor...清空指定資源類型的 ARC 快取。
ClearLRUCacheCapacityFor...SelfClearLRUCacheCapacityFor...清空指定資源類型的 LRU 快取。
AutoRemoveFromCachesSelfAutoRemoveFromCaches搜尋所有快取並移除指定 URL。
ClearAllCachesSelfClearAllCaches清空所有快取。
ReleaseSelfRelease清空並釋放所有快取容器。

InitARCCacheCapacityFor...​

public static void InitARCCacheCapacityForAudio(int capacity = 20)

public static void InitARCCacheCapacityForTexture2d(int capacity = 60)

public static void InitARCCacheCapacityForText(int capacity = 100)

初始指定資源類型的 ARC 快取容量；同類型僅允許一種快取策略，呼叫後會清除並停用該類型的 LRU 快取。

Requester.InitARCCacheCapacityForTexture2d(60);

InitLRUCacheCapacityFor...​

public static void InitLRUCacheCapacityForAudio(int capacity = 20)

public static void InitLRUCacheCapacityForTexture2d(int capacity = 60)

public static void InitLRUCacheCapacityForText(int capacity = 80)

初始指定資源類型的 LRU 快取容量；呼叫後會清除並停用該類型的 ARC 快取。

Requester.InitLRUCacheCapacityForTexture2d(60);

RemoveFromARCCacheFor...​

public static bool RemoveFromARCCacheForAudio(string url)

public static bool RemoveFromARCCacheForTexture2d(string url)

public static bool RemoveFromARCCacheForText(string url)

從指定資源類型的 ARC 快取中移除 URL 項目，移除成功回傳 true。

RemoveFromLRUCacheFor...​

public static bool RemoveFromLRUCacheForAudio(string url)

public static bool RemoveFromLRUCacheForTexture2d(string url)

public static bool RemoveFromLRUCacheForText(string url)

從指定資源類型的 LRU 快取中移除 URL 項目，移除成功回傳 true。

ClearARCCacheCapacityFor...​

public static void ClearARCCacheCapacityForAudio()

public static void ClearARCCacheCapacityForTexture2d()

public static void ClearARCCacheCapacityForText()

清空指定資源類型的 ARC 快取 (逐一觸發淘汰處理)。

ClearLRUCacheCapacityFor...​

public static void ClearLRUCacheCapacityForAudio()

public static void ClearLRUCacheCapacityForTexture2d()

public static void ClearLRUCacheCapacityForText()

清空指定資源類型的 LRU 快取 (逐一觸發淘汰處理)。

AutoRemoveFromCaches​

public static bool AutoRemoveFromCaches(string url)

搜尋所有快取 (ARC 與 LRU 的 Audio / Texture2d / Text)，找到指定 URL 即移除並回傳 true。

Requester.AutoRemoveFromCaches(url);

ClearAllCaches​

public static void ClearAllCaches()

清空所有已初始的快取 (ARC 與 LRU 的 Audio / Texture2d / Text)。

Release​

public static void Release()

清空所有快取並釋放快取容器 (歸 null)，需再次呼叫 Init 系列方法才會恢復快取功能。

提醒 被快取的 Unity 物件 (AudioClip / Texture2D) 於淘汰或移除時會自動 Destroy (詳見 Cacher)；未快取 (cached = false) 的物件不再使用時，需自行 Destroy 釋放記憶體。