# multibucket
一个轻量、异步、**后端无关** 的对象存储门面。业务代码只针对 [`ObjectStorage`] trait 编写一次,即可对接任意存储桶——这正是 “multibucket”(多桶)的命名由来。
首个(也是目前唯一的)后端是 **七牛云对象存储 Kodo**,直接使用其原始 HTTP API 手写实现,因此不引入笨重的第三方 SDK 依赖树。
> 📚 完整文档:[使用指南 `docs/usage.md`](docs/usage.md) | [发布指南 `docs/publishing.md`](docs/publishing.md)
---
## 目录
- [特性](#特性)
- [运行条件](#运行条件)
- [安装](#安装)
- [快速开始](#快速开始)
- [支持的接口](#支持的接口)
- [七牛后端要点](#七牛后端要点)
- [运行示例](#运行示例)
- [发布到 crates.io](#发布到-cratesio)
- [技术架构](#技术架构)
- [许可证](#许可证)
---
## 特性
- **统一 trait**:`put` / `get` / `delete` / `exists` / `stat` / `list` / `presign_get`,一套接口适配多后端。
- **纯手写七牛鉴权**:上传凭证(uploadToken)、私有下载凭证、`QBox` 管理凭证,签名算法严格对齐[七牛官方文档](https://developer.qiniu.com/kodo)。
- **异步 + 纯 Rust TLS**:基于 `tokio` + `reqwest`(`rustls`),在 Windows 上无需 OpenSSL 即可编译。
- **可扩展**:新增 S3 / 阿里云 OSS / 腾讯云 COS 只需在 `src/backends/` 下再实现一次 trait。
## 运行条件
- Rust **1.70+**(edition 2021)。安装见 <https://rustup.rs>。
- 一个七牛账号:开通 [对象存储 Kodo](https://portal.qiniu.com/kodo/bucket),创建 **空间(bucket)**,获取 **AccessKey / SecretKey**。
- 若使用私有空间下载,需为空间绑定一个 **已备案的加速域名**。
## 安装
在本 crate 目录下示例已在 `Cargo.toml` 就绪。若作为依赖引入其它项目:
```toml
[dependencies]
multibucket = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
bytes = "1"
```
## 快速开始
```rust
use std::time::Duration;
use bytes::Bytes;
use multibucket::{
ObjectStorage, PutBody, PutOptions,
backends::qiniu::{QiniuClient, QiniuConfig, Region},
};
#[tokio::main]
async fn main() -> multibucket::Result<()> {
// 1. 构造客户端
let cfg = QiniuConfig::new("ACCESS_KEY", "SECRET_KEY", "my-bucket")
.region(Region::Z0);
let client = QiniuClient::new(cfg);
// 2. 上传
client
.put("a/b.txt", PutBody::from(Bytes::from("hello")), &PutOptions::default())
.await?;
// 3. 下载 / 元信息 / 判断存在 / 删除
let data = client.get("a/b.txt").await?;
let meta = client.stat("a/b.txt").await?;
assert!(client.exists("a/b.txt").await?);
client.delete("a/b.txt").await?;
// 4. 生成有时效的下载 URL(私有空间会自动加签名 token)
let url = client.presign_get("a/b.txt", Duration::from_secs(600))?;
println!("{url}");
Ok(())
}
```
完整可运行示例见 [`examples/qiniu_basic.rs`](examples/qiniu_basic.rs)。
## 支持的接口
| `put(key, body, opts)` | 上传(覆盖写) | 表单上传 `POST up*.qiniup.com/` |
| `get(key)` | 下载到内存 | `GET` 下载域名(私有自动签名) |
| `stat(key)` | 读取对象元信息 | `POST rs*.qiniucs.com/stat/...`(QBox) |
| `exists(key)` | 是否存在 | 基于 `stat`,`612` 视为不存在 |
| `delete(key)` | 删除对象 | `POST rs*.qiniucs.com/delete/...`(QBox) |
| `list(prefix, opts)` | 分页列举 | `GET rsf*.qiniucs.com/list`(QBox) |
| `presign_get(key, expires)` | 生成带时效的下载 URL | 下载凭证签名 |
| `put_resumable(key, body, part_size, opts)` | 分片 / 断点续传上传 | 分片上传 v2(initiate / uploadPart / mkfile,`UpToken` 鉴权) |
| `upload_token(key, ttl)` | 生成前端直传凭证(七牛特有) | uploadToken |
## 七牛后端要点
- **区域与域名**:`Region` 枚举内置 z0/z1/z2/na0/as0/ea0 的上传、管理、列举、下载默认域名。如七牛调整域名或需走私有网关,可在 `QiniuConfig` 上用 `up_host / rs_host / rsf_host` 覆盖。权威域名可用 `GET https://uc.qiniup.com/query?ak=<AK>&bucket=<Bucket>` 查询。
- **私有空间**:`QiniuConfig::private_bucket("download.example.com")` 会开启下载 URL 签名。
- **分片 / 断点续传**:`put_resumable(..)` 走分片上传 v2(默认分片 4 MiB,单片最小 1 MiB,最多 10000 片,逐片自动重试 3 次);需要跨进程恢复时,用 `initiate_multipart_upload` / `upload_part` / `complete` 手动编排并持久化 `upload_id` 与已完成分片(`ResumeState`)。
- **时钟同步**:`deadline` / `e` 均基于本机 Unix 时间,频繁 401 请先校准系统时钟。
- **putTime**:七牛返回的是 100 纳秒单位时间戳,本 crate 已转换为 `SystemTime`。
## 运行示例
```sh
# Windows PowerShell
$env:QINIU_ACCESS_KEY="..."; $env:QINIU_SECRET_KEY="..."; $env:QINIU_BUCKET="..."
cargo run --example qiniu_basic
```
```sh
# macOS / Linux
QINIU_ACCESS_KEY=... QINIU_SECRET_KEY=... QINIU_BUCKET=... cargo run --example qiniu_basic
```
## 发布到 crates.io
发布流程、`Cargo.toml` 元数据要求、版本号规则、`cargo owner` 管理等详见
**[`docs/publishing.md`](docs/publishing.md)**。速览:
```sh
# 1. 登录(token 会写入 ~/.cargo/credentials)
cargo login <crates.io API Token>
# 2. 自查包内容与编译
cargo package --list
cargo test
# 3. 先演练(只读),再正式发布
cargo publish --dry-run
cargo publish
# 4. 打标签
git tag v0.1.0 && git push --tags
```
## 技术架构
```
multibucket/
├── Cargo.toml
├── README.md
├── LICENSE-MIT / LICENSE-APACHE
├── docs/
│ ├── usage.md # 使用指南
│ └── publishing.md # 发布指南
├── examples/
│ └── qiniu_basic.rs
└── src/
├── lib.rs # crate 门面与文档
├── error.rs # Error / Result
├── types.rs # ObjectMetadata / PutBody / PutOptions / ListOutcome
├── storage.rs # ObjectStorage trait + ListOptions
└── backends/
├── mod.rs
└── qiniu/
├── mod.rs # QiniuClient(实现 ObjectStorage)
├── auth.rs # Mac 签名:uploadToken / 私有下载 / QBox 管理凭证
├── config.rs # QiniuConfig(Builder)
└── region.rs # Region 与各服务域名
```
依赖:`tokio`(异步运行时)、`reqwest`(`rustls`)、`hmac`+`sha1`(签名)、`base64`、`percent-encoding`、`serde`/`serde_json`、`bytes`、`async-trait`、`thiserror`。
## 许可证
本项目采用 **MIT OR Apache-2.0** 双许可。