1. 从一次“上传失败”说起为什么我们离不开分片上传讲分片上传之前先聊聊我去年经手的一个真实项目。当时要给客户做一个视频管理后台素材动辄几个GB最初图省事直接用了普通的POST表单上传。测试环境里百兆宽带下传一个2GB的文件看着进度条一点点爬结果到83%的时候网络闪断整个文件作废用户得从头再来。客户的运维当场脸就黑了。这个场景估计不少人都遇到过。文件越大单次上传的失败率越高重试成本也越高。根本原因在于传统上传把整个文件当作一个不可分割的整体服务端必须等完整字节流到达才能落盘。网络抖动、代理超时、服务器重启、客户端程序被杀任何一个环节出问题前面传输的数据就全部作废。分片上传的核心思路很简单粗暴把大文件切成若干个小块逐块上传服务端收齐后合并成原始文件。每一片都是独立传输单元失败只需要重传失败的那一片而不是整个文件。但分片上传真正落地时远比“切块上传”这四个字复杂。分片之间的时序关系、并发控制、合并校验、断点续传每一步都藏着坑。这篇文章我想从时序图的视角把分片上传的完整过程、关键节点、状态流转都拆开讲一遍把我在项目里踩过的坑和最终沉淀下来的方案一起放出来。2. 为什么要分片从传输模型看单文件上传的七个致命问题先回到最底层的问题我们为什么需要分片很多人觉得“文件大才需要分片”这个说法对但不完整。分片解决的从来不只是“大”而是“大文件传输过程中的不确定性”。2.1 网络请求的先天限制HTTP协议本身并不限制请求体的大小但实际链路里到处都是限制。Nginx默认client_max_body_size是1MBTomcat的maxPostSize默认2MB云厂商的SLB和API网关也各有各的体量上限。不是说调大不行而是调大之后会引入新的问题内存占用、超时配置、负载均衡器的连接时长限制。我见过最典型的一个事故生产环境的Nginx配置了client_max_body_size 500m结果客户端上传大文件时请求在网关层被截断Nginx返回了413错误。排查了半天最后发现是前置的云负载均衡器单请求最大只支持100MB。这种链路里的隐形墙不把文件切小根本绕不过去。2.2 失败重试的代价随文件大小线性上升网络传输的失败率虽然低但不是零。假设单次请求失败的概率是0.1%一个100MB的文件用一次请求传完失败率也就是0.1%但如果分成100片每片1MB要做完整个上传需要100次请求全部成功概率是(1-0.001)^100 ≈ 90.5%整体失败率反而接近10%。看到这个数字可能有人会疑惑那分片不是增加了失败概率吗关键差异在于失败后的恢复成本。单请求模式下失败一次意味着100MB全部重传分片模式下失败一片只重传1MB。数学期望算下来分片的平均传输量远小于不分片。打个比方搬家时把全部家当装进一个集装箱路上翻车一次就得重新收拾分片相当于把家当装进100个小箱子翻车了只损失其中一箱其余箱子照常到达。这是分片最核心的价值——缩短重试范围降低平均传输成本。2.3 单请求无法享受的并发红利普通上传是串行的请求发出等待响应再发下一个。如果文件只有几MB串行上传和并发上传的区别可能只有几百毫秒但GB级别的文件串行上传的耗时简直无法忍受。分片之后每个分片的请求天然独立可以并行发起。客户端可以根据带宽状况开N个并发上传通道把网络带宽吃到接近极限。对于内网传输、跨地域传输这些长肥链路场景并发的收益尤其明显。我在一个跨洋传输项目里把分片并发从1路调到8路传输时间直接缩短了约5倍。2.4 时图视角下的本质从“一个请求”到“一组请求”传统上传的时序图只有三条线客户端发起、服务端响应、完成。而分片上传的时序图里客户端、服务端、存储系统之间的交互是一张网状结构——初始化、逐片上传、并发推进、合并请求、轮询状态、失败重试、断点恢复每个节点都有自己的生命周期。这也是为什么我总跟团队强调设计分片上传方案先画时序图再写代码。时序图能逼你把每个角色的职责、每条消息的触发条件、每个状态的前提和后续都理清楚。时序图画不出来或者画出来逻辑矛盾代码写一半一定会被返工。3. 分片上传完整流程一张时序图背后的六个关键阶段下面这张时序图描述的是我在生产环境里实际落地过的一套方案。它涵盖了一个分片上传从初始化到最终确认的完整生命周期。请重点看每个交互的前置条件和触发逻辑这是时序图的灵魂所在。客户端 服务端 存储系统 | | | | 1. 初始化上传请求 | | | (文件名/大小/分片数) | | |-----------------------------| | | | 2. 创建上传会话(返回 uploadId) | | ---------------------------| | | | | | 3. 逐片上传(可并发) | | | (分片序号 分片内容) | | |-----------------------------| 4. 校验分片序号/大小 | | |--------------------------------| | | 5. 存储分片记录元数据 | | |--------------------------------| | ---------------------------| | | | | | 6. 完成上传请求 | | | (uploadId 分片清单) | | |-----------------------------| 7. 按序号排列并合并分片 | | |--------------------------------| | | 8. 返回最终文件地址/校验值 | | ---------------------------| | | | |下面按阶段逐个拆解。3.1 阶段一初始化上传会话建立“契约”时序图里第一条交互就是客户端向服务端发起“初始化上传请求”。这条消息很关键它定义了后续所有分片的“契约”。请求里通常要携带这些信息原始文件名用于合并后的文件命名文件总大小服务端校验累计分片体量的依据分片大小客户端规划好的分片策略服务端需要校验其合法性分片总数上传完成的判定依据之一可选的MD5或文件指纹用于最终合并后的完整性校验服务端收到请求后会做两件事一是校验元数据合法性和配额二是创建一个“上传会话”核心是一个唯一的uploadId并在缓存或数据库里记录该会话的所有状态信息。这个uploadId是整个分片上传流程的“会话凭证”。后续所有分片上传请求都需要携带它。有了它即使客户端断网、重启、甚至换一台设备只要拿到同一个uploadId就能恢复之前的传输进度。我在设计时给初始化接口加了一个幂等键客户端生成一个UUID作为requestId服务端在缓存里做去重。这样即使客户端因网络超时重试初始化请求也不会创建出多个孤儿会话。这个是踩过坑之后补上的后面会细讲。3.2 阶段二分片规则的设计与确认客户端在初始化请求里报上自己的分片策略服务端确认通过后才进入传输阶段。分片大小和分片数量的选择直接影响传输效率和失败重试成本。我常用的一个经验标准是文件小于 100MB分片大小 1MB ~ 2MB文件在 100MB ~ 1GB 之间分片大小 5MB ~ 10MB文件在 1GB ~ 10GB 之间分片大小 10MB ~ 50MB前端的约束是浏览器环境里读取文件分片需要Blob.slice()这个操作本身很快没有太强的性能瓶颈。后端的约束是内存缓冲区和临时文件的规划分片太小会导致请求数过多占用大量HTTP连接分片太大会失去分片的意义。还有一个容易忽略的点最后一个分片通常小于标称分片大小服务端一定要允许这种“不齐整”。很多新手写的校验逻辑是“每片必须等于分片大小”结果最后一片永远校验失败。3.3 阶段三分片并行上传与滑动窗口时序图中间最热闹的一段是“逐片上传可并发”的部分。客户端拿到uploadId后把文件切成N片然后开M个并发通道按窗口机制推进。窗口机制要解决的现实问题是如果一次性把100个分片全部并发发出去服务端可能扛不住也可能因为网络拥塞造成过多的分片重传。合理的做法是维护一个“滑动窗口”初始只允许4到6个分片在途每成功一个从待发送队列里补一个进来。窗口大小可以根据上传速度动态调整带宽充裕时放宽丢包率升高时收紧。每个分片的上传请求必须携带uploadId会话标识partNumber分片序号从1开始连续递增分片内容本身可选的分片MD5服务端可以单片校验提前发现坏片服务端收到分片后先校验uploadId对应的会话是否存在、partNumber是否在合法区间内、分片大小是否和partNumber匹配然后才写入临时存储。等所有分片都上传完成、客户端调用“完成上传”接口后服务端再按序号拼接。3.4 阶段四完成上传与分片合并的边界条件所有分片上传成功后客户端发一条“完成上传”请求携带uploadId和完整的partNumber列表。服务端收到这条消息才决定启动合并流程。这个设计是刻意的服务端不主动猜测上传是否完成一切以客户端的“完成信号”为准。因为分片可能是乱序到达的服务端不能因为“收到了80%的分片”就以为快完成了。只有客户端自己知道它是否把所有分片都发完了。合并过程需要注意两点必须按partNumber排序后再拼接而不是按存储顺序直接合并。多个并发请求到达存储系统时碎片顺序是乱的直接拼接会毁掉文件。合并可能耗时较长尤其是TB级别的文件。因此“完成上传”接口不能是同步等待合并结束的简单阻塞接口最好是异步任务状态查询的模式。我在项目中采用的方案是完成上传接口返回一个taskId客户端拿着taskId轮询合并任务的执行状态比如pending、running、success、failed。时序图里体现为“轮询状态”这条虚线交互。虽然多了一个接口但避免了HTTP连接被长时间占用也方便做重试和审计。3.5 阶段五合并后的完整性校验合并完成后服务端需要给客户端一个交代。这个“交代”不只是一条成功响应而是一个可验证的文件指纹。具体做法是合并完成后计算整个文件的MD5或者SHA-256然后和客户端初始化时上报的原始文件指纹比对。如果一致说明合并过程没有发生数据丢失或字节序错乱如果不一致说明合并有问题或者某个分片本身就是坏的需要标记分片并触发重传。这里有个性能细节计算一个2GB文件的MD5需要几十秒甚至更长如果放在同步链路里会卡很久。我在生产方案里把校验放在合并任务内部和拼接步骤做成一个流水线结果通过taskId轮询获取。客户端拿到结果后可以再拉一遍文件做二次校验不过这个属于可选的双保险实际业务里很少做。3.6 阶段六会话清理与临时文件回收一个不怎么被提及但极其重要的阶段上传会话的生命周期管理。用户上传到一半放弃、客户端崩溃、网络长期断开——这些情况都会让服务端残留未完成的上传会话和一堆半成品分片。如果不做清理机制临时存储会被吃光。我一般会为每个上传会话设置过期时间默认24小时客户端通过心跳或续传请求不断续期。超过过期时间仍未完成合并的会话会被后台定时任务扫描并删除同时清理对应的临时分片文件。这里需要小心一个边界不要在用户还在传输时误删会话。扫描时机的判断要基于最后的活跃时间而不是创建时间。比如一个2GB的文件传输了20小时每次都有分片成功活跃时间一直在刷新这种会话就不能算过期。4. 关键参数与策略选型分片大小、并发数、超时该如何定网络上讲分片上传的教程不少但大多只讲流程不讲参数怎么定。参数选型决定了你的方案在实战中是稳如老狗还是频繁重试。这一节把我沉淀下来的参数计算方法和选型逻辑摊开讲。4.1 分片大小的上下限约束分片大小不是拍脑袋定的它受四个因素约束网络层MTU与TCP窗口单个TCP连接的吞吐量和带宽延迟积相关过小的分片比如256KB在长肥链路上无法充分利用单连接带宽过大的分片比如100MB又会导致重传代价过高。客户端内存浏览器端File.slice只负责逻辑切割真正把分片读入内存的是FormData或fetch/axios的body。如果同时开8路并发每路分片大小为20MB那么客户端内存峰值就要预留160MB这在低配移动设备上会直接OOM。服务端缓冲区如果服务端采用“收齐所有分片后合并”的策略那么临时文件存储总量就是文件总大小分片大小只是影响单分片写入粒度。请求数量分片越小请求越多HTTP握手、鉴权、日志的开销越大。1GB文件若用1MB分片就是1024个请求每个请求都有至少两次网络往返纯开销就很可观。我曾经测过一组数据千兆内网环境文件大小2GB分片大小从1MB增加到8MB总耗时先降后升。1MB时分片开销太大8MB时并发窗口内的网络利用率下降最优值落在4MB左右。如果你不想做精细化调优以5MB起步进行验证是比较稳的选择。4.2 并发数怎么算别拍脑袋开8路并发数不是固定值理论基础是“BDP估计”即带宽延迟积。公式很简单并发窗口大小 ≈ (带宽MB/s × RTT毫秒) / (8 × 分片大小MB)举例客户端上行带宽50MbpsRTT 20ms换算成字节带宽6.25MB/sRTT 0.02s。BDP约0.125MB 128KB。如果分片大小为5MB那么单连接带宽利用率其实很低因为一个RTT内最多塞进128KB5MB的分片要等40个RTT才能发完。这种情况下并发数要开到足够大才能填满带宽。更实用的做法是动态反馈调整客户端维护一个“在途分片数”每成功一片就计算平均单片耗时如果单片耗时持续下降说明带宽未被占满可以适当增加窗口如果单片耗时上升说明网络拥堵立即缩减窗口。很多优秀的开源库比如Tus、UpChunk走的都是这个思路。我给一个最常用的初始值场景初始分片大小初始并发数说明移动端弱网512KB ~ 1MB2单分片越小弱网重试代价越低浏览器普通宽带2MB ~ 8MB3 ~ 5平衡请求数和并行度桌面端内网/专线8MB ~ 16MB8 ~ 16充分利用带宽分片不宜过大跨地域长传5MB ~ 10MB4 ~ 8大分片降低RTT开销适度并发4.3 超时与重试处理“假失败”分片上传中最让人抓狂的现象是分片明明已经传到服务端了但客户端因为没有及时收到响应判定为超时然后重传同一片。如果服务端没有做幂等处理就会收到两片相同的分片合并时出现数据重复。应对方案有两层服务端分片幂等以uploadId partNumber为唯一键如果该分片已存在直接返回成功不重复存储。时序图上体现为“重复请求合并”的一个分支判断。客户端超时分级连接超时比如5秒直接重试读取超时比如30秒先主动查询该分片是否已到达服务端再决定是否重传。这个查询接口很轻量能避免大量无谓的重传流量。我强烈建议实现服务端分片幂等因为它的成本极低、收益极高。简单场景下甚至不需要数据库用内存缓存存储“已上传分片的partNumber集合”即可。5. 服务端落盘与合并临时文件管理和并发合并的细节服务端的实现风格决定了整套方案的稳定性。很多教程把重点放在客户端忽略服务端的设计结果就是“三分钟搭出demo上线第一周炸出五个bug”。这里把我认为最重要的几个服务端细节讲透。5.1 临时文件的组织方式目录名里带uploadId为了避免不同会话之间的分片文件互相干扰我会为每个上传会话单独建一个临时目录目录名直接用uploadId。结构类似/upload_tmp/7f2c4b09-6e1a-4c3f-8b7d-2f1a9e5c3d77/ part_001 part_002 part_003 ...uploadId使用UUID时随机性有保证目录冲突的概率基本为零。如果文件数特别多分片数上百万可以用两层目录结构比如按uploadId的前两位再分一层避免单目录下文件数过多导致文件系统性能退化。还有一点容易被忽略临时目录和最终存储目录建议放在同一个文件系统下。合并操作的本质是“按顺序拼接”如果跨文件系统拼接过程就会变成“读取写入”IO开销翻倍同一文件系统下可以做rename或硬链接成本极低。5.2 合并的并发控制一次只有一个合并线程合并操作最怕重复执行。如果“完成上传”请求被客户端重试服务端可能同时启动两个合并任务读取同一批分片文件产生竞争和脏数据。我的方案是引入一个task_lock以uploadId为粒度做互斥。具体实现可以用数据库行锁也可以用Redis的SETNX命令获取到锁的任务才能执行合并其他任务进入等待或直接返回“当前任务已存在”。合并的伪代码逻辑大致如下def merge_chunks(upload_id, part_numbers): if lock_exists(upload_id): return merge already running set_lock(upload_id, ttl10min) try: with open(final_path, wb) as fp: for part_number in sorted(part_numbers): chunk_path temp_dir / fpart_{part_number} fp.write(read_file(chunk_path)) os.remove(chunk_path) # 边读边清理减少临时空间占用 # 计算最终文件MD5与预期值比对 status success if verify() else failed finally: release_lock(upload_id)这里有一个容易被忽略的性能点逐片写入比“把所有分片拼接成一个大临时文件再整体移动”更省空间。因为分片上传过程中临时文件已经占用了近乎完整文件的空间合并时如果先生成一个大临时文件再写最终文件临时空间峰值会是文件大小的两倍。边读边写、边清理分片总空间峰值只比文件大小多一个分片大小。5.3 合并失败怎么办重试策略与部分失败恢复合并从来不是100%成功的。磁盘空间不足、分片文件被误删、读写出错都可能导致合并失败。我设计的合并任务包含一个“失败原因”字段失败后允许客户端重新发起“完成上传”请求服务端会先清理不完整的合并产出物然后重新启动合并。如果某些分片确实缺失响应里会明确告诉客户端“缺失分片序号列表”客户端根据这个列表精确补传而不是全量重传。这个设计既需要服务端诚实——它不能假装合并成功也需要客户端配合——它能处理“部分缺失”的响应并精准补片。很多项目在这个环节省事结果就是数据静默损坏只能靠更加愚蠢的全量重传兜底。6. 断点续传与状态记录客户端如何快速回到中断现场分片上传的一大优势是天然支持断点续传。但这个优势不会自己兑现客户端必须主动管理“哪些分片已成功上传”的状态。6.1 客户端状态维护的两种方式最简单的方式用本地状态文件或localStorage记录。每成功一片就持久化一个partNumber。下次启动上传时先读取这些成功记录跳过已成功的分片只传剩余部分。LocalStorage的容量大约是5MB记录上万个分片序号会爆掉。更稳的方案是维护一个Bitmap或位数组比如文件有1024片用一个1024位的数组来表示每位对应一个分片序号1表示已成功。这个位数组可以序列化成一个小字符串存localStorage毫无压力。更复杂的方案是服务端状态查询。客户端发起续传时调用“查询分片状态”接口服务端返回该uploadId下已收到的分片序号列表。这种方式不需要客户端本地持久化任何数据换浏览器、换设备都能续传但会增加服务端存储负担和查询压力。我倾向两种方式结合本地状态用于即时恢复服务端状态用于跨会话兜底。它们的同步时机是每次分片上传成功并更新本地状态后服务端的临时文件就是事实来源。6.2 断点续传的时序图视角断点续传在时序图上表现为客户端重新发起“初始化上传请求”时携带上次的uploadId服务端返回“该会话已存在及其分片状态”客户端根据返回的已上传分片集合只发送缺口部分。客户端 服务端 | 恢复上传请求(uploadId) | |------------------------------| | 返回已上传分片列表 | |------------------------------| | 并发上传缺失分片 | |-----------------------------|这里有一个坑极易踩上传会话过期导致续传失败。比如用户上传到一半去开会回来时已超过会话过期时间服务端已经把临时文件清理了。此时客户端如果傻傻地传缺失分片一定会失败。解决思路是在客户端发起续传前先判断服务端返回的会话状态如果会话存在且未过期进入增量续传流程如果会话不存在或已过期重新初始化上传会话从零开始如果部分分片已存在但会话接近过期客户端必须主动触发“续期接口”把过期时间向后推6.3 秒传当分片上传遇到文件指纹讲分片上传就不能不提“秒传”它本质上是断点续传的另一种表现形式。所谓秒传是指客户端在初始化上传请求时携带文件的MD5或更稳妥的SHA-256服务端先在已有的文件库中查一遍如果发现内容完全一致的文件直接返回“上传成功”和指向该文件的地址不再进行任何实际传输。秒传的实现逻辑并不复杂但有个技术细节需要注意对大文件计算MD5本身就要读一遍整个文件耗时可能很长。一个2GB的文件本地机械硬盘的读取速度可能只有150MB/s计算MD5需要十几秒用户在这段时间里看着进度条不动体验并不好。我常用的优化做法是“先采样后计算”对于超过特定大小比如100MB的文件不计算全文MD5而是取头、中、尾各1MB做采样加上文件大小组成一个“弱指纹”先做一轮预筛选。如果弱指纹唯一不触发秒传如果弱指纹匹配到候选文件再计算全文指纹做最终确认。这样既减少了大多数场景下的计算开销又不会降低秒传的准确性。7. 时序图之外兼容性与异常场景的防御性设计分片上传方案真正上线前我还会花大量时间处理“意外情况”。这部分内容往往是最被低估的但也是线上故障的主要来源。7.1 HTTP断连与浏览器刷新的处理浏览器环境里最头疼的问题是用户上传过程中直接刷新页面或者点击了“取消上传”浏览器会把所有在途的XMLHttpRequest或fetch请求立刻中止。如果服务端没有对这种情况做特殊处理已经传完的分片都留在临时目录里但客户端再也无法“恢复现场”——因为会话还在客户端的本地状态却丢失了。较好的实践是前端在上传页面销毁前把当前uploadId和成功分片列表写进localStorage。页面重新加载时检测到存在未完成的上传记录自动提示用户恢复上传。这是一个看似简单但非常影响体验的功能做没做用户感知特别明显。7.2 分片顺序错乱与重复片的防御并发上传天然导致分片乱序到达。服务端绝不能假设“先到的分片序号小、后到的分片序号大”否则合并出的文件必然是坏的。防御手段前面提过这里再集中强调一遍分片存储阶段每个分片独立保存文件名包含partNumber合并阶段强制按partNumber排序后再拼接同一个partNumber如果收到多次以最后一次为准或直接忽略重复请求7.3 服务端会话过期的动态续期会话过期策略不能是死板的“创建时间24小时”因为一个耗时很长的上传会突破这个限制。最稳妥的做法是每次分片上传成功后更新会话的“最后活跃时间”过期判定基于最后活跃时间。定时清理任务扫描时判断条件如下会话过期时间 max(会话创建时间 最大生存期, 最后活跃时间 空闲容忍期)举例最大生存期48小时空闲容忍期24小时。如果一个会话创建后不断有分片上传只要两次上传间隔不超过24小时就不会被清理。如果用户上传10小时才传了一半然后凌晨去睡觉也不至于立刻被删——但第二天回来还没继续服务端就有权清理了。7.4 资源配额与流量控制为了防意外我还会给每个用户加一个“在途临时文件总大小”的配额。因为一个用户可能同时有多个上传会话在进行如果都不限制临时盘会被塞满影响平台上所有用户的上传任务。配额限制写在初始化上传会话的接口里如果当前用户所有在途会话的原始文件大小总和超过阈值就拒绝创建新会话返回明确的错误码。这种限制一般不会误伤正常用户但能在异常请求量的冲击下保住整个服务的稳定性。8. 时序图工具选型UML时序图、云服务自带监测图还是自定义图最后聊一聊“时序图”本身。前面讲了半天分片上传状态流转但实际工作中我们画时序图用的什么工具、什么规范也值得单独说一嘴。8.1 规格各异的“时序图”严格来讲UML时序图是描述对象之间消息传递时间顺序的标准图型强调“多个角色之间在时间轴上的交互顺序”。它的元素包括生命线Lifeline、激活条Activation、消息箭头Message、返回箭头Return Message、可选片段Combined Fragment等。但实际项目里很多人说的“时序图”可能不只是UML时序图还包含泳道图把不同系统的处理过程按纵向泳道排列、活动图描述流程分支甚至交互流程图。以“i2c时序图”为例那片领域里的时序图更多是指物理电平在时钟线SCL和数据线SDA上的波形变化和UML时序图是两个完全不同的概念。本文讨论的分片上传时序图属于前一种即UML时序图。对于分片上传这种多角色、多分支、有并发交互的场景我强烈建议用标准UML时序图来画因为它的“生命线”和“消息顺序”表达能力刚好匹配我们的需求。如果你用泳道图画分片上传各角色上下游关系虽然直观但并发消息的先后关系很难表达清楚。8.2 工具选型与建模思路常用工具我试过几款简单列一下工具适用场景优点缺点PlantUML代码内嵌、自动化文档纯文本、可版本管理、支持大部分UML语法图形样式偏简陋复杂布局需要调参数MermaidMarkdown生态、快速草图语法轻量渲染即时复杂分支和嵌套片段的表达能力偏弱draw.io / diagrams.net正式交付、对外产图界面友好支持手绘布局可导出高清图手工调整耗时无法版本化管理云监控平台的链路图生产环境性能分析自动生成的调用链真实数据驱动无法精准表达设计态的分支与异常场景我的建议是迭代用PlantUML或Mermaid交付用draw.io或Visio精修。设计讨论期不需要好看的图要的是快速改、快速看、快速发现逻辑漏洞上线交付和方案评审时再花时间把图打磨精致。8.3 分片上传时序图建模时的两个实用技巧第一个技巧是给每个角色添加“状态校验”分支。比如客户端发“初始化上传请求”时服务端要先校验是否已有同uploadId的会话如果有走恢复流程如果没有走创建流程。把这个分支画在时序图上代码写的时候就不会漏掉它。第二个技巧是不要画“绝对理想路径”。完整的时序图除了包含主流程还要包含异常分支超时重试、分片缺失补传、会话过期重新初始化、合并失败重试。画完这些分支后你才能对系统边界有一个全局认知。我经常在评审会上看到两种极端一种是一张图表达了所有分支复杂到没人看得懂另一种是只画Happy Path看似完美代码实现时发现边界情况全都漏了。合理的标准是主路径用一条清晰的时间线画出来异常分支用独立的小图或文字标注拆出去既保持主图的可读性又不丢失边界逻辑。9. 生产环境里的真问题稳定运行三个月后的事实检验方案上线只是起点。真正有价值的经验来自线上运行几个月后遇到的真实问题。选几个典型案例分享出来比任何理论都更有说服力。案例一并发合并导致文件头部字节错乱上线早期我们曾遇到过一个诡异问题约连分片上传的文件偶发性地在若干KB处出现乱码。排查发现合并任务启动时读取分片文件同一分片文件被另一个还未释放的连接写入尾部数据两个进程对同一文件并发读写导致合并结果中出现极短但致命的字节错位。修复方案合并前先确认所有分片对应的HTTP请求已经全部结束同时在存储层引入“分片文件写入完成标记”只有标记存在才允许读取合并。从源头上杜绝并发读写同一个分片文件。案例二Nginx的body缓冲导致内存暴涨另一个典型案例是Nginx接收上传请求时的缓冲区设置。默认client_body_buffer_size较小大分片上传时Nginx会把请求体先暂存到临时文件但如果在配置里把缓冲区调得过大并发分片上传时Nginx worker进程内存直接被打满。这个问题的本质是“分片大小和服务端代理层配置不匹配”。后来我们把分片大小控制在4MB以内并设置合理的client_body_buffer_size内存问题随即消失。案例三用户上传到一半办公网络切换导致大量重传移动办公用户经常在Wi-Fi和4G之间切换IP地址变化导致部分HTTP请求被重置。我们统计过一次网络切换平均会造成约8%的在途分片失败。但由于分片上传方案本身的重试机制这些失败分片都只重传一次就成功了用户甚至完全没有感知到网络切换的发生。这正是分片上传最核心的价值它把网络的不可靠性变成了一种可控、可恢复的常态而不是捅破上传体验的致命伤。10. 分片上传的两种扩展跨端续传与分片验证码增强如果你的分片上传方案已经稳定运行并且想再往前走一步有两类增强值得考虑。10.1 跨端续传让用户换设备也能接着传断点续传服务端分片状态记录天然支持“跨端续传”能力。用户A在手机上传到一半换到电脑上继续传只要把uploadId和鉴权信息带过去即可。需要做的工作主要是设计好“恢复会话”的鉴权机制防止uploadId泄露后被他人恶意续传或拉取文件。在时序图上就增加了一条“恢复会话时校验token”的交互。这个功能对B端产品的用户粘度提升非常明显。10.2 分片验证码更强的数据完整性保障前面提到的是整个文件的MD5校验但如果在分片上传阶段就对每个分片做独立的校验码记录合并时再校验一遍可以把数据损坏的检出粒度从“整文件级别”缩小到“单片级别”。具体方案是客户端计算每个分片的MD5上传时把MD5作为每个请求的一个字段服务端存储分片时记录校验码合并完成后服务端还可以重新计算完整文件的校验码三重校验环环相扣。成本也不高对CPU负载的影响几乎可以忽略。但换来的是极高的信心——当用户问“传上去的文件会不会坏”你可以给出确定性回答。11. 最后分享一点个人经验先画时序图再写代码这句话救过我很多次分片上传这个功能看起来是“切个片、传一下、拼一下”真正实现了才发现全流程的状态节点多到惊人。初始化、分片上传、断点续传、完成合并、临时清理、异常恢复、跨端续传每个节点都有前置条件和后续动作错一环就在线上出一次事故。我个人的习惯是在写第一行代码之前先把上文那张时序图画完整——包括主路径和异常分支。画完之后把每个消息箭头对应的接口名、参数、返回值写出来再核对一遍状态流转。整个过程通常需要一两个小时但节省的返工时间远远不止这些。如果你的项目正准备上分片上传我的建议是不要急着写代码。先拿一张纸把客户端、服务端、存储系统三个角色画出来把每一个交互的时间点和分支条件标上用自己真实的分片大小和并发参数过一遍流程。你能在图里发现的问题以后就不会出现在生产环境里。分片上传不是那种“网上抄个demo就能用”的功能它涉及网络、存储、并发、状态管理、异常恢复等多个环节每个环节都要有明确的决策依据。希望这篇从时序图角度展开的拆解能把你在设计阶段遇到的疑惑和坑都提前填平。
分片上传全流程拆解：时序图、断点续传与并发实践
1. 从一次“上传失败”说起为什么我们离不开分片上传讲分片上传之前先聊聊我去年经手的一个真实项目。当时要给客户做一个视频管理后台素材动辄几个GB最初图省事直接用了普通的POST表单上传。测试环境里百兆宽带下传一个2GB的文件看着进度条一点点爬结果到83%的时候网络闪断整个文件作废用户得从头再来。客户的运维当场脸就黑了。这个场景估计不少人都遇到过。文件越大单次上传的失败率越高重试成本也越高。根本原因在于传统上传把整个文件当作一个不可分割的整体服务端必须等完整字节流到达才能落盘。网络抖动、代理超时、服务器重启、客户端程序被杀任何一个环节出问题前面传输的数据就全部作废。分片上传的核心思路很简单粗暴把大文件切成若干个小块逐块上传服务端收齐后合并成原始文件。每一片都是独立传输单元失败只需要重传失败的那一片而不是整个文件。但分片上传真正落地时远比“切块上传”这四个字复杂。分片之间的时序关系、并发控制、合并校验、断点续传每一步都藏着坑。这篇文章我想从时序图的视角把分片上传的完整过程、关键节点、状态流转都拆开讲一遍把我在项目里踩过的坑和最终沉淀下来的方案一起放出来。2. 为什么要分片从传输模型看单文件上传的七个致命问题先回到最底层的问题我们为什么需要分片很多人觉得“文件大才需要分片”这个说法对但不完整。分片解决的从来不只是“大”而是“大文件传输过程中的不确定性”。2.1 网络请求的先天限制HTTP协议本身并不限制请求体的大小但实际链路里到处都是限制。Nginx默认client_max_body_size是1MBTomcat的maxPostSize默认2MB云厂商的SLB和API网关也各有各的体量上限。不是说调大不行而是调大之后会引入新的问题内存占用、超时配置、负载均衡器的连接时长限制。我见过最典型的一个事故生产环境的Nginx配置了client_max_body_size 500m结果客户端上传大文件时请求在网关层被截断Nginx返回了413错误。排查了半天最后发现是前置的云负载均衡器单请求最大只支持100MB。这种链路里的隐形墙不把文件切小根本绕不过去。2.2 失败重试的代价随文件大小线性上升网络传输的失败率虽然低但不是零。假设单次请求失败的概率是0.1%一个100MB的文件用一次请求传完失败率也就是0.1%但如果分成100片每片1MB要做完整个上传需要100次请求全部成功概率是(1-0.001)^100 ≈ 90.5%整体失败率反而接近10%。看到这个数字可能有人会疑惑那分片不是增加了失败概率吗关键差异在于失败后的恢复成本。单请求模式下失败一次意味着100MB全部重传分片模式下失败一片只重传1MB。数学期望算下来分片的平均传输量远小于不分片。打个比方搬家时把全部家当装进一个集装箱路上翻车一次就得重新收拾分片相当于把家当装进100个小箱子翻车了只损失其中一箱其余箱子照常到达。这是分片最核心的价值——缩短重试范围降低平均传输成本。2.3 单请求无法享受的并发红利普通上传是串行的请求发出等待响应再发下一个。如果文件只有几MB串行上传和并发上传的区别可能只有几百毫秒但GB级别的文件串行上传的耗时简直无法忍受。分片之后每个分片的请求天然独立可以并行发起。客户端可以根据带宽状况开N个并发上传通道把网络带宽吃到接近极限。对于内网传输、跨地域传输这些长肥链路场景并发的收益尤其明显。我在一个跨洋传输项目里把分片并发从1路调到8路传输时间直接缩短了约5倍。2.4 时图视角下的本质从“一个请求”到“一组请求”传统上传的时序图只有三条线客户端发起、服务端响应、完成。而分片上传的时序图里客户端、服务端、存储系统之间的交互是一张网状结构——初始化、逐片上传、并发推进、合并请求、轮询状态、失败重试、断点恢复每个节点都有自己的生命周期。这也是为什么我总跟团队强调设计分片上传方案先画时序图再写代码。时序图能逼你把每个角色的职责、每条消息的触发条件、每个状态的前提和后续都理清楚。时序图画不出来或者画出来逻辑矛盾代码写一半一定会被返工。3. 分片上传完整流程一张时序图背后的六个关键阶段下面这张时序图描述的是我在生产环境里实际落地过的一套方案。它涵盖了一个分片上传从初始化到最终确认的完整生命周期。请重点看每个交互的前置条件和触发逻辑这是时序图的灵魂所在。客户端 服务端 存储系统 | | | | 1. 初始化上传请求 | | | (文件名/大小/分片数) | | |-----------------------------| | | | 2. 创建上传会话(返回 uploadId) | | ---------------------------| | | | | | 3. 逐片上传(可并发) | | | (分片序号 分片内容) | | |-----------------------------| 4. 校验分片序号/大小 | | |--------------------------------| | | 5. 存储分片记录元数据 | | |--------------------------------| | ---------------------------| | | | | | 6. 完成上传请求 | | | (uploadId 分片清单) | | |-----------------------------| 7. 按序号排列并合并分片 | | |--------------------------------| | | 8. 返回最终文件地址/校验值 | | ---------------------------| | | | |下面按阶段逐个拆解。3.1 阶段一初始化上传会话建立“契约”时序图里第一条交互就是客户端向服务端发起“初始化上传请求”。这条消息很关键它定义了后续所有分片的“契约”。请求里通常要携带这些信息原始文件名用于合并后的文件命名文件总大小服务端校验累计分片体量的依据分片大小客户端规划好的分片策略服务端需要校验其合法性分片总数上传完成的判定依据之一可选的MD5或文件指纹用于最终合并后的完整性校验服务端收到请求后会做两件事一是校验元数据合法性和配额二是创建一个“上传会话”核心是一个唯一的uploadId并在缓存或数据库里记录该会话的所有状态信息。这个uploadId是整个分片上传流程的“会话凭证”。后续所有分片上传请求都需要携带它。有了它即使客户端断网、重启、甚至换一台设备只要拿到同一个uploadId就能恢复之前的传输进度。我在设计时给初始化接口加了一个幂等键客户端生成一个UUID作为requestId服务端在缓存里做去重。这样即使客户端因网络超时重试初始化请求也不会创建出多个孤儿会话。这个是踩过坑之后补上的后面会细讲。3.2 阶段二分片规则的设计与确认客户端在初始化请求里报上自己的分片策略服务端确认通过后才进入传输阶段。分片大小和分片数量的选择直接影响传输效率和失败重试成本。我常用的一个经验标准是文件小于 100MB分片大小 1MB ~ 2MB文件在 100MB ~ 1GB 之间分片大小 5MB ~ 10MB文件在 1GB ~ 10GB 之间分片大小 10MB ~ 50MB前端的约束是浏览器环境里读取文件分片需要Blob.slice()这个操作本身很快没有太强的性能瓶颈。后端的约束是内存缓冲区和临时文件的规划分片太小会导致请求数过多占用大量HTTP连接分片太大会失去分片的意义。还有一个容易忽略的点最后一个分片通常小于标称分片大小服务端一定要允许这种“不齐整”。很多新手写的校验逻辑是“每片必须等于分片大小”结果最后一片永远校验失败。3.3 阶段三分片并行上传与滑动窗口时序图中间最热闹的一段是“逐片上传可并发”的部分。客户端拿到uploadId后把文件切成N片然后开M个并发通道按窗口机制推进。窗口机制要解决的现实问题是如果一次性把100个分片全部并发发出去服务端可能扛不住也可能因为网络拥塞造成过多的分片重传。合理的做法是维护一个“滑动窗口”初始只允许4到6个分片在途每成功一个从待发送队列里补一个进来。窗口大小可以根据上传速度动态调整带宽充裕时放宽丢包率升高时收紧。每个分片的上传请求必须携带uploadId会话标识partNumber分片序号从1开始连续递增分片内容本身可选的分片MD5服务端可以单片校验提前发现坏片服务端收到分片后先校验uploadId对应的会话是否存在、partNumber是否在合法区间内、分片大小是否和partNumber匹配然后才写入临时存储。等所有分片都上传完成、客户端调用“完成上传”接口后服务端再按序号拼接。3.4 阶段四完成上传与分片合并的边界条件所有分片上传成功后客户端发一条“完成上传”请求携带uploadId和完整的partNumber列表。服务端收到这条消息才决定启动合并流程。这个设计是刻意的服务端不主动猜测上传是否完成一切以客户端的“完成信号”为准。因为分片可能是乱序到达的服务端不能因为“收到了80%的分片”就以为快完成了。只有客户端自己知道它是否把所有分片都发完了。合并过程需要注意两点必须按partNumber排序后再拼接而不是按存储顺序直接合并。多个并发请求到达存储系统时碎片顺序是乱的直接拼接会毁掉文件。合并可能耗时较长尤其是TB级别的文件。因此“完成上传”接口不能是同步等待合并结束的简单阻塞接口最好是异步任务状态查询的模式。我在项目中采用的方案是完成上传接口返回一个taskId客户端拿着taskId轮询合并任务的执行状态比如pending、running、success、failed。时序图里体现为“轮询状态”这条虚线交互。虽然多了一个接口但避免了HTTP连接被长时间占用也方便做重试和审计。3.5 阶段五合并后的完整性校验合并完成后服务端需要给客户端一个交代。这个“交代”不只是一条成功响应而是一个可验证的文件指纹。具体做法是合并完成后计算整个文件的MD5或者SHA-256然后和客户端初始化时上报的原始文件指纹比对。如果一致说明合并过程没有发生数据丢失或字节序错乱如果不一致说明合并有问题或者某个分片本身就是坏的需要标记分片并触发重传。这里有个性能细节计算一个2GB文件的MD5需要几十秒甚至更长如果放在同步链路里会卡很久。我在生产方案里把校验放在合并任务内部和拼接步骤做成一个流水线结果通过taskId轮询获取。客户端拿到结果后可以再拉一遍文件做二次校验不过这个属于可选的双保险实际业务里很少做。3.6 阶段六会话清理与临时文件回收一个不怎么被提及但极其重要的阶段上传会话的生命周期管理。用户上传到一半放弃、客户端崩溃、网络长期断开——这些情况都会让服务端残留未完成的上传会话和一堆半成品分片。如果不做清理机制临时存储会被吃光。我一般会为每个上传会话设置过期时间默认24小时客户端通过心跳或续传请求不断续期。超过过期时间仍未完成合并的会话会被后台定时任务扫描并删除同时清理对应的临时分片文件。这里需要小心一个边界不要在用户还在传输时误删会话。扫描时机的判断要基于最后的活跃时间而不是创建时间。比如一个2GB的文件传输了20小时每次都有分片成功活跃时间一直在刷新这种会话就不能算过期。4. 关键参数与策略选型分片大小、并发数、超时该如何定网络上讲分片上传的教程不少但大多只讲流程不讲参数怎么定。参数选型决定了你的方案在实战中是稳如老狗还是频繁重试。这一节把我沉淀下来的参数计算方法和选型逻辑摊开讲。4.1 分片大小的上下限约束分片大小不是拍脑袋定的它受四个因素约束网络层MTU与TCP窗口单个TCP连接的吞吐量和带宽延迟积相关过小的分片比如256KB在长肥链路上无法充分利用单连接带宽过大的分片比如100MB又会导致重传代价过高。客户端内存浏览器端File.slice只负责逻辑切割真正把分片读入内存的是FormData或fetch/axios的body。如果同时开8路并发每路分片大小为20MB那么客户端内存峰值就要预留160MB这在低配移动设备上会直接OOM。服务端缓冲区如果服务端采用“收齐所有分片后合并”的策略那么临时文件存储总量就是文件总大小分片大小只是影响单分片写入粒度。请求数量分片越小请求越多HTTP握手、鉴权、日志的开销越大。1GB文件若用1MB分片就是1024个请求每个请求都有至少两次网络往返纯开销就很可观。我曾经测过一组数据千兆内网环境文件大小2GB分片大小从1MB增加到8MB总耗时先降后升。1MB时分片开销太大8MB时并发窗口内的网络利用率下降最优值落在4MB左右。如果你不想做精细化调优以5MB起步进行验证是比较稳的选择。4.2 并发数怎么算别拍脑袋开8路并发数不是固定值理论基础是“BDP估计”即带宽延迟积。公式很简单并发窗口大小 ≈ (带宽MB/s × RTT毫秒) / (8 × 分片大小MB)举例客户端上行带宽50MbpsRTT 20ms换算成字节带宽6.25MB/sRTT 0.02s。BDP约0.125MB 128KB。如果分片大小为5MB那么单连接带宽利用率其实很低因为一个RTT内最多塞进128KB5MB的分片要等40个RTT才能发完。这种情况下并发数要开到足够大才能填满带宽。更实用的做法是动态反馈调整客户端维护一个“在途分片数”每成功一片就计算平均单片耗时如果单片耗时持续下降说明带宽未被占满可以适当增加窗口如果单片耗时上升说明网络拥堵立即缩减窗口。很多优秀的开源库比如Tus、UpChunk走的都是这个思路。我给一个最常用的初始值场景初始分片大小初始并发数说明移动端弱网512KB ~ 1MB2单分片越小弱网重试代价越低浏览器普通宽带2MB ~ 8MB3 ~ 5平衡请求数和并行度桌面端内网/专线8MB ~ 16MB8 ~ 16充分利用带宽分片不宜过大跨地域长传5MB ~ 10MB4 ~ 8大分片降低RTT开销适度并发4.3 超时与重试处理“假失败”分片上传中最让人抓狂的现象是分片明明已经传到服务端了但客户端因为没有及时收到响应判定为超时然后重传同一片。如果服务端没有做幂等处理就会收到两片相同的分片合并时出现数据重复。应对方案有两层服务端分片幂等以uploadId partNumber为唯一键如果该分片已存在直接返回成功不重复存储。时序图上体现为“重复请求合并”的一个分支判断。客户端超时分级连接超时比如5秒直接重试读取超时比如30秒先主动查询该分片是否已到达服务端再决定是否重传。这个查询接口很轻量能避免大量无谓的重传流量。我强烈建议实现服务端分片幂等因为它的成本极低、收益极高。简单场景下甚至不需要数据库用内存缓存存储“已上传分片的partNumber集合”即可。5. 服务端落盘与合并临时文件管理和并发合并的细节服务端的实现风格决定了整套方案的稳定性。很多教程把重点放在客户端忽略服务端的设计结果就是“三分钟搭出demo上线第一周炸出五个bug”。这里把我认为最重要的几个服务端细节讲透。5.1 临时文件的组织方式目录名里带uploadId为了避免不同会话之间的分片文件互相干扰我会为每个上传会话单独建一个临时目录目录名直接用uploadId。结构类似/upload_tmp/7f2c4b09-6e1a-4c3f-8b7d-2f1a9e5c3d77/ part_001 part_002 part_003 ...uploadId使用UUID时随机性有保证目录冲突的概率基本为零。如果文件数特别多分片数上百万可以用两层目录结构比如按uploadId的前两位再分一层避免单目录下文件数过多导致文件系统性能退化。还有一点容易被忽略临时目录和最终存储目录建议放在同一个文件系统下。合并操作的本质是“按顺序拼接”如果跨文件系统拼接过程就会变成“读取写入”IO开销翻倍同一文件系统下可以做rename或硬链接成本极低。5.2 合并的并发控制一次只有一个合并线程合并操作最怕重复执行。如果“完成上传”请求被客户端重试服务端可能同时启动两个合并任务读取同一批分片文件产生竞争和脏数据。我的方案是引入一个task_lock以uploadId为粒度做互斥。具体实现可以用数据库行锁也可以用Redis的SETNX命令获取到锁的任务才能执行合并其他任务进入等待或直接返回“当前任务已存在”。合并的伪代码逻辑大致如下def merge_chunks(upload_id, part_numbers): if lock_exists(upload_id): return merge already running set_lock(upload_id, ttl10min) try: with open(final_path, wb) as fp: for part_number in sorted(part_numbers): chunk_path temp_dir / fpart_{part_number} fp.write(read_file(chunk_path)) os.remove(chunk_path) # 边读边清理减少临时空间占用 # 计算最终文件MD5与预期值比对 status success if verify() else failed finally: release_lock(upload_id)这里有一个容易被忽略的性能点逐片写入比“把所有分片拼接成一个大临时文件再整体移动”更省空间。因为分片上传过程中临时文件已经占用了近乎完整文件的空间合并时如果先生成一个大临时文件再写最终文件临时空间峰值会是文件大小的两倍。边读边写、边清理分片总空间峰值只比文件大小多一个分片大小。5.3 合并失败怎么办重试策略与部分失败恢复合并从来不是100%成功的。磁盘空间不足、分片文件被误删、读写出错都可能导致合并失败。我设计的合并任务包含一个“失败原因”字段失败后允许客户端重新发起“完成上传”请求服务端会先清理不完整的合并产出物然后重新启动合并。如果某些分片确实缺失响应里会明确告诉客户端“缺失分片序号列表”客户端根据这个列表精确补传而不是全量重传。这个设计既需要服务端诚实——它不能假装合并成功也需要客户端配合——它能处理“部分缺失”的响应并精准补片。很多项目在这个环节省事结果就是数据静默损坏只能靠更加愚蠢的全量重传兜底。6. 断点续传与状态记录客户端如何快速回到中断现场分片上传的一大优势是天然支持断点续传。但这个优势不会自己兑现客户端必须主动管理“哪些分片已成功上传”的状态。6.1 客户端状态维护的两种方式最简单的方式用本地状态文件或localStorage记录。每成功一片就持久化一个partNumber。下次启动上传时先读取这些成功记录跳过已成功的分片只传剩余部分。LocalStorage的容量大约是5MB记录上万个分片序号会爆掉。更稳的方案是维护一个Bitmap或位数组比如文件有1024片用一个1024位的数组来表示每位对应一个分片序号1表示已成功。这个位数组可以序列化成一个小字符串存localStorage毫无压力。更复杂的方案是服务端状态查询。客户端发起续传时调用“查询分片状态”接口服务端返回该uploadId下已收到的分片序号列表。这种方式不需要客户端本地持久化任何数据换浏览器、换设备都能续传但会增加服务端存储负担和查询压力。我倾向两种方式结合本地状态用于即时恢复服务端状态用于跨会话兜底。它们的同步时机是每次分片上传成功并更新本地状态后服务端的临时文件就是事实来源。6.2 断点续传的时序图视角断点续传在时序图上表现为客户端重新发起“初始化上传请求”时携带上次的uploadId服务端返回“该会话已存在及其分片状态”客户端根据返回的已上传分片集合只发送缺口部分。客户端 服务端 | 恢复上传请求(uploadId) | |------------------------------| | 返回已上传分片列表 | |------------------------------| | 并发上传缺失分片 | |-----------------------------|这里有一个坑极易踩上传会话过期导致续传失败。比如用户上传到一半去开会回来时已超过会话过期时间服务端已经把临时文件清理了。此时客户端如果傻傻地传缺失分片一定会失败。解决思路是在客户端发起续传前先判断服务端返回的会话状态如果会话存在且未过期进入增量续传流程如果会话不存在或已过期重新初始化上传会话从零开始如果部分分片已存在但会话接近过期客户端必须主动触发“续期接口”把过期时间向后推6.3 秒传当分片上传遇到文件指纹讲分片上传就不能不提“秒传”它本质上是断点续传的另一种表现形式。所谓秒传是指客户端在初始化上传请求时携带文件的MD5或更稳妥的SHA-256服务端先在已有的文件库中查一遍如果发现内容完全一致的文件直接返回“上传成功”和指向该文件的地址不再进行任何实际传输。秒传的实现逻辑并不复杂但有个技术细节需要注意对大文件计算MD5本身就要读一遍整个文件耗时可能很长。一个2GB的文件本地机械硬盘的读取速度可能只有150MB/s计算MD5需要十几秒用户在这段时间里看着进度条不动体验并不好。我常用的优化做法是“先采样后计算”对于超过特定大小比如100MB的文件不计算全文MD5而是取头、中、尾各1MB做采样加上文件大小组成一个“弱指纹”先做一轮预筛选。如果弱指纹唯一不触发秒传如果弱指纹匹配到候选文件再计算全文指纹做最终确认。这样既减少了大多数场景下的计算开销又不会降低秒传的准确性。7. 时序图之外兼容性与异常场景的防御性设计分片上传方案真正上线前我还会花大量时间处理“意外情况”。这部分内容往往是最被低估的但也是线上故障的主要来源。7.1 HTTP断连与浏览器刷新的处理浏览器环境里最头疼的问题是用户上传过程中直接刷新页面或者点击了“取消上传”浏览器会把所有在途的XMLHttpRequest或fetch请求立刻中止。如果服务端没有对这种情况做特殊处理已经传完的分片都留在临时目录里但客户端再也无法“恢复现场”——因为会话还在客户端的本地状态却丢失了。较好的实践是前端在上传页面销毁前把当前uploadId和成功分片列表写进localStorage。页面重新加载时检测到存在未完成的上传记录自动提示用户恢复上传。这是一个看似简单但非常影响体验的功能做没做用户感知特别明显。7.2 分片顺序错乱与重复片的防御并发上传天然导致分片乱序到达。服务端绝不能假设“先到的分片序号小、后到的分片序号大”否则合并出的文件必然是坏的。防御手段前面提过这里再集中强调一遍分片存储阶段每个分片独立保存文件名包含partNumber合并阶段强制按partNumber排序后再拼接同一个partNumber如果收到多次以最后一次为准或直接忽略重复请求7.3 服务端会话过期的动态续期会话过期策略不能是死板的“创建时间24小时”因为一个耗时很长的上传会突破这个限制。最稳妥的做法是每次分片上传成功后更新会话的“最后活跃时间”过期判定基于最后活跃时间。定时清理任务扫描时判断条件如下会话过期时间 max(会话创建时间 最大生存期, 最后活跃时间 空闲容忍期)举例最大生存期48小时空闲容忍期24小时。如果一个会话创建后不断有分片上传只要两次上传间隔不超过24小时就不会被清理。如果用户上传10小时才传了一半然后凌晨去睡觉也不至于立刻被删——但第二天回来还没继续服务端就有权清理了。7.4 资源配额与流量控制为了防意外我还会给每个用户加一个“在途临时文件总大小”的配额。因为一个用户可能同时有多个上传会话在进行如果都不限制临时盘会被塞满影响平台上所有用户的上传任务。配额限制写在初始化上传会话的接口里如果当前用户所有在途会话的原始文件大小总和超过阈值就拒绝创建新会话返回明确的错误码。这种限制一般不会误伤正常用户但能在异常请求量的冲击下保住整个服务的稳定性。8. 时序图工具选型UML时序图、云服务自带监测图还是自定义图最后聊一聊“时序图”本身。前面讲了半天分片上传状态流转但实际工作中我们画时序图用的什么工具、什么规范也值得单独说一嘴。8.1 规格各异的“时序图”严格来讲UML时序图是描述对象之间消息传递时间顺序的标准图型强调“多个角色之间在时间轴上的交互顺序”。它的元素包括生命线Lifeline、激活条Activation、消息箭头Message、返回箭头Return Message、可选片段Combined Fragment等。但实际项目里很多人说的“时序图”可能不只是UML时序图还包含泳道图把不同系统的处理过程按纵向泳道排列、活动图描述流程分支甚至交互流程图。以“i2c时序图”为例那片领域里的时序图更多是指物理电平在时钟线SCL和数据线SDA上的波形变化和UML时序图是两个完全不同的概念。本文讨论的分片上传时序图属于前一种即UML时序图。对于分片上传这种多角色、多分支、有并发交互的场景我强烈建议用标准UML时序图来画因为它的“生命线”和“消息顺序”表达能力刚好匹配我们的需求。如果你用泳道图画分片上传各角色上下游关系虽然直观但并发消息的先后关系很难表达清楚。8.2 工具选型与建模思路常用工具我试过几款简单列一下工具适用场景优点缺点PlantUML代码内嵌、自动化文档纯文本、可版本管理、支持大部分UML语法图形样式偏简陋复杂布局需要调参数MermaidMarkdown生态、快速草图语法轻量渲染即时复杂分支和嵌套片段的表达能力偏弱draw.io / diagrams.net正式交付、对外产图界面友好支持手绘布局可导出高清图手工调整耗时无法版本化管理云监控平台的链路图生产环境性能分析自动生成的调用链真实数据驱动无法精准表达设计态的分支与异常场景我的建议是迭代用PlantUML或Mermaid交付用draw.io或Visio精修。设计讨论期不需要好看的图要的是快速改、快速看、快速发现逻辑漏洞上线交付和方案评审时再花时间把图打磨精致。8.3 分片上传时序图建模时的两个实用技巧第一个技巧是给每个角色添加“状态校验”分支。比如客户端发“初始化上传请求”时服务端要先校验是否已有同uploadId的会话如果有走恢复流程如果没有走创建流程。把这个分支画在时序图上代码写的时候就不会漏掉它。第二个技巧是不要画“绝对理想路径”。完整的时序图除了包含主流程还要包含异常分支超时重试、分片缺失补传、会话过期重新初始化、合并失败重试。画完这些分支后你才能对系统边界有一个全局认知。我经常在评审会上看到两种极端一种是一张图表达了所有分支复杂到没人看得懂另一种是只画Happy Path看似完美代码实现时发现边界情况全都漏了。合理的标准是主路径用一条清晰的时间线画出来异常分支用独立的小图或文字标注拆出去既保持主图的可读性又不丢失边界逻辑。9. 生产环境里的真问题稳定运行三个月后的事实检验方案上线只是起点。真正有价值的经验来自线上运行几个月后遇到的真实问题。选几个典型案例分享出来比任何理论都更有说服力。案例一并发合并导致文件头部字节错乱上线早期我们曾遇到过一个诡异问题约连分片上传的文件偶发性地在若干KB处出现乱码。排查发现合并任务启动时读取分片文件同一分片文件被另一个还未释放的连接写入尾部数据两个进程对同一文件并发读写导致合并结果中出现极短但致命的字节错位。修复方案合并前先确认所有分片对应的HTTP请求已经全部结束同时在存储层引入“分片文件写入完成标记”只有标记存在才允许读取合并。从源头上杜绝并发读写同一个分片文件。案例二Nginx的body缓冲导致内存暴涨另一个典型案例是Nginx接收上传请求时的缓冲区设置。默认client_body_buffer_size较小大分片上传时Nginx会把请求体先暂存到临时文件但如果在配置里把缓冲区调得过大并发分片上传时Nginx worker进程内存直接被打满。这个问题的本质是“分片大小和服务端代理层配置不匹配”。后来我们把分片大小控制在4MB以内并设置合理的client_body_buffer_size内存问题随即消失。案例三用户上传到一半办公网络切换导致大量重传移动办公用户经常在Wi-Fi和4G之间切换IP地址变化导致部分HTTP请求被重置。我们统计过一次网络切换平均会造成约8%的在途分片失败。但由于分片上传方案本身的重试机制这些失败分片都只重传一次就成功了用户甚至完全没有感知到网络切换的发生。这正是分片上传最核心的价值它把网络的不可靠性变成了一种可控、可恢复的常态而不是捅破上传体验的致命伤。10. 分片上传的两种扩展跨端续传与分片验证码增强如果你的分片上传方案已经稳定运行并且想再往前走一步有两类增强值得考虑。10.1 跨端续传让用户换设备也能接着传断点续传服务端分片状态记录天然支持“跨端续传”能力。用户A在手机上传到一半换到电脑上继续传只要把uploadId和鉴权信息带过去即可。需要做的工作主要是设计好“恢复会话”的鉴权机制防止uploadId泄露后被他人恶意续传或拉取文件。在时序图上就增加了一条“恢复会话时校验token”的交互。这个功能对B端产品的用户粘度提升非常明显。10.2 分片验证码更强的数据完整性保障前面提到的是整个文件的MD5校验但如果在分片上传阶段就对每个分片做独立的校验码记录合并时再校验一遍可以把数据损坏的检出粒度从“整文件级别”缩小到“单片级别”。具体方案是客户端计算每个分片的MD5上传时把MD5作为每个请求的一个字段服务端存储分片时记录校验码合并完成后服务端还可以重新计算完整文件的校验码三重校验环环相扣。成本也不高对CPU负载的影响几乎可以忽略。但换来的是极高的信心——当用户问“传上去的文件会不会坏”你可以给出确定性回答。11. 最后分享一点个人经验先画时序图再写代码这句话救过我很多次分片上传这个功能看起来是“切个片、传一下、拼一下”真正实现了才发现全流程的状态节点多到惊人。初始化、分片上传、断点续传、完成合并、临时清理、异常恢复、跨端续传每个节点都有前置条件和后续动作错一环就在线上出一次事故。我个人的习惯是在写第一行代码之前先把上文那张时序图画完整——包括主路径和异常分支。画完之后把每个消息箭头对应的接口名、参数、返回值写出来再核对一遍状态流转。整个过程通常需要一两个小时但节省的返工时间远远不止这些。如果你的项目正准备上分片上传我的建议是不要急着写代码。先拿一张纸把客户端、服务端、存储系统三个角色画出来把每一个交互的时间点和分支条件标上用自己真实的分片大小和并发参数过一遍流程。你能在图里发现的问题以后就不会出现在生产环境里。分片上传不是那种“网上抄个demo就能用”的功能它涉及网络、存储、并发、状态管理、异常恢复等多个环节每个环节都要有明确的决策依据。希望这篇从时序图角度展开的拆解能把你在设计阶段遇到的疑惑和坑都提前填平。