supabase_storage

简介

封装 Supabase Storage 的 API，提供文件上传、下载、删除、列举等功能。

组件接口

类

StorageFileApi

文件操作 API 封装

内部持有 StorageClient 客户端

负责将用户的文件操作请求转换为底层的 HTTP 指令

成员变量

变量名	类型	初始值	须初始化	描述
client	StorageClient	nil	可选	StorageClient 客户端
bucket_id	string	nil	可选	存储桶 ID

成员方法

函数原型	函数作用
FileUploadResponse upload_or_update_file(string relative_path, mixed data, bool update, FileOptions option = nil)	上传或更新文件，操作对象为存储桶
FileUploadResponse update_file(string relative_path, mixed data, FileOptions option = nil)	更新文件，将替换指定路径下的现有文件
FileUploadResponse upload_file(string relative_path, mixed data, FileOptions option = nil)	上传文件到指定路径的现有存储桶
MessageResponse move_file(string sourceKey, string destinationKey)	移动文件，将现有文件移动到同一存储桶中的新路径
SignedUrlResponse create_signed_url(string file_path, int expires_in = 60)	创建签名 URL，使用签名 URL 可以在固定时间内共享文件
SignedUrlResponse create_signed_upload_url(string file_path)	创建用于上传文件的签名 URL，使用签名 URL 可以将文件直接上传到存储桶
UploadToSignedUrlResponse upload_to_signed_url(string file_path, mixed file_body)	将文件上传到已签名的 URL
SignedUrlResponse get_public_url(string file_path, UrlOptions url_options)	获取公共存储桶中资源的 URL
array remove_file(array paths)	从现有存储桶中删除文件
array list_files(string query_path, FileSearchOptions options)	列出现有存储桶中的文件
mixed download_file(string file_path, UrlOptions url_options, int content_type)	从现有存储桶下载文件
string build_url_with_option(string url, UrlOptions options)	基于当前 URL 和选项构建一个新 URL

HttpTransPort

TransPort

底层传输层：负责 HTTP 协议细节、URL 拼接、认证头注入、错误处理

成员变量

变量名	类型	初始值	须初始化	描述
base_url	string	nil	可选
default_headers	map	nil	可选

成员方法

函数原型	函数作用
mixed request(string method, string path, mixed body = nil, map headers = nil, int content_type = "Content_Type.json")	执行底层 HTTP 请求

StorageClient

业务逻辑层：面向用户的 API 封装

负责将用户的业务请求转换为底层的 HTTP 指令

内部持有 HttpTransPort 实例来完成实际的网络通信

成员变量

变量名	类型	初始值	须初始化	描述
trans_port	HttpTransPort	nil	可选	底层传输层实例

成员方法

函数原型	函数作用
mixed request(string method, string path, mixed body = nil, map headers = nil, int content_type = 2)	发起 HTTP 请求
StorageFileApi from(string id)	切换上下文到指定的存储桶，准备进行文件操作
array list_buckets()	列出所有存储桶
map get_bucket(string id)	获取指定存储桶详情
map create_bucket(string id, BucketOptions options)	创建存储桶
map update_bucket(string id, BucketOptions options)	更新存储桶
map empty_bucket(string id)	清空存储桶
map delete_bucket(string id)	删除存储桶

MessageResponse

消息响应类型

用于返回操作结果消息

成员变量

变量名	类型	初始值	须初始化	描述
message	string	nil	可选	消息内容

成员方法

函数原型	函数作用

BucketResponseError

存储桶响应错误类型

用于表示存储桶操作失败时的错误信息

成员变量

变量名	类型	初始值	须初始化	描述
error	string	nil	可选	错误类型
message	string	nil	可选	错误消息
status_code	int	0	可选	HTTP 状态码

成员方法

函数原型	函数作用

Bucket

存储桶信息

表示 Supabase Storage 中的存储桶对象

成员变量

