状态查询与幂等设计

状态查询接口

断点续传需要一个查询接口：

GET /uploads/{upload_id}/parts

返回内容不是简单的百分比，而是已完成的分片编号列表。客户端根据这个列表跳过已上传分片，只补传缺失部分。

为什么是「分片列表」而不是「百分比」？因为百分比无法精确告诉客户端「从哪继续」——只有精确到分片编号，断点续传才可靠。

幂等设计

断点续传一定会遇到重复上传同一个分片（网络重试、浏览器重复提交、多页面并发）。服务端不能因为重复请求就报错，而要做幂等处理：

状态机

上传任务的状态机要清晰，且允许从「任意中断点」恢复：

init -> uploading <--> paused/failed（可续传）
         ↓ 所有分片到齐
      merging -> scanning -> available

• 中断 = 状态停在 uploading，分片部分完成。
• 恢复 = 查询已完成分片，继续传缺失部分。
• 合并 = 所有分片到齐后触发。

一致性：不能完全信任客户端

服务端虽然接收客户端的进度报告，但要以服务端实际记录为准：

• 客户端说「我传了 3 号分片」，服务端要能查到 3 号分片确实存在且 hash 一致。
• 数据不一致时，以服务端为准，要求客户端重传。

清理与过期

断点续传也依赖过期机制：

• 任务长期不续传（如 24 小时无新分片），自动标记失效并清理分片。
• 用户主动放弃时，清理接口删除任务和分片。
• 避免「永远传不完」的任务无限占用存储。

下一节看断点续传的产品体验——状态怎么呈现给用户，才是真的「好用」。

上一章节

如何识别同一个上传

下一章节

用户体验与状态流转