方案分享SpringBoot如何集成插件实现大文件上传的MD5秒传校验先说个常见场景项目里需要上传几个G的视频素材用户等了两分钟页面还卡在进度条“转圈”后台显示文件才传了四分之一。换做是我第一反应也不是去骂带宽而是先看看这套上传链路到底有没有做“秒传校验”。所谓MD5秒传校验核心思路就一句话用户上传前先按内容算出一个唯一的文件指纹MD5服务端查一下这个指纹是否已经存在如果存在直接把新上传请求“短路”掉返回“上传成功”文件就不用真传了。这套能力在SpringBoot里落地并不难难的是做得“插件化”校验逻辑不写死在业务Controller里而是抽成一个独立模块主项目通过配置引入即可复用。今天我就把在项目里实践过的完整方案分享出来覆盖流程设计、核心代码、分片合并、二次校验、状态存储到最终压测调优。无论你是刚接触SpringBoot的新人还是已经在用MinIO、OSS做存储的老手都可以把这套秒传校验逻辑无缝嵌进自己的上传链路里。1. 秒传校验的完整流程设计先回答“一秒完成”还是“一个轮回”很多人一听到“秒传”就以为整个文件在1秒之内传完了。别被这个词骗了MD5秒传只是把“传输过程”省掉了但文件本身还需要在第一次上传时完整落盘。所以整个流程本质上要拆成两条链路一条是“第一次上传”的完整路径另一条是“重复上传”的秒传路径。1.1 前端计算MD5与秒传判定的一次往返前端拿到File对象后最理想的做法是在上传前先异步计算整个文件的MD5值。浏览器端我用的是spark-md5它能分片读取文件不把整个文件塞进内存2GB的大文件计算时间大约在3~6秒这个成本是可以接受的。计算完成后前端先调用后端的检查接口GET /api/upload/check?md5{fileMd5}size{fileSize}后端拿到MD5和文件大小后去文件记录表里查一下有没有“MD5相同 大小相同”的记录。如果存在且状态是“已完成”直接返回{ skip: true, fileId: 已存在记录的ID }前端这时候就可以弹“上传成功已秒传”整个过程只有一次HTTP往返这是真正的“秒传”。如果查不到记录后端就返回{ skip: false, uploadId: 新生成的ID }前端拿着这个uploadId开始分片上传。注意我特意把“大小相同”也加进了判定条件。原因在后面的二次校验章节展开这里先记住一个原则只用MD5做唯一判定迟早会在真实环境里踩坑。1.2 服务端的数据模型与状态机设计秒传校验要靠谱背后必须有一张能描述“文件当前处于什么阶段”的表。我一般叫它file_upload_record字段设计如下字段名类型说明idbigint主键upload_idvarchar(64)一次上传会话的唯一标识前端每次分片上传都要带上file_md5varchar(32)文件内容MD5file_sizebigint文件总字节数file_namevarchar(255)原始文件名file_pathvarchar(512)合并完成后的存储路径chunk_totalint总分片数chunk_uploadedint已上传分片数upload_statustinyint0临时态、1合并中、2已完成、3失败expire_atdatetime临时分片的过期时间用于清理孤儿分片这张表的核心价值在于它把“一个上传动作”抽象成了“一条可查询的记录”。用户的每次分片上传、合并请求都是在更新这条记录的状态。秒传判定也变成了一次简单的数据库查询。表建好之后再看服务端的关键接口这块我在下面的章节单独拆开讲。2. 插件化封装把校验逻辑从Controller拆出来的工程结构标题里特别强调了“集成插件实现”这里我想多说几句。所谓插件化在SpringBoot生态里有两种常见理解一是引入第三方starter组件比如MinIO的SDK二是把自己的通用逻辑封装成独立模块主项目以Maven依赖方式引入。我这里的MD5秒传校验更适合用第二种思路。2.1 自定义Starter模块的接口设计我把秒传校验的核心抽成了一个独立的Maven模块file-upload-plugin它不依赖任何业务方的数据库表只依赖一个抽象的“存取记录”接口。主项目只需要实现这个接口插件就能跑起来。public interface UploadRecordStore { UploadRecord findByMd5AndSize(String md5, long size); UploadRecord create(UploadRecord record); UploadRecord findById(String uploadId); boolean addChunkIndex(String uploadId, int chunkIndex); }有了这个接口业务方的Controller里不会出现任何“如果MD5相同就跳过”这种散落的逻辑。取而代之的是直接调用插件暴露的UploadDeduplicateServiceService public class UploadDeduplicateService { private final UploadRecordStore recordStore; public UploadDeduplicateService(UploadRecordStore recordStore) { this.recordStore recordStore; } public CheckResult check(String md5, long size) { UploadRecord record recordStore.findByMd5AndSize(md5, size); if (record ! null record.getUploadStatus() UploadStatus.COMPLETED) { return CheckResult.skip(record.getFileId()); } String uploadId UUID.randomUUID().toString().replace(-, ); recordStore.create(new UploadRecord(uploadId, md5, size)); return CheckResult.upload(uploadId); } }以后如果某天你不想用MD5了想换成SHA-256或者BLAKE3只需要再做一个实现类替换注入的组件即可。这就是插件化带来的直接收益业务方不需要因为算法升级而去改动Controller里那一堆上传逻辑。2.2 自动装配与配置项为了让主项目“引入依赖即生效”模块里需要写一个自动配置类Configuration EnableConfigurationProperties(UploadProperties.class) public class UploadPluginAutoConfiguration { Bean ConditionalOnMissingBean public UploadDeduplicateService uploadDeduplicateService(UploadRecordStore recordStore) { return new UploadDeduplicateService(recordStore); } }同时在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里写上这个配置类的全限定名。主项目里只需要dependency groupIdcom.example/groupId artifactIdfile-upload-plugin/artifactId version1.0.0/version /dependency以及实现一个UploadRecordStore就完成了接入。配置项方面我建议把分片大小、临时目录、合并线程池参数都放到application.yml里file: upload: chunk-size: 10MB temp-dir: /data/tmp/upload merge-thread-pool: 4 expire-days: 1为什么这样做因为“插件”这两个字的含义本质上就是把容易变化的参数变成配置把容易替换的实现变成接口。代码里硬编码的每一样东西将来都可能成为你熬夜排查的根源。3. 分片接收与合并的服务端实现细节秒传校验只是上传链路的前置判断真正的大文件上传还得靠分片。分片的理由很朴素一个2GB的文件如果走普通的MultipartFile一次性接收先不说前端表单能不能提交后端把2GB数据一次性读进内存JVM当场就要OutOfMemoryError。3.1 分片大小与前端切片的配合分片大小的选择我直接给出经验值5MB到20MB之间。太小会导致请求数量爆炸比如2GB文件切成1MB一片就有2048个请求光是HTTP握手就能把时间吃掉大半太大又会失去分片的意义网络抖动一次就要重传很大一块。我项目里用的是10MB2GB文件分成约205片并发3~5片上传实测带宽能跑满。前端切片的伪代码如下const file fileInput.files[0]; const chunkSize 10 * 1024 * 1024; const chunks Math.ceil(file.size / chunkSize); async function uploadChunks(uploadId, file, chunks, chunkSize) { for (let i 0; i chunks; i) { const start i * chunkSize; const end Math.min(file.size, start chunkSize); const blob file.slice(start, end); const formData new FormData(); formData.append(uploadId, uploadId); formData.append(chunkIndex, i); formData.append(chunkTotal, chunks); formData.append(chunk, blob); await fetch(/api/upload/chunk, { method: POST, body: formData }); } }3.2 后端分片落盘的幂等处理后端接到分片请求后要做的事情有三件校验uploadId存在、把分片写入临时目录、更新已上传分片数。这里最容易被忽略的是“幂等”——也就是同一个分片因为网络原因被前端重试了两次后端不能写两份也不能把chunkUploaded加两次。我的做法是给每个分片起一个固定的文件名以分片索引作为唯一标识PostMapping(/api/upload/chunk) public ResponseEntityVoid uploadChunk(RequestParam String uploadId, RequestParam int chunkIndex, RequestParam MultipartFile chunk) throws IOException { UploadRecord record recordStore.findById(uploadId); if (record null) { return ResponseEntity.notFound().build(); } Path chunkPath Paths.get(tempDir).resolve(uploadId _ chunkIndex .part); synchronized (uploadId.intern()) { if (Files.exists(chunkPath)) { // 已存在说明之前传过直接返回成功避免重复写入 return ResponseEntity.ok().build(); } try (InputStream in chunk.getInputStream()) { Files.copy(in, chunkPath, StandardCopyOption.REPLACE_EXISTING); } } boolean newAdd recordStore.addChunkIndex(uploadId, chunkIndex); if (newAdd) { // 仅当这次新增分片成功时才累加已上传计数 recordStore.incrementChunkUploaded(uploadId); } return ResponseEntity.ok().build(); }uploadId.intern()这个写法有点取巧但在单机部署下够用。它让同一个文件的分片上传期间相同uploadId的并发请求会排队处理避免两个线程同时判断“分片不存在”然后同时写入。要是将来做多节点部署这里要换成分布式锁具体我在状态存储章节再展开。3.3 合并文件时的顺序保证与性能优化所有分片上传完毕后前端调用合并接口POST /api/upload/merge Content-Type: application/json { uploadId: xxx, fileName: demo.mp4 }后端合并时最忌讳的做法是循环读取每个分片然后往同一个输出流里写这样不仅慢还可能在分片多的时候频繁触发GC。我采用的是RandomAccessFile按分片索引定位写入PostMapping(/api/upload/merge) public ResponseEntityUploadResult merge(RequestBody MergeRequest request) throws IOException { UploadRecord record recordStore.findById(request.getUploadId()); if (record null) { return ResponseEntity.notFound().build(); } String finalPath storageDir / record.getFileMd5() _ record.getFileSize(); Path finalFile Paths.get(finalPath); recordStore.markMerging(request.getUploadId()); try (FileChannel out FileChannel.open(finalFile, StandardOpenOption.CREATE, StandardOpenOption.WRITE)) { for (int i 0; i record.getChunkTotal(); i) { Path chunkPath Paths.get(tempDir).resolve(request.getUploadId() _ i .part); try (FileChannel in FileChannel.open(chunkPath, StandardOpenOption.READ)) { long size in.size(); long position i * (long) chunkSize; in.transferTo(0, size, out); } } } // 合并完成后清理分片文件 for (int i 0; i record.getChunkTotal(); i) { Files.deleteIfExists(Paths.get(tempDir).resolve(request.getUploadId() _ i .part)); } recordStore.markCompleted(request.getUploadId(), finalPath); return ResponseEntity.ok(new UploadResult(record.getFileMd5(), finalPath)); }这里有个细节值得强调为什么最终文件路径要用fileMd5_fileSize命名因为秒传的关键在于“相同内容的文件只保留一份”用内容的MD5和大小一起做文件名天然就实现了去重存储。后面再来一个相同文件的秒传请求直接返回已存在的路径就行。4. 二次校验为什么MD5通过后还要再算一遍如果你看过我之前写的其他上传方案应该记得我说过一句话“前端算的MD5只能作为一种弱信任凭证。”MD5算法的碰撞风险在安全领域由来已久但在上传场景里我们面临的主要问题还不是恶意碰撞而是更加繁琐的现实问题网络传输中分片损坏、前端内存计算错误、不同浏览器对File.slice边界的处理不一致这些都可能导致合并后的文件与原始文件不一致。4.1 合并后的服务端重算策略所以我的方案里合并完成后一定会对最终文件再做一次完整的MD5计算与前端提交的MD5进行比对。如果一致才算真正上传成功如果不一致直接把这条记录标记为失败返回给前端“文件校验失败请重试”。String actualMd5 DigestUtils.md5Hex(new FileInputStream(finalFile.toFile())); if (!actualMd5.equalsIgnoreCase(record.getFileMd5())) { recordStore.markFailed(request.getUploadId()); Files.deleteIfExists(finalFile); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(文件校验失败请重新上传); }有人可能会问那这样不是又多了一次全文件读取确实合并后服务端计算MD5需要再读一遍文件但这是保证数据正确性必须支付的成本。而且这个操作可以放到异步线程里做不必阻塞前端等待。前端只需要轮询合并状态接口即可。4.2 相同MD5不同文件名的处理另一个容易被忽略的问题两个用户上传内容完全相同但文件名不同的文件MD5和大小都一致这时秒传是成立的——因为文件名本身不该成为“文件是否同一份”的依据。但在业务上用户可能需要保留各自的文件名。我的处理方案是文件内容只存一份文件名和业务元数据存到另一张业务表里指向这份物理文件的ID。这样既享受了去重存储的存储成本优势又满足了业务上文件名的独立性。5. 状态存储选型从内存Map到Redis再到对象存储前面提到的UploadRecordStore接口我给了三种实现方式按项目规模从小到大排列。5.1 单体应用数据库表实现最朴素也最稳定的方式就是用MySQL或者PostgreSQL存储上传记录。好处是事务可控、查询方便、重启不丢数据。缺点嘛在高频分片上传时每次addChunkIndex都是一次写库操作2GB文件分成200片意味着有200次数据库写入虽然不至于压垮数据库但显然不是最优解。5.2 高频场景Redis保存临时状态我实际工作中更推荐混合方案临时状态分片进度、上传状态放Redis以uploadId作为key用Hash结构存储最终稳定状态已完成文件的MD5、路径、大小落到数据库。这样check接口查“秒传”时可以走数据库索引而分片上传过程中的高频计数操作全部在内存里完成。public class RedisUploadRecordStore implements UploadRecordStore { private final RedisTemplateString, Object redisTemplate; Override public boolean addChunkIndex(String uploadId, int chunkIndex) { Long added redisTemplate.opsForSet().add(upload:chunks: uploadId, chunkIndex); return added ! null added 0; } }用Set来存已上传的分片索引还有一个额外好处天然去重且能直接通过查询Set集合得到已上传分片列表方便做断点续传。前端重新打开页面时调用GET /api/upload/chunks?uploadIdxxx后端把Set里已存在的分片索引返回给前端前端直接跳过这些分片这就是断点续传的核心实现。5.3 大规模分布式对象存储与最终一致性如果文件最终要落到MinIO或阿里云OSS那么合并策略要变一下。最稳妥的做法是先把分片临时存储在本地磁盘或云服务器临时目录合并完整后再调用对象存储SDK一次性上传最终文件。直接让对象存储去承担分片合并虽然MinIO支持分片上传接口但会让业务代码与特定的对象存储强绑定失去了插件化的灵活性。我用MinIO实践时的做法是minioClient.putObject( PutObjectArgs.builder() .bucket(bucketName) .object(record.getFileMd5() _ record.getFileSize()) .stream(new FileInputStream(finalFile.toFile()), finalFile.toFile().length(), -1) .build() );上传完成后秒传校验就不需要再去查数据库文件路径了直接查对象存储里是否存在这个key即可。这一层同样抽象在UploadRecordStore的findByMd5AndSize实现里Controller根本感知不到底层换成MinIO了。6. 压测与调优实践参数、并发与真实数据写代码一时爽接生产火葬场。在我自己的实践中这套方案刚上线时就碰上过两个问题一是分片并发太高导致Tomcat线程池被打满二是临时目录堆积了大量孤儿分片把磁盘撑爆了。所以压测和调优不是可选项而是必选项。6.1 并发上传时的线程池隔离最初的版本里分片上传接口直接用的Tomcat默认线程池。当10个用户同时上传2GB文件每个文件200个分片再每个用户同时发5个分片请求瞬时请求量就是1000个并发。Tomcat默认200线程立刻被打满连健康检查接口都开始超时。解决办法是给分片上传单独配置一个线程池执行器Bean(chunkUploadExecutor) public ThreadPoolTaskExecutor chunkUploadExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(8); executor.setQueueCapacity(2000); executor.setThreadNamePrefix(chunk-upload-); return executor; }然后把分片接收逻辑用Async(chunkUploadExecutor)异步化前端上传分片后立刻返回“已接收”真正的落盘在异步线程里完成。这里要注意前端必须处理“已接收”不代表“已落盘”所以前端轮询进度时不能依靠HTTP响应而应该依靠GET /api/upload/progress接口查实际分片落盘情况。6.2 分片参数调优的实测对比我把不同分片大小和并发数的实测数据整理了一下方便你根据自己的带宽做决策文件大小分片大小并发分片数总耗时带宽利用率备注1GB5MB3约42s约75%请求数太多HTTP开销明显1GB10MB3约32s约88%推荐组合1GB10MB5约29s约92%带宽好的情况下最佳1GB20MB3约35s约80%分片大单片失败重传成本高1GB50MB2约45s约65%分片太大失去并发优势结论是分片大小10MB、并发数3到5是性价比最高的区间。分片再小请求开销占比上升分片再大单片重传成本太高且并发很难跑满带宽。6.3 临时目录的自动清理策略孤儿分片是怎么产生的用户上传到一半退出、前端断网、浏览器崩溃都会导致临时分片永远留在磁盘上。我建议的清理策略是每个uploadId在创建时带上过期时间比如1天启动一个定时任务每小时扫描一次临时目录删除所有修改时间早于过期时间的.part文件同时把对应的Redis状态记录也清掉。Scheduled(cron 0 0 * * * ?) public void cleanExpiredPartFiles() { try (StreamPath stream Files.list(Paths.get(tempDir))) { stream.filter(path - path.toString().endsWith(.part)) .filter(path - { try { return Files.getLastModifiedTime(path).toMillis() System.currentTimeMillis() - expireHours * 3600 * 1000L; } catch (IOException e) { return true; } }) .forEach(path - { try { Files.deleteIfExists(path); } catch (IOException ignored) { } }); } }别小看这个定时清理任务它能保证即使业务代码偶尔出问题磁盘也不会被垃圾分片拖垮。这套方案上线后我最深的体会是MD5秒传校验本身并不复杂复杂的是围绕它构建的整个上传链路的边界情况处理。插件化设计让我把这些边界情况都收敛在独立模块里主项目只需关注业务本身。最后再分享一个我在实践中替换算法的技巧如果你已经按插件化思路实现了UploadRecordStore和UploadDeduplicateService而某天产品要求支持秒传的同时计算文件的SHA-256你别去改Controller只需要在服务里加一个DigestType枚举然后把findByMd5AndSize替换成findByMd5AndSizeAndDigestType就行。这就是为什么我说插件化架构的核心收益不是“第一版跑多快”而是“第二版改多省”。 
长河君 · 2026/10/10 11:15:16 · 阅读 1.2k SpringBoot插件化实现大文件MD5秒传校验方案详解
方案分享SpringBoot如何集成插件实现大文件上传的MD5秒传校验先说个常见场景项目里需要上传几个G的视频素材用户等了两分钟页面还卡在进度条“转圈”后台显示文件才传了四分之一。换做是我第一反应也不是去骂带宽而是先看看这套上传链路到底有没有做“秒传校验”。所谓MD5秒传校验核心思路就一句话用户上传前先按内容算出一个唯一的文件指纹MD5服务端查一下这个指纹是否已经存在如果存在直接把新上传请求“短路”掉返回“上传成功”文件就不用真传了。这套能力在SpringBoot里落地并不难难的是做得“插件化”校验逻辑不写死在业务Controller里而是抽成一个独立模块主项目通过配置引入即可复用。今天我就把在项目里实践过的完整方案分享出来覆盖流程设计、核心代码、分片合并、二次校验、状态存储到最终压测调优。无论你是刚接触SpringBoot的新人还是已经在用MinIO、OSS做存储的老手都可以把这套秒传校验逻辑无缝嵌进自己的上传链路里。1. 秒传校验的完整流程设计先回答“一秒完成”还是“一个轮回”很多人一听到“秒传”就以为整个文件在1秒之内传完了。别被这个词骗了MD5秒传只是把“传输过程”省掉了但文件本身还需要在第一次上传时完整落盘。所以整个流程本质上要拆成两条链路一条是“第一次上传”的完整路径另一条是“重复上传”的秒传路径。1.1 前端计算MD5与秒传判定的一次往返前端拿到File对象后最理想的做法是在上传前先异步计算整个文件的MD5值。浏览器端我用的是spark-md5它能分片读取文件不把整个文件塞进内存2GB的大文件计算时间大约在3~6秒这个成本是可以接受的。计算完成后前端先调用后端的检查接口GET /api/upload/check?md5{fileMd5}size{fileSize}后端拿到MD5和文件大小后去文件记录表里查一下有没有“MD5相同 大小相同”的记录。如果存在且状态是“已完成”直接返回{ skip: true, fileId: 已存在记录的ID }前端这时候就可以弹“上传成功已秒传”整个过程只有一次HTTP往返这是真正的“秒传”。如果查不到记录后端就返回{ skip: false, uploadId: 新生成的ID }前端拿着这个uploadId开始分片上传。注意我特意把“大小相同”也加进了判定条件。原因在后面的二次校验章节展开这里先记住一个原则只用MD5做唯一判定迟早会在真实环境里踩坑。1.2 服务端的数据模型与状态机设计秒传校验要靠谱背后必须有一张能描述“文件当前处于什么阶段”的表。我一般叫它file_upload_record字段设计如下字段名类型说明idbigint主键upload_idvarchar(64)一次上传会话的唯一标识前端每次分片上传都要带上file_md5varchar(32)文件内容MD5file_sizebigint文件总字节数file_namevarchar(255)原始文件名file_pathvarchar(512)合并完成后的存储路径chunk_totalint总分片数chunk_uploadedint已上传分片数upload_statustinyint0临时态、1合并中、2已完成、3失败expire_atdatetime临时分片的过期时间用于清理孤儿分片这张表的核心价值在于它把“一个上传动作”抽象成了“一条可查询的记录”。用户的每次分片上传、合并请求都是在更新这条记录的状态。秒传判定也变成了一次简单的数据库查询。表建好之后再看服务端的关键接口这块我在下面的章节单独拆开讲。2. 插件化封装把校验逻辑从Controller拆出来的工程结构标题里特别强调了“集成插件实现”这里我想多说几句。所谓插件化在SpringBoot生态里有两种常见理解一是引入第三方starter组件比如MinIO的SDK二是把自己的通用逻辑封装成独立模块主项目以Maven依赖方式引入。我这里的MD5秒传校验更适合用第二种思路。2.1 自定义Starter模块的接口设计我把秒传校验的核心抽成了一个独立的Maven模块file-upload-plugin它不依赖任何业务方的数据库表只依赖一个抽象的“存取记录”接口。主项目只需要实现这个接口插件就能跑起来。public interface UploadRecordStore { UploadRecord findByMd5AndSize(String md5, long size); UploadRecord create(UploadRecord record); UploadRecord findById(String uploadId); boolean addChunkIndex(String uploadId, int chunkIndex); }有了这个接口业务方的Controller里不会出现任何“如果MD5相同就跳过”这种散落的逻辑。取而代之的是直接调用插件暴露的UploadDeduplicateServiceService public class UploadDeduplicateService { private final UploadRecordStore recordStore; public UploadDeduplicateService(UploadRecordStore recordStore) { this.recordStore recordStore; } public CheckResult check(String md5, long size) { UploadRecord record recordStore.findByMd5AndSize(md5, size); if (record ! null record.getUploadStatus() UploadStatus.COMPLETED) { return CheckResult.skip(record.getFileId()); } String uploadId UUID.randomUUID().toString().replace(-, ); recordStore.create(new UploadRecord(uploadId, md5, size)); return CheckResult.upload(uploadId); } }以后如果某天你不想用MD5了想换成SHA-256或者BLAKE3只需要再做一个实现类替换注入的组件即可。这就是插件化带来的直接收益业务方不需要因为算法升级而去改动Controller里那一堆上传逻辑。2.2 自动装配与配置项为了让主项目“引入依赖即生效”模块里需要写一个自动配置类Configuration EnableConfigurationProperties(UploadProperties.class) public class UploadPluginAutoConfiguration { Bean ConditionalOnMissingBean public UploadDeduplicateService uploadDeduplicateService(UploadRecordStore recordStore) { return new UploadDeduplicateService(recordStore); } }同时在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里写上这个配置类的全限定名。主项目里只需要dependency groupIdcom.example/groupId artifactIdfile-upload-plugin/artifactId version1.0.0/version /dependency以及实现一个UploadRecordStore就完成了接入。配置项方面我建议把分片大小、临时目录、合并线程池参数都放到application.yml里file: upload: chunk-size: 10MB temp-dir: /data/tmp/upload merge-thread-pool: 4 expire-days: 1为什么这样做因为“插件”这两个字的含义本质上就是把容易变化的参数变成配置把容易替换的实现变成接口。代码里硬编码的每一样东西将来都可能成为你熬夜排查的根源。3. 分片接收与合并的服务端实现细节秒传校验只是上传链路的前置判断真正的大文件上传还得靠分片。分片的理由很朴素一个2GB的文件如果走普通的MultipartFile一次性接收先不说前端表单能不能提交后端把2GB数据一次性读进内存JVM当场就要OutOfMemoryError。3.1 分片大小与前端切片的配合分片大小的选择我直接给出经验值5MB到20MB之间。太小会导致请求数量爆炸比如2GB文件切成1MB一片就有2048个请求光是HTTP握手就能把时间吃掉大半太大又会失去分片的意义网络抖动一次就要重传很大一块。我项目里用的是10MB2GB文件分成约205片并发3~5片上传实测带宽能跑满。前端切片的伪代码如下const file fileInput.files[0]; const chunkSize 10 * 1024 * 1024; const chunks Math.ceil(file.size / chunkSize); async function uploadChunks(uploadId, file, chunks, chunkSize) { for (let i 0; i chunks; i) { const start i * chunkSize; const end Math.min(file.size, start chunkSize); const blob file.slice(start, end); const formData new FormData(); formData.append(uploadId, uploadId); formData.append(chunkIndex, i); formData.append(chunkTotal, chunks); formData.append(chunk, blob); await fetch(/api/upload/chunk, { method: POST, body: formData }); } }3.2 后端分片落盘的幂等处理后端接到分片请求后要做的事情有三件校验uploadId存在、把分片写入临时目录、更新已上传分片数。这里最容易被忽略的是“幂等”——也就是同一个分片因为网络原因被前端重试了两次后端不能写两份也不能把chunkUploaded加两次。我的做法是给每个分片起一个固定的文件名以分片索引作为唯一标识PostMapping(/api/upload/chunk) public ResponseEntityVoid uploadChunk(RequestParam String uploadId, RequestParam int chunkIndex, RequestParam MultipartFile chunk) throws IOException { UploadRecord record recordStore.findById(uploadId); if (record null) { return ResponseEntity.notFound().build(); } Path chunkPath Paths.get(tempDir).resolve(uploadId _ chunkIndex .part); synchronized (uploadId.intern()) { if (Files.exists(chunkPath)) { // 已存在说明之前传过直接返回成功避免重复写入 return ResponseEntity.ok().build(); } try (InputStream in chunk.getInputStream()) { Files.copy(in, chunkPath, StandardCopyOption.REPLACE_EXISTING); } } boolean newAdd recordStore.addChunkIndex(uploadId, chunkIndex); if (newAdd) { // 仅当这次新增分片成功时才累加已上传计数 recordStore.incrementChunkUploaded(uploadId); } return ResponseEntity.ok().build(); }uploadId.intern()这个写法有点取巧但在单机部署下够用。它让同一个文件的分片上传期间相同uploadId的并发请求会排队处理避免两个线程同时判断“分片不存在”然后同时写入。要是将来做多节点部署这里要换成分布式锁具体我在状态存储章节再展开。3.3 合并文件时的顺序保证与性能优化所有分片上传完毕后前端调用合并接口POST /api/upload/merge Content-Type: application/json { uploadId: xxx, fileName: demo.mp4 }后端合并时最忌讳的做法是循环读取每个分片然后往同一个输出流里写这样不仅慢还可能在分片多的时候频繁触发GC。我采用的是RandomAccessFile按分片索引定位写入PostMapping(/api/upload/merge) public ResponseEntityUploadResult merge(RequestBody MergeRequest request) throws IOException { UploadRecord record recordStore.findById(request.getUploadId()); if (record null) { return ResponseEntity.notFound().build(); } String finalPath storageDir / record.getFileMd5() _ record.getFileSize(); Path finalFile Paths.get(finalPath); recordStore.markMerging(request.getUploadId()); try (FileChannel out FileChannel.open(finalFile, StandardOpenOption.CREATE, StandardOpenOption.WRITE)) { for (int i 0; i record.getChunkTotal(); i) { Path chunkPath Paths.get(tempDir).resolve(request.getUploadId() _ i .part); try (FileChannel in FileChannel.open(chunkPath, StandardOpenOption.READ)) { long size in.size(); long position i * (long) chunkSize; in.transferTo(0, size, out); } } } // 合并完成后清理分片文件 for (int i 0; i record.getChunkTotal(); i) { Files.deleteIfExists(Paths.get(tempDir).resolve(request.getUploadId() _ i .part)); } recordStore.markCompleted(request.getUploadId(), finalPath); return ResponseEntity.ok(new UploadResult(record.getFileMd5(), finalPath)); }这里有个细节值得强调为什么最终文件路径要用fileMd5_fileSize命名因为秒传的关键在于“相同内容的文件只保留一份”用内容的MD5和大小一起做文件名天然就实现了去重存储。后面再来一个相同文件的秒传请求直接返回已存在的路径就行。4. 二次校验为什么MD5通过后还要再算一遍如果你看过我之前写的其他上传方案应该记得我说过一句话“前端算的MD5只能作为一种弱信任凭证。”MD5算法的碰撞风险在安全领域由来已久但在上传场景里我们面临的主要问题还不是恶意碰撞而是更加繁琐的现实问题网络传输中分片损坏、前端内存计算错误、不同浏览器对File.slice边界的处理不一致这些都可能导致合并后的文件与原始文件不一致。4.1 合并后的服务端重算策略所以我的方案里合并完成后一定会对最终文件再做一次完整的MD5计算与前端提交的MD5进行比对。如果一致才算真正上传成功如果不一致直接把这条记录标记为失败返回给前端“文件校验失败请重试”。String actualMd5 DigestUtils.md5Hex(new FileInputStream(finalFile.toFile())); if (!actualMd5.equalsIgnoreCase(record.getFileMd5())) { recordStore.markFailed(request.getUploadId()); Files.deleteIfExists(finalFile); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(文件校验失败请重新上传); }有人可能会问那这样不是又多了一次全文件读取确实合并后服务端计算MD5需要再读一遍文件但这是保证数据正确性必须支付的成本。而且这个操作可以放到异步线程里做不必阻塞前端等待。前端只需要轮询合并状态接口即可。4.2 相同MD5不同文件名的处理另一个容易被忽略的问题两个用户上传内容完全相同但文件名不同的文件MD5和大小都一致这时秒传是成立的——因为文件名本身不该成为“文件是否同一份”的依据。但在业务上用户可能需要保留各自的文件名。我的处理方案是文件内容只存一份文件名和业务元数据存到另一张业务表里指向这份物理文件的ID。这样既享受了去重存储的存储成本优势又满足了业务上文件名的独立性。5. 状态存储选型从内存Map到Redis再到对象存储前面提到的UploadRecordStore接口我给了三种实现方式按项目规模从小到大排列。5.1 单体应用数据库表实现最朴素也最稳定的方式就是用MySQL或者PostgreSQL存储上传记录。好处是事务可控、查询方便、重启不丢数据。缺点嘛在高频分片上传时每次addChunkIndex都是一次写库操作2GB文件分成200片意味着有200次数据库写入虽然不至于压垮数据库但显然不是最优解。5.2 高频场景Redis保存临时状态我实际工作中更推荐混合方案临时状态分片进度、上传状态放Redis以uploadId作为key用Hash结构存储最终稳定状态已完成文件的MD5、路径、大小落到数据库。这样check接口查“秒传”时可以走数据库索引而分片上传过程中的高频计数操作全部在内存里完成。public class RedisUploadRecordStore implements UploadRecordStore { private final RedisTemplateString, Object redisTemplate; Override public boolean addChunkIndex(String uploadId, int chunkIndex) { Long added redisTemplate.opsForSet().add(upload:chunks: uploadId, chunkIndex); return added ! null added 0; } }用Set来存已上传的分片索引还有一个额外好处天然去重且能直接通过查询Set集合得到已上传分片列表方便做断点续传。前端重新打开页面时调用GET /api/upload/chunks?uploadIdxxx后端把Set里已存在的分片索引返回给前端前端直接跳过这些分片这就是断点续传的核心实现。5.3 大规模分布式对象存储与最终一致性如果文件最终要落到MinIO或阿里云OSS那么合并策略要变一下。最稳妥的做法是先把分片临时存储在本地磁盘或云服务器临时目录合并完整后再调用对象存储SDK一次性上传最终文件。直接让对象存储去承担分片合并虽然MinIO支持分片上传接口但会让业务代码与特定的对象存储强绑定失去了插件化的灵活性。我用MinIO实践时的做法是minioClient.putObject( PutObjectArgs.builder() .bucket(bucketName) .object(record.getFileMd5() _ record.getFileSize()) .stream(new FileInputStream(finalFile.toFile()), finalFile.toFile().length(), -1) .build() );上传完成后秒传校验就不需要再去查数据库文件路径了直接查对象存储里是否存在这个key即可。这一层同样抽象在UploadRecordStore的findByMd5AndSize实现里Controller根本感知不到底层换成MinIO了。6. 压测与调优实践参数、并发与真实数据写代码一时爽接生产火葬场。在我自己的实践中这套方案刚上线时就碰上过两个问题一是分片并发太高导致Tomcat线程池被打满二是临时目录堆积了大量孤儿分片把磁盘撑爆了。所以压测和调优不是可选项而是必选项。6.1 并发上传时的线程池隔离最初的版本里分片上传接口直接用的Tomcat默认线程池。当10个用户同时上传2GB文件每个文件200个分片再每个用户同时发5个分片请求瞬时请求量就是1000个并发。Tomcat默认200线程立刻被打满连健康检查接口都开始超时。解决办法是给分片上传单独配置一个线程池执行器Bean(chunkUploadExecutor) public ThreadPoolTaskExecutor chunkUploadExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(8); executor.setQueueCapacity(2000); executor.setThreadNamePrefix(chunk-upload-); return executor; }然后把分片接收逻辑用Async(chunkUploadExecutor)异步化前端上传分片后立刻返回“已接收”真正的落盘在异步线程里完成。这里要注意前端必须处理“已接收”不代表“已落盘”所以前端轮询进度时不能依靠HTTP响应而应该依靠GET /api/upload/progress接口查实际分片落盘情况。6.2 分片参数调优的实测对比我把不同分片大小和并发数的实测数据整理了一下方便你根据自己的带宽做决策文件大小分片大小并发分片数总耗时带宽利用率备注1GB5MB3约42s约75%请求数太多HTTP开销明显1GB10MB3约32s约88%推荐组合1GB10MB5约29s约92%带宽好的情况下最佳1GB20MB3约35s约80%分片大单片失败重传成本高1GB50MB2约45s约65%分片太大失去并发优势结论是分片大小10MB、并发数3到5是性价比最高的区间。分片再小请求开销占比上升分片再大单片重传成本太高且并发很难跑满带宽。6.3 临时目录的自动清理策略孤儿分片是怎么产生的用户上传到一半退出、前端断网、浏览器崩溃都会导致临时分片永远留在磁盘上。我建议的清理策略是每个uploadId在创建时带上过期时间比如1天启动一个定时任务每小时扫描一次临时目录删除所有修改时间早于过期时间的.part文件同时把对应的Redis状态记录也清掉。Scheduled(cron 0 0 * * * ?) public void cleanExpiredPartFiles() { try (StreamPath stream Files.list(Paths.get(tempDir))) { stream.filter(path - path.toString().endsWith(.part)) .filter(path - { try { return Files.getLastModifiedTime(path).toMillis() System.currentTimeMillis() - expireHours * 3600 * 1000L; } catch (IOException e) { return true; } }) .forEach(path - { try { Files.deleteIfExists(path); } catch (IOException ignored) { } }); } }别小看这个定时清理任务它能保证即使业务代码偶尔出问题磁盘也不会被垃圾分片拖垮。这套方案上线后我最深的体会是MD5秒传校验本身并不复杂复杂的是围绕它构建的整个上传链路的边界情况处理。插件化设计让我把这些边界情况都收敛在独立模块里主项目只需关注业务本身。最后再分享一个我在实践中替换算法的技巧如果你已经按插件化思路实现了UploadRecordStore和UploadDeduplicateService而某天产品要求支持秒传的同时计算文件的SHA-256你别去改Controller只需要在服务里加一个DigestType枚举然后把findByMd5AndSize替换成findByMd5AndSizeAndDigestType就行。这就是为什么我说插件化架构的核心收益不是“第一版跑多快”而是“第二版改多省”。