multibucket
异步、后端无关的对象存储门面:业务代码只针对 ObjectStorage trait 编写一次,即可对接任意存储桶。当前内置 七牛云对象存储 Kodo 后端,直连其原始 HTTP API,不引入第三方 SDK。
安装
[]
= "0.1"
= { = "1", = ["rt-multi-thread", "macros"] }
= "1"
需要 Rust 1.70+。TLS 使用 rustls,Windows 上无需 OpenSSL。
构造客户端
use ;
let cfg = new
.region; // z0 / z1 / z2 / na0 / as0 / ea0
let client = new;
私有空间需绑定下载域名,之后所有下载 URL 自动加签名:
let cfg = new
.region
.private_bucket;
内置域名若不适用(私有网关、七牛调整域名、需要直连指定 IP),可逐个覆盖:up_host(..) / rs_host(..) / rsf_host(..) / download_domain(..);use_https(false) 可切回 http。要控制超时与代理,传入自己的 reqwest::Client:
let http = builder
.timeout
.build?;
let client = new.with_http;
上传
use Bytes;
use ;
let meta = client
.put
.await?;
println!;
PutBody 可由 Bytes、Vec<u8>、&'static [u8] 转来;同名 key 直接覆盖写,PutOptions { insert_only: true, .. } 可改为拒绝覆盖。
下载 / 元信息 / 存在 / 删除
let data = client.get.await?; // Bytes
let meta = client.stat.await?;
if client.exists.await?
列举
use ListOptions;
let mut opts = with_limit;
loop
ListOptions 另有 delimiter(支持 /,用于按目录分组)。
有时效的下载 URL
use Duration;
let url = client.presign_get?;
公有桶返回普通 URL,私有桶自动附带下载凭证(同步方法,不发请求)。
大文件:分片与断点续传
便捷调用,内部走分片上传 v2,逐片自动重试:
// part_size = 0 表示使用默认 4 MiB
let meta = client
.put_resumable
.await?;
需要跨进程恢复时,自行持久化 upload_id 与已完成分片:
use ResumeState;
let state = ResumeState ;
client
.put_resumable_resume
.await?;
完全手动编排(并发控制、进度上报等场景):
use CompletedPart;
let mp = client
.initiate_multipart_upload
.await?;
let upload_id = mp.upload_id.to_string; // 立刻持久化,便于中断后恢复
let name1 = mp.upload_part.await?; // 返回 partName,需保存
let name2 = mp.upload_part.await?;
let meta = mp
.complete
.await?;
约束:分片号从 1 开始、最多 10000 片;除最后一片外每片不得小于 1 MiB。中断后可用 client.multipart_upload(key, upload_id) 重新接上已存在的上传任务。
前端直传凭证
use Duration;
let token = client.upload_token?;
把 token 下发给浏览器 / 移动端,让它们直接 POST 到七牛上传域名。
错误处理
所有方法返回 multibucket::Result<T>;后端非 2xx 会收敛为 Error::Api:
use Error;
if let Err = client.stat.await
exists() 已把 612 处理为 false,不会报错。签名依赖本机时间,频繁 401 请先校准系统时钟。
运行示例
端到端示例覆盖上文全部用法(上传 → 元信息 → 下载 → 签名 URL → 列举 → 删除 → 分片 / 手动编排),凭证从环境变量读取:
# Windows PowerShell
$env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
# macOS / Linux
QINIU_ACCESS_KEY=... QINIU_SECRET_KEY=... QINIU_BUCKET=...
许可证
本项目采用 MIT OR Apache-2.0 双许可。