摘要：在 Python 高并发下载场景下，传统的 requests + threading 方案往往受限于 GIL 和线程切换开销，导致性能瓶颈与资源浪费。今天，我们正式开源 QSDE (Qustellar Smart Download Engine) —— 一款基于纯 asyncio + httpx 构建的工业级下载引擎。它不仅提供 60FPS 的丝滑终端 UI，更拥有原子性文件清理、全链路取消等企业级特性。
🚀 为什么我们需要 QSDE？
作为开发者，在编写爬虫、游戏启动器或系统更新工具时，我们常面临以下痛点：
QSDE (Qustellar Smart Download Engine) 正是为了解决这些问题而生。
⚡ 核心特性：快，且稳
QSDE v1.0.0 基于 Python 3.8+ 的 原生协程 (Native Coroutine) 架构，抛弃了所有阻塞式 I/O。
1. 极致性能 (Pure Asyncio)
利用 httpx 的 HTTP/2 支持与 asyncio 的事件循环，QSDE 可以在单核 CPU 上轻松维持数千个并发连接，将带宽压榨到极限，同时保持极低的内存占用。
2. 60FPS “Zero-Jitter” UI
内置基于 Rich 库定制的 TUI（文本用户界面）。
- 智能列显示：自动识别是“总进度”还是“单文件进度”，分别显示“文件数”与“字节数”。
- 丝滑渲染：采用 30~60Hz 刷新率，进度条流畅顺滑，彻底告别刷屏。
- 错误持久化：即使进度条消失，报错信息也会持久化保留在屏幕上，绝不静默失败。
3. 工业级健壮性 (Industrial Robustness)
这是 QSDE 与普通脚本最大的区别：
- 原子性清理 (Atomic Cleanup)：无论程序因何种原因（断网、报错、强制取消）退出，QSDE 保证绝不残留损坏的临时文件。
- 全链路取消：调用 CancelAll() 可在毫秒级内停止所有网络请求、磁盘写入及哈希计算任务。
- 智能重试：内置指数退避算法（Exponential Backoff），自动应对网络抖动。
4. 双模运行 (Dual-Mode)
- GUI Mode：适合 CLI 工具，开箱即用的漂亮界面。
- API Mode：静默运行，通过回调函数（Callback）传输进度数据，完美适配 PyQt/PySide/Flask 等场景。
📦 快速上手
安装依赖
QSDE 依赖现代化的 Python 异步生态：
pip install httpx aiofiles rich
场景一：极速批量下载 (带 UI)
适合爬虫、资源下载器等场景。
import asyncio
from QSDE import QSDEngine, DownloadTask, HashAlgorithm
async def Main():
# 初始化引擎：开启 UI，设置 8 并发
Engine = QSDEngine(MaxConcurrency=8, EnableUI=True)
# 定义任务列表
Tasks = [
DownloadTask(
Url="https://proof.ovh.net/files/10Mb.dat",
SavePath="downloads/game_asset_1.dat",
# 可选：SHA256 校验，不匹配自动重试
ExpectedHash="…",
HashAlgo=HashAlgorithm.SHA256
),
DownloadTask(
Url="https://proof.ovh.net/files/1Mb.dat",
SavePath="downloads/config.json"
)
]
# 一行代码启动，自动接管所有异常处理
await Engine.StartBatchDownload(Tasks)
if __name__ == "__main__":
asyncio.run(Main())
场景二：集成到 PyQt/PySide (静默模式)
QSDE 提供了优雅的 PascalCase 风格 API，非常符合企业级开发习惯。
async def RunInBackground():
# 关闭内置 UI，进入 API 模式
Engine = QSDEngine(EnableUI=False)
# 动态配置网络环境（支持运行时修改！）
Engine.SetNetworkConfig(
Proxy="http://127.0.0.1:7890",
UserAgent="MyApp/2.0",
TimeOut=60
)
# 挂载回调函数
def OnProgress(Finished, Total):
print(f"当前进度: {Finished}/{Total}")
# 在这里发射 Qt 信号，更新 GUI 进度条
def OnByteProgress(Filename, ChunkSize, TotalBytes):
# 实时网速计算
pass
Engine.SetCallbacks(OnTotalProgress=OnProgress)
# 开始下载
Result = await Engine.StartBatchDownload(Tasks)
print(f"成功: {Result['success']}, 失败: {Result['failed']}")
🧩 设计哲学：PascalCase 与 规范化
QSDE 在代码风格上追求极致的规范。我们全库采用 PascalCase (大驼峰) 命名法，这在 Python 开源界独树一帜，旨在提供更清晰的语义边界，让代码读起来像散文一样优雅。
# 感受一下这优雅的调用风格
Engine.SetRuntimeConfig(MaxConcurrency=32)
Engine.CancelAll()
🔗 开源地址与获取
QSDE v1.0.0 完整源码现已托管至 GitHub，采用宽松的 Apache 2.0 协议开源。无论你是个人学习，还是用于商业项目（如开发游戏启动器），都可以免费使用。
GitHub 仓库地址（包含完整源码、文档与 Demo）：
👉 https://github.com/Qustellar/QSDE
如果您觉得这个项目对您有帮助，请移步 GitHub 点亮一颗 ⭐ Star，这是对开源作者最大的支持！
Qustellar Open Source Team
