Interface IStorage

sdk/storage/src/interface.ts:254–389

 * - 所有方法都应当是幂等或尽可能接近幂等（例如删除不存在的对象不应抛出致命错误），以便业务层重试。
 */
export interface IStorage {
  bucketName: string;

  /**
   * 确保存储桶存在；若不存在则**可能**尝试创建（取决于 vendor 与账号权限）。
   *
   * 返回值说明：
   * - `exists`: 调用前 bucket 是否存在
   * - `created`: 本次调用是否创建了 bucket
   *
   * 建议：
   * - 对于 OSS/COS 等厂商，很多团队更倾向于在控制台/基础设施层面创建 bucket（权限/策略/生命周期等更可控），
   *   应用侧仅做存在性校验即可（bucket 不存在时会抛出底层 SDK 错误）。
   */
  ensureBucket(): Promise<EnsureBucketResult>;

  /**
   * 判断对象是否存在。
   *
   * 返回值说明：
   * - `exists`: 对象是否存在
   */
  checkObjectExists(params: ExistsObjectParams): Promise<ExistsObjectResult>;

  /**
   * 上传对象到 bucket。
   *
   * 典型用法：
   * - 上传文件内容（Buffer/Readable）
   * - 上传文本（string）
   *
   * 注意：
   * - `contentType`/`contentDisposition`/`metadata` 会映射为不同厂商的 HTTP 头或元数据字段，adapter 负责兼容。
   */
  uploadObject(params: UploadObjectParams): Promise<UploadObjectResult>;

  /**
   * 下载对象（以 Node.js `Readable` 流形式返回）。
   *
   * 说明：
   * - 适合大文件流式读取，避免一次性加载到内存。
   * - 调用方负责消费/关闭流（正常读取结束会自动关闭）。
   */
  downloadObject(params: DownloadObjectParams): Promise<DownloadObjectResult>;

  /**
   * 删除单个对象（按 key）。
   *
   * 建议：
   * - 作为幂等操作处理：若对象不存在，最好仍返回成功（由 adapter 决定具体行为）。
   */
  deleteObject(params: DeleteObjectParams): Promise<DeleteObjectResult>;

  /**
   * 根据多个 key 批量删除对象。
   *
   * 注意：
   * - 各厂商对单次批量删除的最大数量限制不同，adapter 可能需要分批处理。