Files SDK

Files SDK 是什麼？

Files SDK 是一套統一儲存 SDK，提供單一且一致的 API，用來操作物件與 Blob 儲存後端。目標是讓您使用相同的上層操作，例如上傳、下載、列出、刪除以及相關輔助方法，同時在幕後切換不同的供應商。

它透過特定供應商的轉接器來路由請求，讓儲存流程的共用部分保持穩定，而供應商之間的差異（例如 URL 相關行為或特定邊緣案例）則由轉接器處理，不需修改呼叫端程式碼。

主要功能

• 單一 Files 類別支援多種供應商：使用同一套 API 進行常見儲存操作（上傳、下載、列出、刪除、head、exists、複製以及 URL 輔助方法），無需為每個後端撰寫供應商專屬程式碼。
• 建構時選擇轉接器：在建立 new Files({ adapter: ... }) 時固定轉接器，避免「每次呼叫再選擇供應商」的模式造成使用上的混亂。
• 支援 Web 標準輸入：上傳時可接受 File、Blob、ReadableStream、ArrayBuffer 與 string 作為輸入。
• 可在支援 fetch 的環境執行：設計用於 Node、Bun、Workers 與 Vercel 等環境，提供一致的執行行為。
• 透過 files.raw 存取原生功能：當需要供應商專屬功能時，可透過 files.raw 屬性存取原生客戶端，並依轉接器進行型別定義。
• 統一錯誤處理：錯誤會以單一 FilesError 型別呈現，並附上跨供應商的統一代碼，原始供應商錯誤則作為原因附加。

如何使用 Files SDK

1. 安裝 SDK（以及您計劃使用的轉接器，作為 peer dependency）：
   • npm install files-sdk
2. 匯入 Files 與供應商轉接器，然後建立 Files 實例，並為您的 bucket/region 配置轉接器（例如 S3）。
3. 在實例上呼叫共用方法，例如：
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. 使用 files.raw：當需要存取共用 API 以外的供應商專屬功能時使用。

以下為頁面上的最小範例：

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

await files.upload("hello.txt", "world");
const file = await files.download("hello.txt");
const meta = await files.head("hello.txt");
const items = await files.list();
await files.delete("hello.txt");

使用情境

• 建立可切換供應商的儲存層：從單一後端（例如 S3 相容儲存）開始，之後可切換到其他轉接器，無需重寫應用程式的上傳/下載/列出/刪除邏輯。
• 在後端程式碼中一致地處理瀏覽器式檔案輸入：當伺服器接收到 Web 標準檔案物件時，使用 SDK 支援的輸入類型（File、Blob、ReadableStream、ArrayBuffer、string）。
• 依前綴組織上傳並在應用層管理物件生命週期：使用 list({ prefix }) 和 delete(key) 模式，在物件儲存上實作應用程式管理的集合或「資料夾」。
• 整合依 fetch 可用性部署的環境：將程式碼部署到 Node、Bun、Workers 或 Vercel，同時使用相同的 API 呼叫與輸入。
• 使用統一錯誤處理重試與錯誤管理：捕捉 FilesError 並取得統一代碼，當需要供應商專屬細節時可檢視原始原因。

常見問題

Files SDK 標準化了哪些儲存操作？

SDK 跨轉接器標準化共用方法介面，包括上傳、下載、刪除、列出、head、exists、複製以及 URL 相關輔助方法（具體 URL 行為會依供應商而異）。

如何選擇儲存供應商？

在建構時建立帶有轉接器的 Files 實例（例如 s3({ bucket: ..., region: ... })）。該轉接器會固定於此實例。

我可以上傳哪些輸入類型？

SDK 接受 File、Blob、ReadableStream、ArrayBuffer 與 string 作為上傳輸入。

當我需要共用 API 以外的功能時會發生什麼？

使用 files.raw 存取所選轉接器所暴露的原生客戶端。這是用於供應商專屬功能，例如頁面所提及的版本控制、生命週期、ACL、multipart 等，這些功能並不屬於共用介面。

是否需要安裝每個供應商的原生依賴？

不需要。頁面將每個供應商的原生 SDK 描述為可選的 peer dependency：僅安裝您實際使用的供應商轉接器（及其所需的原生套件）。若匯入轉接器但未安裝其 peer dependency，Node 會拋出 ERR_MODULE_NOT_FOUND 錯誤，表示缺少該套件。

替代方案

• 各供應商專屬儲存 SDK（例如 S3/GCS/Azure 原生用戶端）：這些方案提供完整的供應商支援，但通常需要為每個後端撰寫不同的程式碼路徑，並分別處理常見任務。
• 不支援 Web 標準輸入的物件儲存抽象層：部分抽象層提供統一介面，但可能不支援相同的 Web 原生輸入類型或以 fetch 為導向的執行環境假設。
• 具備儲存後端選項的伺服器端檔案上傳函式庫：當主要目標是處理上傳時很有用，但它們可能無法提供相同的標準化操作（head/exists/copy/url 輔助函式），以及存取原生用戶端的轉接功能。
• 直接透過 HTTP 整合物件/Blob 端點：若需要最大控制權，可自行呼叫供應商的 HTTP API，但需自行處理清單、簽章、錯誤正規化以及供應商差異。