变量名	类型	初始值	须初始化	描述
id	string	nil	可选	存储桶唯一标识符
name	string	nil	可选	存储桶名称
owner	string	nil	可选	存储桶所有者
is_public	string	nil	可选	是否为公开存储桶（注意：API 可能返回 boolean，需要转换）
file_size_limit	int	0	可选	文件大小限制（字节），0 表示无限制
allowed_mime_types	array	nil	可选	允许的 MIME 类型列表，nil 表示允许所有类型
created_at	string	nil	可选	创建时间
updated_at	string	nil	可选	更新时间

成员方法

函数原型	函数作用

BucketOptions

存储桶配置选项

用于创建或更新存储桶时的配置参数

成员变量

变量名	类型	初始值	须初始化	描述
is_public	bool	false	可选	存储桶的可见性，true 为公开，false 为私有，默认为私有
file_size_limit	string	nil	可选	存储桶中允许的最大文件大小（以字节为单位），nil 表示无限制
allowed_mime_types	array	nil	可选	允许的 MIME 类型列表，nil 表示允许所有 MIME 类型

成员方法

函数原型	函数作用

SortBy

排序选项

用于指定文件列表的排序方式

成员变量

变量名	类型	初始值	须初始化	描述
column	string	nil	可选	排序列名，如 "name"、"created_at"、"updated_at" 等
order	string	nil	可选	排序顺序，"asc" 为升序，"desc" 为降序

成员方法

函数原型	函数作用

FileUploadResponse

文件上传响应

表示文件上传操作的结果

成员变量

变量名	类型	初始值	须初始化	描述
Key	string	nil	可选	文件路径/键名
Message	string	nil	可选	响应消息
Data	array	nil	可选	响应数据数组
Code	string	nil	可选	响应代码
Error	string	nil	可选	错误信息（如果存在）

成员方法

函数原型	函数作用

SignedUrlResponse

签名 URL 响应

包含用于访问或上传文件的签名 URL

成员变量

变量名	类型	初始值	须初始化	描述
signed_url	string	nil	可选	签名 URL，用于在固定时间内访问或上传文件

成员方法

函数原型	函数作用

FileSearchOptions

文件搜索选项

用于配置文件列表查询的参数

成员变量

变量名	类型	初始值	须初始化	描述
limit	int	0	可选	返回文件数量限制，0 表示使用默认值
offset	int	0	可选	分页偏移量，跳过前 N 条记录
sort_by_options	SortBy	nil	可选	排序选项，nil 表示不排序

成员方法

函数原型	函数作用

FileObject

文件对象

表示存储桶中的文件信息

成员变量

变量名	类型	初始值	须初始化	描述
name	string	nil	可选	文件名
bucket_id	string	nil	可选	所属存储桶 ID
owner	string	nil	可选	文件所有者
id	string	nil	可选	文件唯一标识符
updated_at	string	nil	可选	更新时间
created_at	string	nil	可选	创建时间
last_accessed_at	string	nil	可选	最后访问时间
metadata	mixed	nil	可选	文件元数据（JSON 对象）
buckets	Bucket	nil	可选	所属存储桶信息

成员方法

函数原型	函数作用

ListFileRequestBody

列出文件请求体

用于构建文件列表查询的请求参数

成员变量

变量名	类型	初始值	须初始化	描述
limit	int	0	可选	返回文件数量限制
offset	int	0	可选	分页偏移量
sort_by_options	SortBy	nil	可选	排序选项
prefix	string	nil	可选	文件路径前缀，用于过滤特定路径下的文件

成员方法

函数原型	函数作用

TransformOptions

图片转换选项

用于配置图片的尺寸、格式、质量等转换参数

成员变量

变量名	类型	初始值	须初始化	描述
width	int	0	可选	图片宽度（像素），0 表示不限制
height	int	0	可选	图片高度（像素），0 表示不限制
resize	string	nil	可选	调整大小模式："cover"（覆盖）、"contain"（包含）、"fill"（填充）
quality	int	80	可选	图片质量（1-100），默认 80
format	string	"origin"	可选	图片格式："origin"（原始）、"webp"、"avif" 等

