Files SDK

Files SDK 是什么？

Files SDK 是一个统一存储 SDK，提供单一且一致的 API，用于与对象和 Blob 存储后端交互。其目标是让您调用相同的高级操作（如上传、下载、列出、删除及相关辅助方法），同时在后台使用不同的提供商。

它通过特定提供商的适配器路由请求。这样可以保持存储工作流的共享部分稳定，同时将提供商差异（如 URL 相关行为或某些边缘情况）在适配器内处理，而无需更改调用位置。

主要功能

• 跨提供商的单一 Files 类：使用单一 API 界面执行常见存储操作（上传、下载、列出、删除、head、exists、copy 及 URL 辅助方法），无需为每个后端编写特定于提供商的代码。
• 构造时通过适配器选择提供商：在实例化 new Files({ adapter: ... }) 时固定适配器，避免“每次调用选择提供商”的模式导致使用混乱。
• 支持 Web 标准输入：接受 File、Blob、ReadableStream、ArrayBuffer 和 string 作为上传输入。
• 在支持 fetch 的环境中运行：设计用于 Node、Bun、Workers 和 Vercel 等环境（页面所述），确保运行时行为一致。
• 通过 files.raw 提供提供商逃生舱：当需要提供商特定功能时，可通过属性（files.raw）访问原生客户端，该属性按适配器类型化。
• 规范化错误处理：错误以统一的 FilesError 类型呈现，跨提供商使用规范化代码，并将原始提供商错误作为原因附加。

如何使用 Files SDK

1. 安装 SDK（以及计划使用的适配器作为对等依赖）：
   • npm install files-sdk
2. 导入 Files 和提供商适配器，然后创建 Files 实例，并为您的存储桶/区域配置适配器（例如 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、copy 及 URL 相关辅助方法（具体 URL 行为可能因提供商而异）。

如何选择存储提供商？

在构造时使用适配器创建 Files 实例（例如 s3({ bucket: ..., region: ... })）。该实例的适配器是固定的。

我可以上传哪些输入类型？

SDK 接受 File、Blob、ReadableStream、ArrayBuffer 和 string 作为上传输入。

当我需要通用 API 未涵盖的功能时会发生什么？

使用逃生舱 files.raw 访问所选适配器暴露的原生客户端。这用于提供商特定功能，如页面所述的项目（例如版本控制、生命周期、ACL、多部分上传），这些功能不属于共享接口。

是否需要安装每个提供商的原生依赖？

不需要。页面将每个提供商的原生 SDK 描述为可选的对等依赖：仅安装您实际使用的提供商的适配器（及其所需的原生包）。如果导入适配器时未安装其对等依赖，Node 将抛出 ERR_MODULE_NOT_FOUND 错误，指示缺少的包。

替代方案

• 特定提供商的存储 SDK（如 S3/GCS/Azure 原生客户端）：这些方案可完整覆盖各提供商功能，但通常需要为每个后端编写不同代码路径，并单独处理通用任务。
• 不支持 Web 标准输入的对象存储抽象层：部分抽象层提供统一接口，但可能不支持相同的 Web 原生输入类型或 fetch 导向的运行时假设。
• 带存储后端选项的服务器端文件上传库：当主要目标是上传处理时很有用，但它们可能无法提供相同的标准化操作（如 head/exists/copy/url 辅助方法）和原生客户端的逃生舱口访问。
• 直接通过 HTTP 集成对象/Blob 端点：如果需要最大控制权，可自行调用提供商的 HTTP API，但需在应用中自行处理列表、签名、错误规范化及提供商差异。