分钟玩转 siwi-download：CLI + Rust 库上手教程

这篇是纯上手教程。从读完你能来看，

• 用 CLI 完成日常所有下载任务
• 把它当 Rust 库嵌进自己的程序
• 处理代理、续传、脚本化等典型场景

一、CLI 篇

痛点的观点是。手动下载经常卡住、重启后要重新写命令，甚至不知道文件到底保存在哪里。

安装

cargo install siwi-download
# 验证
siwi-download --version
# 试运行
siwi-download .

命令全景

siwi-download
Arguments:
URL to download
Options:
-u,--url  URL
-o,--output 
 输出目录
-f,--filename  自定义文件名
-P,--progress 显示进度条
-p,--proxy  HTTP 代理
-v,--verbose 详细日志
-j。--json JSON 格式输出
-h,--help 帮助
-V,--version 版本

URL 可以直接放在位置参数，也可以用 -u/--url 显式指定，两者等价：

siwi-download https://example.com/file.zip
siwi-download -u https://example.com/file.zip

贴心细节：不传参数时CLI 会直接打印完整帮助，不会让你面对 “Error: URL is required”。

五个典型场景

场景1这方面。最朴素的下载

siwi-download https://example.com/file.zip

文件会被下载到当前目录，文件名自动从 URL 提取。

从场景2来看，要进度条

siwi-download https://example.com/big.iso -P

⠁ 50MiB/120MiB

包含已下载字节、总字节、预估剩余时间。

场景3这方面，指定目录和文件名

siwi-download https://example.com/latest/release.tar.gz \
-o ~/Downloads \
-f myapp-v1.tar.gz

• -o: 指定输出目录
• -f: 覆盖文件名

场景4的观点是。通过代理下载

siwi-download https://example.com/file.zip -p http://proxy.example.com:8080

支持 HTTP/HTTPS 代理。老实说，

场景5的观点是，脚本化，要 JSON 输出

siwi-download https://example.com/file.zip -j

标准 JSON，方便 jq 提取关键字段：

{
"url"的观点是，"https://example.com/file.zip","file_name": "file.zip","origin_file_name": "file.zip","storage_path": ".","file_path": "./file.zip","file_size": null,"range_from": null,"download_start_at": null,"download_end_at": null,"download_status": "Complete","head_status": null,"resp_status": null,"time_used": null。"msg": null
}

E.g.,提取方法与耗时：

siwi-download https://example.com/file.zip -j | jq '.file_path,.time_used'

说到续传，主要卖点

只要再跑一次一样命令：

# 第一次下到一半后 Ctrl+C 中断
siwi-download https://example.com/big.iso -o ./dl -P
# 第二次自动从断点继续
siwi-download https://example.com/big.iso -o ./dl -P

实现原理：CLI 会先检查本地文件大小，接下来发送带 "Range: bytes=<已下大小>-" 的请求，只下载剩余部分。

• ✅ 服务器必须支持 Range 请求。其实，
• ⚠️ 如果服务器返回 Status OK 会从头重传。
• ✅ 本地已是完整文件时服务器返回 Status: Range Not Satisfiable ,CLI 会识别并报告 “file exists”。

调试小技巧

Add -v 查看内部日志：

siwi-download https://example.com/file.zip -v

二、Rust 库篇

Pain Point: “想在自己的服务里集成下载，却找不到易用的 async API”。

引入依赖

siwi-download = "*"
tokio = { version = "*"。features = }

最小示例 

use siwi_download::download::{Download,DownloadOptions};async fn main -> siwi_download::error::AnyResult<> {
// 指定存储目录
let downloader = Download::new;downloader.auto_create_storage_path.await?，
// 配置选项
let mut options = DownloadOptions::default;options.set_file_name
.set_show_progress;// 执行下载并获取报告
let report = downloader.download(
说到"https。//example.com/file.zip",options,).await?，println!，Ok)


}



API速查 

`Download` —— 下载器实例 

// 创建实例，传入存储目录
let downloader = Download::new;// 幂等创建目录
downloader.auto_create_storage_path.await?，// 多次复用同一个实例进行不同文件的下载
let report = downloader.download.await?，Pain Point: 重复创建客户端导致资源浪费——这里提供了持久化实例。

`DownloadOptions` —— 配置项 

let mut opts = DownloadOptions::default;怎么说呢，opts.set_file_name
.set_proxy
.set_show_progress;按理说，// 自定义 Header，例如 User‑Agent
use reqwest::header::{HeaderMap。HeaderValue,USER_AGENT};
let mut headers = HeaderMap::new;headers.insert(USER_AGENT,HeaderValue::from_str?)，opts.set_headers;

`DownloadReport` —— 下载结果 

The struct contains exhaustive metadata:

pub struct DownloadReport {
pub url: String,pub file_name: String,pub origin_file_name: String,pub storage_path: String,pub file_path: String,pub file_size: Option,pub range_from: Option,pub download_status: Option。pub time_used: Option,pub msg: Option,}

`DownloadStatus` 枚举解释了每一步状态：

pub enum DownloadStatus {
Create,// 新建文件并开始下发
Append,// 检测到已有部分，执行续传
Complete,// 完整结束
Exists,// 本地已存在完整文件，无需
请求
Error,// 任意错误
}

错误处理 

The library统一使用 anyhow::Result,搭配 `?其实，` 自动向上传递错误信息。

use siwi_download::error::AnyResult;async fn fetch -> AnyResult<> {
let dl = Download::new;dl.download).await?，Ok)
}

If you need finer‑grained info:

let rpt = dl.download.await?，match rpt.download_status {
Some => println!,Some => println!,Some => {
eprintln!，}
_ => {}
}

把报告发送到远端 （解决实际问题：“CI/CD 想把每次下载结果回埋数据库”) 

`DownloadReport::report` 内置 POST JSON 功能：

use reqwest::header::HeaderMap;let mut hdrs = HeaderMap::new;// 如需鉴权 token...
hdrs.insert?)，report.report.await?，


三、实战配方 

配方1 ：批量下载 Bash 脚本 

set -e
URLS=(
再看“https。//example.com/file1.zip”
“https的观点是，//example.com/file2.zip”
“https这方面，//example.com/file3.zip”
)
for url in "${URLS}";do
echo “>> 下载 $url”
siwi‑download "$url" –output ./downloads –progress –json |
jq '{file:.file_name。status:.download_status}'
done

配方2 ：Rust 中批量并发下载 + 错误隔离 

use siwi_download::{
download::{Download,DownloadOptions,DownloadStatus},error::{AnyError,AnyResult},};use futures::future;老实说，async fn main -> AnyResult<> {
let dl = Download::new;dl.auto_create_storage_path.await?，
 let urls = vec!，let futures_vec : Vec<_>= urls.into_iter
.map(|u| {
let d=&dl;async move{
match d.download).await{
Ok=> println!,Err=> eprintln!,}
Ok:的观点是，<,AnyError>)
}
})
.collect;future::join_all.await;Ok)




配方3 ：Dockerfile 中可靠的模型下载 

="">

FROM debian:buster‑slim
COPY --from=builder /usr/local/cargo/bin/siwi‑download /usr/local/bin/

RUN siwi‑download https://example.com/large‑model.bin \
–output /models –filename model.bin –progress



配方 ４ ：CI 里抓数据集 


小结 p="" ​="" ​​="" ​​​​="" ​​​​​​​​​​<="">
小结>

---