成员方法

函数原型	函数作用

UrlOptions

URL 选项

用于配置文件 URL 的转换和下载选项

成员变量

变量名	类型	初始值	须初始化	描述
transform	TransformOptions	nil	可选	图片转换选项，nil 表示不转换
download	bool	false	可选	是否作为下载链接，true 时会在响应头中设置 Content-Disposition

成员方法

函数原型	函数作用

SignedUploadUrlResponse

签名上传 URL 响应

包含用于上传文件的签名 URL

成员变量

变量名	类型	初始值	须初始化	描述
url	string	nil	可选	签名上传 URL

成员方法

函数原型	函数作用

UploadToSignedUrlResponse

上传到签名 URL 的响应

表示通过签名 URL 上传文件后的结果

成员变量

变量名	类型	初始值	须初始化	描述
Key	string	nil	可选	上传后的文件路径/键名

成员方法

函数原型	函数作用

FileOptions

文件选项

用于配置文件上传时的各种选项

成员变量

变量名	类型	初始值	须初始化	描述
cache_control	string	"3600"	可选	资源在浏览器和 Supabase CDN 中缓存的秒数，在 `Cache-Control: max-age=<seconds>` 标头中设置，默认 3600 秒
content_type	string	"text/plain;charset=UTF-8"	可选	`Content-Type` 标头值，如果 fileBody 不是 Blob/File/FormData，应指定此值，默认 `text/plain;charset=UTF-8`
duplex	string	nil	可选	双工流选项，用于启用或禁用双工流（允许在同一流中同时读取和写入数据），nil 表示不设置
upsert	bool	nil	可选	是否覆盖已存在的文件，true 时覆盖，false 时抛出错误，nil 时不传递该选项（使用服务器默认值）

成员方法

函数原型	函数作用

样例

