适用场景与密钥模型

直传= 客户端进程直接持有 OSS 的 AccessKeyId / AccessKeySecret，自己在本地做 OSS V4 签名。

• ✅ 适合：程序跑在你完全掌控的可信服务器 / 后端上。
• 手机 App、桌面客户端、浏览器 WASM 等不可信环境——那些场景请改用 《阿里云 OSS 预签名实战》，密钥永远留在后端。说起来，

. 使用者痛点一览 — 安全与权限管理

• "我担心将 AccessKey 写在代码里会被泄露": 将凭证暴露给客户端会导致未授权访问或滥用。
• "如何限制每个文件只能被上传一次": 对同一 UploadId 的重复使用可能导致数据覆盖或碎片化。
• "我不想手动生成签名。只能让后端完成": direct 模式需要自行实现 V4 签名，门槛较高。

. 加依赖

rusty-cat = { version = ".",features = }
tokio = { version = ""。features = }

. 使用者痛点二览 — 开发复杂度与依赖冲突

• "我不确定哪种特性组合才能支持 multipart": 必须开启 `aliyun‑oss‑direct` 并配合 `tokio` 的多线程运行时。
• "编译报错，缺少某些宏或异步特性": 确认 Cargo.toml 中正确指定 `features` 与 `tokio` 的 `rt-multi-thread`。
• "升级 Rust 后出现 API 不兼容": 每次 Rust 或 crate 升级都需检查 API 文档。话说回来，

. 上传：完整可运行程序

把顶部常量换成你自己的。cargo run 即可。怎么说呢，.with_max_parts_in_flight 就是「单文件 个分片并发上传」的开关。

use std::sync::Arc;use rusty_cat::aliyun_oss_direct::AliOssDirectUpload;use rusty_cat::api::{FileTransferRecord。MeowClient,MeowConfig,UploadPounceBuilder};#
async fn main -> Result<, Box {
let client = MeowClient::new);// Bucket、AccessKeyId、AccessKeySecret、地域
let protocol =
AliOssDirectUpload::new;let task = UploadPounceBuilder::new(
"big-object.bin",// 展示用文件名
"./big-object.bin",// 本地文件方法
/* 分片大小 */ *。// MiB
)
.with_url
.with_breakpoint_upload) // 协议对象必须放进 Arc
.with_max_parts_in_flight // 单文件最多 个并发
.with_max_chunk_retries // 每片失败最多再重试 次
.build?，let outcome = client
.enqueue_and_wait(task,|r: FileTransferRecord| {
println!(
"上传进度 {:.}% 状态 {:?}",r.progress *,r.status
);})
.await，;println，;client.close.await?，// 必须调用
Ok)
}

内部发生了什么？——OSS Multipart 流程拆解

S D K 会自动帮你走完整个 OSS Multipart 流程：

• 每片的分片号由偏移量推导。重传幂等，所以乱序 / 并发是安全的；话说回来，
• OSS 最多 。SDK 会提前校验，
• 分片大小建议 ,峰值内存 ≈ N × 分片大小 。

. 下载：两种方式 —— 用直连 vs 签署 URL

从方式一来看，用 direct 下载协议

M 注意 direct 下载协议只能串行 ) 对它无效。

use std::sync::Arc;use rusty_cat::aliyun_oss_direct::AliOssDirectDownload;use rusty_cat::api::{DownloadPounceBuilder。MeowClient,MeowConfig};#
async fn main -> Result<, Box {
let client = MeowClient::new);说起来，let protocol =
AliOssDirectDownload::new;let task = DownloadPounceBuilder::<&str>::new(
"obj.bin","./downloads/obj.bin",/* 分块大小 */ *。/* url */ "https://my-bucket.oss-cn-beijing.aliyuncs.com/test/obj.bin"",)
.with_breakpoint_download)
.build;按理说，client.enqueue_and_wait.await?，client.close.await?，Ok)
}

方式二的观点是。签名 GET URL + 默认下载器

⚠️ 要想 **并发**下载，你一定不能挂 provider 下载协议！只需让后端签署一个 **预签名 GET URL**，接下来交给内置默认下载器即可。

use rusty_cat::{
至于api:。{DownloadPounceBuilder,MeowClient,MeowConfig},};// presigned_get_url：后端签出的 OSS 预签名 GET URL
// total_size：文件总字节数
#
async fn main -> Result<, Box {
let presigned_get_url =
说到"https，//my-bucket.oss-cn-beijing.aliyuncs.com/test/obj.bin?Expires=...&Signature=...";let total_size: u64 = /* …*/，话说回来，let client = MeowClient::::new;let task =
DownloadPounceBuilder::<&str>::new(
"obj.bin","./downloads/obj.bin",/* 分块大小 */ *,presigned_get_url。)
.with_total_size // 告诉 SDK 总大小，跳过 HEAD
.with_max_parts_in_flight // 个 Range GET 并发
//.without_breakpoint_download;// 保持默认 StandardRangeDownload
.build;client.enqueue_and_wait(task,|r| println!* ))
.await，;client.close.await?，Ok)
}

这就是「上传下载不对称」的关键点：**上传要挂 provider 协议才并发**，**下载要不挂 provider 协议才并发**。下载时若使用 provider，则只能串行；若使用预签名 URL，则可实现 Range GET 并行。其实，完整规则见 《分片并发下载教程》；签署细节请参阅 《阿里云 OSS 预签名实战》。

. 使用者痛点三览 — 性能瓶颈与资源消耗

• “我发现单文件分块数过多导致 CPU 占用飙高” → 调整
  和

  参数即可。”​.

. 断点续传与取消 —— 数据安全与成本控制

• “我的进程崩溃了但已经上传了一部分” → SDK 自动通过
  接管已有会话，并校验每个期望分片是否已落地。建议持久化 UploadId `)，便于手动终止孤儿会话。

C++ Code snippet omitted for brevity…