public void pkg_sample()
{
    string supabase_url = config.opt("supabase_url");
    string supabase_service_key = config.opt("supabase_service_key");
    string storage_url = config.opt("storage_url");

    // 初始化存储客户端（默认使用 service key）
    StorageClient client = StorageClient.new(supabase_url + storage_url, supabase_service_key);

    // ------------------------ 桶操作相关的测试代码 ------------------------

    // 测试列出所有存储桶
    array bucket_list_result = client.list_buckets();
    printf("Buckets: %O\n", bucket_list_result);

    // 测试根据 ID 获取存储桶
    map bucket_fetch_result = client.get_bucket("test2");
    printf("Bucket: %O\n", bucket_fetch_result);

    // 测试创建存储桶，访问模式为公开
    BucketOptions bucket_create_options = BucketOptions.new(true);
    map bucket_create_result = client.create_bucket("test2", bucket_create_options);
    printf("Bucket: %O\n", bucket_create_result);

    // 测试更新存储桶，访问模式为私有
    BucketOptions bucket_update_options = BucketOptions.new(false);
    map bucket_update_result = client.update_bucket("test2", bucket_update_options);
    printf("Bucket: %O\n", bucket_update_result);
    map bucket_update_fetch = client.get_bucket("test2");
    printf("Bucket: %O\n", bucket_update_fetch);

    // 测试清空存储桶
    map bucket_empty_result = client.empty_bucket("test2");
    printf("Empty bucket: %O\n", bucket_empty_result);

    // 测试删除存储桶
    map bucket_delete_result = client.delete_bucket("test2");
    printf("Delete bucket: %O\n", bucket_delete_result);

    // ------------------------ 上传文件（桶的内部操作）相关的测试代码 ------------------------

    // 读取测试文件内容
    string content = (string)(file.read_all("/src/data/dummy.txt", "b"));

    // 测试上传文件,选择对test1桶进行操作
    StorageFileApi file_api = client.from("test1");
    FileUploadResponse upload_result = file_api.upload_file("444.txt", content);
    printf("Upload file: %O\n", upload_result);

    // 测试更新文件
    FileUploadResponse update_result = file_api.update_file("222.txt", content);
    printf("Update file: %O\n", update_result);

    // 测试移动文件
    MessageResponse move_result = file_api.move_file("hhh.txt", "ttt/test2.txt");
    printf("Move file: %O\n", move_result);

    // 测试删除文件
    array delete_result = file_api.remove_file(["444.txt", "333.txt"]);
    printf("Delete file: %O\n", delete_result);

    // 测试创建签名 URL
    SignedUrlResponse signed_url_result = file_api.create_signed_url("ttt/test2.txt", 300);
    printf("Signed URL: %O\n", signed_url_result);

    // 测试获取公共 URL
    UrlOptions public_url_options = UrlOptions.new(TransformOptions.new());
    map public_url_result = file_api.get_public_url("test.txt", public_url_options);
    printf("Public URL: %O\n", public_url_result);

    // 测试列出文件
    SortBy sort_by = SortBy.new();
    FileSearchOptions list_options = FileSearchOptions.new(sort_by, 0, 1);
    array list_result = file_api.list_files("", list_options);
    printf("List files: %O\n", list_result);

    // 测试创建上传签名 URL 并上传文件
    SignedUrlResponse upload_signed_result = file_api.create_signed_upload_url("hhh.txt");
    printf("Signed URL: %O\n", upload_signed_result);
    UploadToSignedUrlResponse upload_to_signed_result = file_api.upload_to_signed_url(
        upload_signed_result.signed_url,
        content
    );
    printf("Upload to signed URL: %O\n", upload_to_signed_result);

    // 测试下载文件
    UrlOptions download_options = UrlOptions.new(TransformOptions.new());
    mixed download_result = file_api.download_file("4.jpg", download_options, 0);
    file fw = file.open("4.jpg", "w");
    fw.write(download_result);
    fw.close();
}

简介​

组件接口​

类​

StorageFileApi​

成员变量​

成员方法​

HttpTransPort​

成员变量​

成员方法​

StorageClient​

成员变量​

成员方法​

MessageResponse​

成员变量​

成员方法​

BucketResponseError​

成员变量​

成员方法​

Bucket​

成员变量​

成员方法​

BucketOptions​

成员变量​

成员方法​

SortBy​

成员变量​

成员方法​

FileUploadResponse​

成员变量​

成员方法​

SignedUrlResponse​

成员变量​

成员方法​

FileSearchOptions​

成员变量​

成员方法​

FileObject​

成员变量​

成员方法​

ListFileRequestBody​

成员变量​

成员方法​

TransformOptions​

成员变量​

成员方法​

UrlOptions​

成员变量​

成员方法​

SignedUploadUrlResponse​

成员变量​

成员方法​

UploadToSignedUrlResponse​

成员变量​

成员方法​

FileOptions​

成员变量​

成员方法​

样例​

简介

组件接口

类

StorageFileApi

成员变量

成员方法

HttpTransPort

成员变量

成员方法

StorageClient

成员变量

成员方法

MessageResponse

成员变量

成员方法

BucketResponseError

成员变量

成员方法

Bucket

成员变量

成员方法

BucketOptions

成员变量

成员方法

SortBy

成员变量

成员方法

FileUploadResponse

成员变量

成员方法

SignedUrlResponse

成员变量

成员方法

FileSearchOptions

成员变量

成员方法

FileObject

成员变量

成员方法

ListFileRequestBody

成员变量

成员方法

TransformOptions

成员变量

成员方法

UrlOptions

成员变量

成员方法

SignedUploadUrlResponse

成员变量

成员方法

UploadToSignedUrlResponse

成员变量

成员方法

FileOptions

成员变量

成员方法

样例