写这篇的起因是上周帮朋友调一个内网文件上传接口。他们上传一个1.2GB的文件客户端用的是最朴素的MultipartFile转InputStream之后一把put。在办公室网络里测试一切正常结果到了真机环境传了十几分钟中间断了一次整个文件直接上传失败日志里只剩一行timeout。后来我把这部分改成分片上传同样的网络环境从“一半概率失败”变成了“基本都能传上去”。这篇文章就把这套基于 Java 的 MinIO 分片上传工具类和测试 demo 的完整思路写下来包括为什么非分片不可、SDK 底层机制、工具类怎么设计、用什么方式验证以及我实际调试中踩过的几个坑。1. 大文件直接PUT上传为什么迟早会出事先说结论大文件不是不能直接传而是不可靠。这里说的“不可靠”不是 MinIO 本身的问题而是网络、内存、超时这些现实因素叠加在一起导致简单的单请求上传在文件体积变大之后会越来越难用。1.1 整个文件读进内存是不可控的很多第一次接触对象存储的人写上传代码的时候很自然就想到“把文件转成 byte[]再交给 SDK”。文件小的时候没问题文件一旦到了 500MB、1GB问题立刻浮现。一个byte[]会占用连续内存JVM 堆稍微小一点就直接OutOfMemoryError堆调得大一点又会影响整台机器的 GC 表现。就算你用的是InputStream只要 SDK 底层为了计算 MD5 或者做重试把流缓存了大对象照样会把内存吃穿。你可能说“我用FileInputStream传就行了”确实可以但这只是解决了内存路径没有解决网络路径的问题。1.2 网络抖动一次整批重来单请求上传大文件意味着这个 HTTP 连接要保持很久。内网环境可能还好一旦经过公网、跨机房、或者中间有防火墙和负载均衡长连接很容易被某些网络设备掐掉。TCP 层断了客户端可能根本感知不到等服务端迟迟没有响应、触发超时的时候整个上传已经失败了。更难受的是这种失败几乎是不可恢复的——你得重新发起一次完整上传前面传出去的全部白费。对 GB 级别的文件来说重试成本太高了尤其是移动网络或者弱网环境进行到 90% 再断一次心态直接爆炸。1.3 串行传输浪费了本可以并行的带宽单个连接传输时TCP 的拥塞控制会限制吞吐量。哪怕服务器带宽足够单连接也很难跑满。而分片上传可以做到多分片并行把整体传输时间从“文件大小 / 单连接速度”变成“文件大小 / 多连接聚合速度”。这在文件越大、网络质量越好的场景下差异越明显。所以分片上传解决的其实是一组问题内存可控、失败可重试、传输可并发。这也是为什么 S3 协议和 MinIO 都会把 Multipart Upload 作为标准能力。我们自己写工具类本质就是把这种能力从“SDK 内部行为”变成“自己掌控的流程”。2. MinIO的Multipart Upload机制还有Java SDK里能用的方法如果你用过 MinIO Java SDK会发现它的高层putObject方法也支持大文件而且流式上传超过某个阈值会自动走分片。那自己写工具类还有没有意义我的判断是如果只是“能传上去”高层 API 就够了如果需要“看得见进度、能恢复、能控制并发”就必须亲自操作 Multipart Upload 的完整生命周期。2.1 一次分片上传的完整生命周期分片上传在 S3 兼容对象存储里的流程是固定的分为四步初始化上传调用createMultipartUpload服务端返回一个uploadId这个 ID 标识了这次未完成的上传任务。上传分片把文件切割成多段逐段调用uploadPart每一段都带上同一个uploadId和分片序号服务端返回每个分片的 ETag。完成上传把所有分片的 ETag 按序号整理成列表调用completeMultipartUpload服务端会把这些分片组合成最终对象。中止上传如果中途失败且不打算继续了调用abortMultipartUpload服务端会清理残留分片。这四步的对应关系如下。生命周期阶段核心操作关键返回值初始化createMultipartUploaduploadId上传片段uploadPart每个分片的 ETag合并分片completeMultipartUpload最终对象元数据清理残留abortMultipartUpload无2.2 Java SDK 中直接操作分片的方法以 minio-java 8.5.x 为例MinioClient直接暴露了这些方法// 初始化返回 uploadId CreateMultipartUploadResponse initResp client.createMultipartUpload(bucket, null, object, Map.of(), Map.of()); String uploadId initResp.result().uploadId(); // 上传单个分片返回该分片 ETag UploadPartResponse partResp client.uploadPart(bucket, null, object, partStream, partLength, partNumber, uploadId, Map.of(), Map.of()); // 完成所有分片 client.completeMultipartUpload(bucket, null, object, uploadId, partList, Map.of(), Map.of()); // 中止上传 client.abortMultipartUpload(bucket, null, object, uploadId, Map.of(), Map.of());使用这些方法的时候有一个前提就是分片本身要被包装成能准确报告size的InputStream而且这个流必须能完整读出对应长度的数据。SDK 内部在做签名和网络请求时会依赖这个长度信息长度对不上服务端要么报错要么挂起等待更多数据。我自己封装工具类的时候还额外用了RandomAccessFile来定位文件偏移量。这样就能做到“只读某一段分片”而不是把整个文件都读到内存里。分片大小控制在 5MiB 到 50MiB 之间每次读入内存的只有当前分片的大小对 JVM 非常友好。3. 工具类落地接口设计、分片计算和核心实现3.1 对外接口应该长什么样工具类不能只为了自己爽还要考虑同事接手的成本。我倾向于对外只暴露一个方法传入桶名、对象名、文件对象和希望的分片大小让内部去处理分片、合并和异常清理。调用方不需要知道uploadId是什么也不需要关心 ETag 怎么排序这些都是工具类内部的事。public class MinioPartUploadUtils { public void uploadWithParts(String bucket, String object, File file, long customPartSize) throws Exception { // 内部处理全部流程 } }如果后续需要进度回调再额外增加一个BiConsumerLong, Long之类的参数把“已上传字节数”和“总字节数”暴露给调用方。初期版本先把主流程跑通最重要。3.2 分片大小怎么算才合理S3 协议对分片有两个硬约束除了最后一个分片其余分片大小不能小于 5MiB整个对象的分片数量最多 10000 个。MinIO 继承了这个约束。所以工具类里必须做一次自适应计算long partSize Math.max(customPartSize, MIN_PART_SIZE); // 5MiB int partCount (int) ((fileSize partSize - 1) / partSize); if (partCount MAX_PART_COUNT) { // 10000 partSize (fileSize MAX_PART_COUNT - 1) / MAX_PART_COUNT; partSize ((partSize MIN_PART_SIZE - 1) / MIN_PART_SIZE) * MIN_PART_SIZE; partCount (int) ((fileSize partSize - 1) / partSize); }如果调用方传的customPartSize太小直接拉到 5MiB。如果文件太大导致分片数量超过 10000就自动把分片大小往上调。这里把partSize对齐到 5MiB 的整数倍是为了避免出现非最后分片不足 5MiB 的边界问题。实际项目里我一般默认 10MiB 或 20MiB太大反而会增加单分片重试的失败代价。3.3 核心代码实现下面是一个简化但完整可用的工具类。为控制篇幅我去掉了多余的校验和日志重点保留流程。import io.minio.*; import io.minio.messages.Part; import java.io.*; import java.util.*; public class MinioPartUploadUtils { public static final long MIN_PART_SIZE 5L * 1024 * 1024; public static final int MAX_PART_COUNT 10000; private final MinioClient client; public MinioPartUploadUtils(MinioClient client) { this.client client; } public void uploadWithParts(String bucket, String object, File file, long customPartSize) throws Exception { long fileSize file.length(); long partSize Math.max(customPartSize, MIN_PART_SIZE); int partCount (int) ((fileSize partSize - 1) / partSize); if (partCount MAX_PART_COUNT) { partSize (fileSize MAX_PART_COUNT - 1) / MAX_PART_COUNT; partSize ((partSize MIN_PART_SIZE - 1) / MIN_PART_SIZE) * MIN_PART_SIZE; partCount (int) ((fileSize partSize - 1) / partSize); } System.out.printf(文件大小%d, 分片大小%d, 分片数量%d%n, fileSize, partSize, partCount); // 1. 初始化上传 CreateMultipartUploadResponse initResp client.createMultipartUpload( bucket, null, object, Map.of(), Map.of()); String uploadId initResp.result().uploadId(); ListPart parts new ArrayList(); try { // 2. 逐分片上传 for (int partNumber 1; partNumber partCount; partNumber) { long offset (long) (partNumber - 1) * partSize; long length Math.min(partSize, fileSize - offset); try (RandomAccessFile raf new RandomAccessFile(file, r)) { raf.seek(offset); byte[] buffer new byte[(int) length]; raf.readFully(buffer); try (InputStream partStream new ByteArrayInputStream(buffer)) { UploadPartResponse partResp client.uploadPart( bucket, null, object, partStream, length, partNumber, uploadId, Map.of(), Map.of()); parts.add(new Part(partNumber, partResp.etag())); System.out.println(分片 partNumber / partCount 完成); } } } // 3. 完成上传 client.completeMultipartUpload( bucket, null, object, uploadId, parts, Map.of(), Map.of()); System.out.println(上传完毕); } catch (Exception e) { // 4. 失败时清理服务端残留 client.abortMultipartUpload(bucket, null, object, uploadId, Map.of(), Map.of()); throw e; } } }这段代码有几个地方值得解释一下。为什么用RandomAccessFile因为它支持seek可以精确跳到文件的指定偏移量去读分片数据比每次打开一个全新的FileInputStream再 skip n 个字节要高效可靠。为什么每轮都重新打开RandomAccessFile这个其实不是必须的我在多线程版本里会让每个线程各持有一个独立的RandomAccessFile避免共享指针互相干扰单线程下只需要在循环外打开一次即可。为什么分片读出来要包一层ByteArrayInputStream因为uploadPart需要的是一个能返回精确size的InputStream而ByteArrayInputStream是最简单可靠的选择。这里有个隐含代价每片数据都会在内存里留一份副本。如果分片大小控制在 10MiB 到 20MiB完全没问题但如果有人为了减少请求次数把分片调到 500MiB这里就会成为新的内存瓶颈。所以我的建议是分片大小别贪大保持“可重试粒度”比“最少请求次数”更重要。4. 测试demo用Docker跑起MinIO把流程完整验证一遍工具类写完之后不能只在单元测试里 mock最好还是连一个真实服务跑一遍。我平时最常用的方式是本地 Docker 起一个 MinIO然后写一个简单的main方法去执行分片上传。4.1 一条命令把MinIO跑起来MinIO 官方镜像支持两条端口9000是 API 端口9001是控制台端口。docker run -d --name minio-demo \ -p 9000:9000 \ -p 9001:9001 \ -e MINIO_ROOT_USERminioadmin \ -e MINIO_ROOT_PASSWORDminioadmin \ -v /data/minio:/data \ minio/minio server /data --console-address :9001启动完成后访问http://127.0.0.1:9001就能看到控制台用户名和密码都是minioadmin。如果我们只是为了验证上传流程控制台可不看API 端口能用就行。4.2 准备一个几GB的测试文件测试文件不需要真的有含义只要体积够大、内容随机就能模拟真实场景。Linux 或 macOS 下用dd生成一个 300MB 的随机文件mkdir -p /tmp/upload-test dd if/dev/urandom of/tmp/upload-test/bigfile.bin bs1M count300这个文件生成后后续每次上传的 MD5 都是随机的我们不需要校验内容只要确认对象在 MinIO 里存在且大小正确即可。4.3 编写并执行测试入口接下来在项目里写一个简单的入口类。为了让代码能直接跑我把它做成main方法而不是 JUnit 测试因为很多人对Test方法怎么获取MinioClient还存在一点理解成本直接main最直白。public class MinioPartUploadDemo { public static void main(String[] args) throws Exception { MinioClient client MinioClient.builder() .endpoint(http://127.0.0.1:9000) .credentials(minioadmin, minioadmin) .build(); String bucket demo-bucket; // 桶不存在就创建 boolean exists client.bucketExists( BucketExistsArgs.builder().bucket(bucket).build()); if (!exists) { client.makeBucket( MakeBucketArgs.builder().bucket(bucket).build()); } File file new File(/tmp/upload-test/bigfile.bin); MinioPartUploadUtils utils new MinioPartUploadUtils(client); long start System.currentTimeMillis(); utils.uploadWithParts(bucket, dir/bigfile.bin, file, 10L * 1024 * 1024); long cost System.currentTimeMillis() - start; System.out.println(耗时: cost ms); } }执行时注意两点一是 pom 或 gradle 要引入 minio SDK 依赖二是 Java 版本要在 8 以上。如果项目里已经有 Spring Boot直接注入MinioClient也行但测试 demo 里用main方法独立跑隔离性更好。跑完控制台会输出每一片的上传结果最后打印“上传完毕”。如果看到这个输出说明工具类的完整流程已经通了。然后我们可以顺手验证一下 MinIO 服务端的对象情况。4.4 用控制台和命令行交叉验证最直接的验证方式是打开控制台进入demo-bucket看到dir/bigfile.bin这个对象右侧会显示大小 300MB。这里要注意一个细节分片上传完成后生成的 ETag 和普通单请求上传不一样它往往带一个-N后缀比如f2f1...-24后面的24表示 24 个分片。这个现象是正常的分片上传标记别当成 bug。如果用 MinIO 客户端命令行工具mc可以这样验证mc alias set local http://127.0.0.1:9000 minioadmin minioadmin mc ls local/demo-bucket/dir/ mc stat local/demo-bucket/dir/bigfile.binmc stat会显示对象大小、最后修改时间、ETag。只要大小正确、对象存在就说明工具类的完成流程没有遗漏。5. 踩坑实录调试分片上传时遇到的五种意外状况这部分我觉得价值不低于工具类本身。下面五个问题都是我在实际调试中真实遇到过、并且花了不少时间才定位到根因的。5.1 非最后一个分片小于5MiB上传直接报错第一次写分片逻辑时我没做最小大小限制用户传 2MiB 就按 2MiB 切。结果上传大概 30 个分片之后某个分片突然报InvalidPart错误码一看是EntityTooSmall。我当时还奇怪最后一片可以小于 5MiB为什么中间某一片报这个后来查了文档才意识到服务端对除最后一个分片之外的所有分片都要求不小于 5MiB。我的计算方式里如果partSize本身小于 5MiB那中间大片全是非法分片。解决方式就是工具类里那句Math.max(customPartSize, MIN_PART_SIZE)先把入口卡死不给非法值流入后续逻辑。5.2 completeMultipartUpload时ETag顺序反了第二次踩坑更隐蔽。我当时图省事用一个MapInteger, String存分片结果然后转成ListPart时直接遍历了 Map。结果因为 HashMap 的迭代顺序不可控传到completeMultipartUpload里面的分片列表顺序是乱的。服务端没有报错最终对象也创建了但下载下来发现文件 CRC 校验不过、内容根本没法用。这类问题最可怕的地方在于“半成功”——对象存在数据却是坏的。排查方式是用mc stat看 ETag 的后缀分片数再去控制台下载对比。从此之后我统一用一个ArrayList严格按照partNumber顺序添加绝不依赖 Map 迭代顺序。5.3 上传中途失败后服务端会残留“孤儿分片”如果你按照我上面的工具类写法catch 块里会调用abortMultipartUpload这个流程会把服务端残留分片清理掉。但真实项目里客户端可能直接崩了、断电了根本没有机会执行 abort。这种情况下MinIO 服务端会一直保留未完成的分片数据日积月累下来会白白占用大量存储空间。所以工具类能做的只是“尽力而为”更稳妥的方案是服务端定期执行一次生命周期清理规则。MinIO 支持给桶配置生命周期规则把带有incomplete-upload标签的对象在指定天数后删除。这个配置可以在控制台的 Bucket Lifecycle 里加如果你们公司用的是自己搭的 MinIO这块必须提前考虑。5.4 并发上传分片时RandomAccessFile指针互相干扰为了让上传再快一点我把单线程循环改成了线程池并发上传 5 个分片。结果一开始就出问题因为多个线程共用同一个RandomAccessFile线程 A 调seek之后线程 B 也调seek两个线程的读取位置全部混乱上传出去的分片数据张冠李戴。解决方式有两个。一是每个线程独立打开RandomAccessFile只在自己的偏移区间内读取二是不用RandomAccessFile改用FileChannel加position参数每次读取时显式指定位置。无论哪种方式核心原则是一样的文件指针不能被多个线程共享。工具类里写成每次循环都打开一次RandomAccessFile的原因就在这里——虽然性能上会有一点损耗但换来了绝对的并发安全。5.5 临时凭证过期导致分片上传时间不够如果项目里使用 STS 临时凭证访问 MinIO这里还有一个隐蔽问题临时凭证默认有效期可能只有几十分钟。正常对象上传几秒钟就结束了无所谓但一个几 GB 的文件串行分片上传可能跑一两个小时。追加上传只能追溯到凭证签发时间凭证过期之后再调uploadPart就会返回AccessDenied。这种场景下要么调大临时凭证过期时间要么把上传逻辑拆成“预签名 URL 前端直传”要么采用更细粒度的“定期刷新凭证”机制。后者实现复杂一般团队用不上所以我平时在项目里会先确认临时凭证的过期时间是否覆盖整个上传周期。如果覆盖不了直接改用长期 AccessKey 做服务端上传反而更省事。6. 生产环境真正上线前值得再补充的几个能力工具类跑通 demo 只是第一步。真实生产环境里有几个点是我建议在上线前就补上的否则后续大概率要返工。6.1 进度回调用户上传大文件时最关心的是“现在传到哪里了”。工具类里可以在每个分片上传完后累计已上传字节数然后回调一个进度接口。比如用BiConsumerLong, Long第一个参数是已上传字节数第二个是文件总字节数调用方可以拿去刷新进度条或者写日志。6.2 断点续传分片上传天然支持断点续传每次初始化时拿到uploadId信息持久化到数据库或 Redis。下次再传同一个文件时先调用listParts查询服务端已有的分片跳过已经完成的分片只续传缺失部分。这个功能听起来很香但实现时要注意清理过期uploadId否则数据库里会积攒大量无效记录。6.3 预签名URL直传如果上传是发生在浏览器或手机端让文件先经过后端再转存到 MinIO 会浪费很多带宽。更合理的方案是后端生成预签名 URL客户端直传 MinIO。针对分片上传MinIO 同样支持生成分片维度的预签名 URL前端可以并行把分片直传到对象存储最后由后端回调完成合并。这套方案比服务端中转复杂不少但带宽成本和响应速度都有明显改善。6.4 上传元数据的扩展分片上传完成后我们通常还想记录文件原始文件名、上传用户、业务 ID 等信息。MinIO 的对象元数据自定义 Header可以承载这些信息。在createMultipartUpload阶段就设置好元数据最终合并出来的对象就会带着这些信息。后续做对象检索、事件通知时都会方便很多。我在实际项目里的习惯是先把工具类做成内部公共组件进度回调、断点续传、预签名 URL 这些都作为独立接口扩展而不是一开始就塞进一个巨型类里。这样既保证 demo 能快速跑通又不会牺牲后续的可维护性。如果你正打算接 MinIO 分片上传建议先复制这套流程完整跑一遍再按自己的业务场景做裁剪。
Java实现MinIO分片上传：从原理到工具类实战
写这篇的起因是上周帮朋友调一个内网文件上传接口。他们上传一个1.2GB的文件客户端用的是最朴素的MultipartFile转InputStream之后一把put。在办公室网络里测试一切正常结果到了真机环境传了十几分钟中间断了一次整个文件直接上传失败日志里只剩一行timeout。后来我把这部分改成分片上传同样的网络环境从“一半概率失败”变成了“基本都能传上去”。这篇文章就把这套基于 Java 的 MinIO 分片上传工具类和测试 demo 的完整思路写下来包括为什么非分片不可、SDK 底层机制、工具类怎么设计、用什么方式验证以及我实际调试中踩过的几个坑。1. 大文件直接PUT上传为什么迟早会出事先说结论大文件不是不能直接传而是不可靠。这里说的“不可靠”不是 MinIO 本身的问题而是网络、内存、超时这些现实因素叠加在一起导致简单的单请求上传在文件体积变大之后会越来越难用。1.1 整个文件读进内存是不可控的很多第一次接触对象存储的人写上传代码的时候很自然就想到“把文件转成 byte[]再交给 SDK”。文件小的时候没问题文件一旦到了 500MB、1GB问题立刻浮现。一个byte[]会占用连续内存JVM 堆稍微小一点就直接OutOfMemoryError堆调得大一点又会影响整台机器的 GC 表现。就算你用的是InputStream只要 SDK 底层为了计算 MD5 或者做重试把流缓存了大对象照样会把内存吃穿。你可能说“我用FileInputStream传就行了”确实可以但这只是解决了内存路径没有解决网络路径的问题。1.2 网络抖动一次整批重来单请求上传大文件意味着这个 HTTP 连接要保持很久。内网环境可能还好一旦经过公网、跨机房、或者中间有防火墙和负载均衡长连接很容易被某些网络设备掐掉。TCP 层断了客户端可能根本感知不到等服务端迟迟没有响应、触发超时的时候整个上传已经失败了。更难受的是这种失败几乎是不可恢复的——你得重新发起一次完整上传前面传出去的全部白费。对 GB 级别的文件来说重试成本太高了尤其是移动网络或者弱网环境进行到 90% 再断一次心态直接爆炸。1.3 串行传输浪费了本可以并行的带宽单个连接传输时TCP 的拥塞控制会限制吞吐量。哪怕服务器带宽足够单连接也很难跑满。而分片上传可以做到多分片并行把整体传输时间从“文件大小 / 单连接速度”变成“文件大小 / 多连接聚合速度”。这在文件越大、网络质量越好的场景下差异越明显。所以分片上传解决的其实是一组问题内存可控、失败可重试、传输可并发。这也是为什么 S3 协议和 MinIO 都会把 Multipart Upload 作为标准能力。我们自己写工具类本质就是把这种能力从“SDK 内部行为”变成“自己掌控的流程”。2. MinIO的Multipart Upload机制还有Java SDK里能用的方法如果你用过 MinIO Java SDK会发现它的高层putObject方法也支持大文件而且流式上传超过某个阈值会自动走分片。那自己写工具类还有没有意义我的判断是如果只是“能传上去”高层 API 就够了如果需要“看得见进度、能恢复、能控制并发”就必须亲自操作 Multipart Upload 的完整生命周期。2.1 一次分片上传的完整生命周期分片上传在 S3 兼容对象存储里的流程是固定的分为四步初始化上传调用createMultipartUpload服务端返回一个uploadId这个 ID 标识了这次未完成的上传任务。上传分片把文件切割成多段逐段调用uploadPart每一段都带上同一个uploadId和分片序号服务端返回每个分片的 ETag。完成上传把所有分片的 ETag 按序号整理成列表调用completeMultipartUpload服务端会把这些分片组合成最终对象。中止上传如果中途失败且不打算继续了调用abortMultipartUpload服务端会清理残留分片。这四步的对应关系如下。生命周期阶段核心操作关键返回值初始化createMultipartUploaduploadId上传片段uploadPart每个分片的 ETag合并分片completeMultipartUpload最终对象元数据清理残留abortMultipartUpload无2.2 Java SDK 中直接操作分片的方法以 minio-java 8.5.x 为例MinioClient直接暴露了这些方法// 初始化返回 uploadId CreateMultipartUploadResponse initResp client.createMultipartUpload(bucket, null, object, Map.of(), Map.of()); String uploadId initResp.result().uploadId(); // 上传单个分片返回该分片 ETag UploadPartResponse partResp client.uploadPart(bucket, null, object, partStream, partLength, partNumber, uploadId, Map.of(), Map.of()); // 完成所有分片 client.completeMultipartUpload(bucket, null, object, uploadId, partList, Map.of(), Map.of()); // 中止上传 client.abortMultipartUpload(bucket, null, object, uploadId, Map.of(), Map.of());使用这些方法的时候有一个前提就是分片本身要被包装成能准确报告size的InputStream而且这个流必须能完整读出对应长度的数据。SDK 内部在做签名和网络请求时会依赖这个长度信息长度对不上服务端要么报错要么挂起等待更多数据。我自己封装工具类的时候还额外用了RandomAccessFile来定位文件偏移量。这样就能做到“只读某一段分片”而不是把整个文件都读到内存里。分片大小控制在 5MiB 到 50MiB 之间每次读入内存的只有当前分片的大小对 JVM 非常友好。3. 工具类落地接口设计、分片计算和核心实现3.1 对外接口应该长什么样工具类不能只为了自己爽还要考虑同事接手的成本。我倾向于对外只暴露一个方法传入桶名、对象名、文件对象和希望的分片大小让内部去处理分片、合并和异常清理。调用方不需要知道uploadId是什么也不需要关心 ETag 怎么排序这些都是工具类内部的事。public class MinioPartUploadUtils { public void uploadWithParts(String bucket, String object, File file, long customPartSize) throws Exception { // 内部处理全部流程 } }如果后续需要进度回调再额外增加一个BiConsumerLong, Long之类的参数把“已上传字节数”和“总字节数”暴露给调用方。初期版本先把主流程跑通最重要。3.2 分片大小怎么算才合理S3 协议对分片有两个硬约束除了最后一个分片其余分片大小不能小于 5MiB整个对象的分片数量最多 10000 个。MinIO 继承了这个约束。所以工具类里必须做一次自适应计算long partSize Math.max(customPartSize, MIN_PART_SIZE); // 5MiB int partCount (int) ((fileSize partSize - 1) / partSize); if (partCount MAX_PART_COUNT) { // 10000 partSize (fileSize MAX_PART_COUNT - 1) / MAX_PART_COUNT; partSize ((partSize MIN_PART_SIZE - 1) / MIN_PART_SIZE) * MIN_PART_SIZE; partCount (int) ((fileSize partSize - 1) / partSize); }如果调用方传的customPartSize太小直接拉到 5MiB。如果文件太大导致分片数量超过 10000就自动把分片大小往上调。这里把partSize对齐到 5MiB 的整数倍是为了避免出现非最后分片不足 5MiB 的边界问题。实际项目里我一般默认 10MiB 或 20MiB太大反而会增加单分片重试的失败代价。3.3 核心代码实现下面是一个简化但完整可用的工具类。为控制篇幅我去掉了多余的校验和日志重点保留流程。import io.minio.*; import io.minio.messages.Part; import java.io.*; import java.util.*; public class MinioPartUploadUtils { public static final long MIN_PART_SIZE 5L * 1024 * 1024; public static final int MAX_PART_COUNT 10000; private final MinioClient client; public MinioPartUploadUtils(MinioClient client) { this.client client; } public void uploadWithParts(String bucket, String object, File file, long customPartSize) throws Exception { long fileSize file.length(); long partSize Math.max(customPartSize, MIN_PART_SIZE); int partCount (int) ((fileSize partSize - 1) / partSize); if (partCount MAX_PART_COUNT) { partSize (fileSize MAX_PART_COUNT - 1) / MAX_PART_COUNT; partSize ((partSize MIN_PART_SIZE - 1) / MIN_PART_SIZE) * MIN_PART_SIZE; partCount (int) ((fileSize partSize - 1) / partSize); } System.out.printf(文件大小%d, 分片大小%d, 分片数量%d%n, fileSize, partSize, partCount); // 1. 初始化上传 CreateMultipartUploadResponse initResp client.createMultipartUpload( bucket, null, object, Map.of(), Map.of()); String uploadId initResp.result().uploadId(); ListPart parts new ArrayList(); try { // 2. 逐分片上传 for (int partNumber 1; partNumber partCount; partNumber) { long offset (long) (partNumber - 1) * partSize; long length Math.min(partSize, fileSize - offset); try (RandomAccessFile raf new RandomAccessFile(file, r)) { raf.seek(offset); byte[] buffer new byte[(int) length]; raf.readFully(buffer); try (InputStream partStream new ByteArrayInputStream(buffer)) { UploadPartResponse partResp client.uploadPart( bucket, null, object, partStream, length, partNumber, uploadId, Map.of(), Map.of()); parts.add(new Part(partNumber, partResp.etag())); System.out.println(分片 partNumber / partCount 完成); } } } // 3. 完成上传 client.completeMultipartUpload( bucket, null, object, uploadId, parts, Map.of(), Map.of()); System.out.println(上传完毕); } catch (Exception e) { // 4. 失败时清理服务端残留 client.abortMultipartUpload(bucket, null, object, uploadId, Map.of(), Map.of()); throw e; } } }这段代码有几个地方值得解释一下。为什么用RandomAccessFile因为它支持seek可以精确跳到文件的指定偏移量去读分片数据比每次打开一个全新的FileInputStream再 skip n 个字节要高效可靠。为什么每轮都重新打开RandomAccessFile这个其实不是必须的我在多线程版本里会让每个线程各持有一个独立的RandomAccessFile避免共享指针互相干扰单线程下只需要在循环外打开一次即可。为什么分片读出来要包一层ByteArrayInputStream因为uploadPart需要的是一个能返回精确size的InputStream而ByteArrayInputStream是最简单可靠的选择。这里有个隐含代价每片数据都会在内存里留一份副本。如果分片大小控制在 10MiB 到 20MiB完全没问题但如果有人为了减少请求次数把分片调到 500MiB这里就会成为新的内存瓶颈。所以我的建议是分片大小别贪大保持“可重试粒度”比“最少请求次数”更重要。4. 测试demo用Docker跑起MinIO把流程完整验证一遍工具类写完之后不能只在单元测试里 mock最好还是连一个真实服务跑一遍。我平时最常用的方式是本地 Docker 起一个 MinIO然后写一个简单的main方法去执行分片上传。4.1 一条命令把MinIO跑起来MinIO 官方镜像支持两条端口9000是 API 端口9001是控制台端口。docker run -d --name minio-demo \ -p 9000:9000 \ -p 9001:9001 \ -e MINIO_ROOT_USERminioadmin \ -e MINIO_ROOT_PASSWORDminioadmin \ -v /data/minio:/data \ minio/minio server /data --console-address :9001启动完成后访问http://127.0.0.1:9001就能看到控制台用户名和密码都是minioadmin。如果我们只是为了验证上传流程控制台可不看API 端口能用就行。4.2 准备一个几GB的测试文件测试文件不需要真的有含义只要体积够大、内容随机就能模拟真实场景。Linux 或 macOS 下用dd生成一个 300MB 的随机文件mkdir -p /tmp/upload-test dd if/dev/urandom of/tmp/upload-test/bigfile.bin bs1M count300这个文件生成后后续每次上传的 MD5 都是随机的我们不需要校验内容只要确认对象在 MinIO 里存在且大小正确即可。4.3 编写并执行测试入口接下来在项目里写一个简单的入口类。为了让代码能直接跑我把它做成main方法而不是 JUnit 测试因为很多人对Test方法怎么获取MinioClient还存在一点理解成本直接main最直白。public class MinioPartUploadDemo { public static void main(String[] args) throws Exception { MinioClient client MinioClient.builder() .endpoint(http://127.0.0.1:9000) .credentials(minioadmin, minioadmin) .build(); String bucket demo-bucket; // 桶不存在就创建 boolean exists client.bucketExists( BucketExistsArgs.builder().bucket(bucket).build()); if (!exists) { client.makeBucket( MakeBucketArgs.builder().bucket(bucket).build()); } File file new File(/tmp/upload-test/bigfile.bin); MinioPartUploadUtils utils new MinioPartUploadUtils(client); long start System.currentTimeMillis(); utils.uploadWithParts(bucket, dir/bigfile.bin, file, 10L * 1024 * 1024); long cost System.currentTimeMillis() - start; System.out.println(耗时: cost ms); } }执行时注意两点一是 pom 或 gradle 要引入 minio SDK 依赖二是 Java 版本要在 8 以上。如果项目里已经有 Spring Boot直接注入MinioClient也行但测试 demo 里用main方法独立跑隔离性更好。跑完控制台会输出每一片的上传结果最后打印“上传完毕”。如果看到这个输出说明工具类的完整流程已经通了。然后我们可以顺手验证一下 MinIO 服务端的对象情况。4.4 用控制台和命令行交叉验证最直接的验证方式是打开控制台进入demo-bucket看到dir/bigfile.bin这个对象右侧会显示大小 300MB。这里要注意一个细节分片上传完成后生成的 ETag 和普通单请求上传不一样它往往带一个-N后缀比如f2f1...-24后面的24表示 24 个分片。这个现象是正常的分片上传标记别当成 bug。如果用 MinIO 客户端命令行工具mc可以这样验证mc alias set local http://127.0.0.1:9000 minioadmin minioadmin mc ls local/demo-bucket/dir/ mc stat local/demo-bucket/dir/bigfile.binmc stat会显示对象大小、最后修改时间、ETag。只要大小正确、对象存在就说明工具类的完成流程没有遗漏。5. 踩坑实录调试分片上传时遇到的五种意外状况这部分我觉得价值不低于工具类本身。下面五个问题都是我在实际调试中真实遇到过、并且花了不少时间才定位到根因的。5.1 非最后一个分片小于5MiB上传直接报错第一次写分片逻辑时我没做最小大小限制用户传 2MiB 就按 2MiB 切。结果上传大概 30 个分片之后某个分片突然报InvalidPart错误码一看是EntityTooSmall。我当时还奇怪最后一片可以小于 5MiB为什么中间某一片报这个后来查了文档才意识到服务端对除最后一个分片之外的所有分片都要求不小于 5MiB。我的计算方式里如果partSize本身小于 5MiB那中间大片全是非法分片。解决方式就是工具类里那句Math.max(customPartSize, MIN_PART_SIZE)先把入口卡死不给非法值流入后续逻辑。5.2 completeMultipartUpload时ETag顺序反了第二次踩坑更隐蔽。我当时图省事用一个MapInteger, String存分片结果然后转成ListPart时直接遍历了 Map。结果因为 HashMap 的迭代顺序不可控传到completeMultipartUpload里面的分片列表顺序是乱的。服务端没有报错最终对象也创建了但下载下来发现文件 CRC 校验不过、内容根本没法用。这类问题最可怕的地方在于“半成功”——对象存在数据却是坏的。排查方式是用mc stat看 ETag 的后缀分片数再去控制台下载对比。从此之后我统一用一个ArrayList严格按照partNumber顺序添加绝不依赖 Map 迭代顺序。5.3 上传中途失败后服务端会残留“孤儿分片”如果你按照我上面的工具类写法catch 块里会调用abortMultipartUpload这个流程会把服务端残留分片清理掉。但真实项目里客户端可能直接崩了、断电了根本没有机会执行 abort。这种情况下MinIO 服务端会一直保留未完成的分片数据日积月累下来会白白占用大量存储空间。所以工具类能做的只是“尽力而为”更稳妥的方案是服务端定期执行一次生命周期清理规则。MinIO 支持给桶配置生命周期规则把带有incomplete-upload标签的对象在指定天数后删除。这个配置可以在控制台的 Bucket Lifecycle 里加如果你们公司用的是自己搭的 MinIO这块必须提前考虑。5.4 并发上传分片时RandomAccessFile指针互相干扰为了让上传再快一点我把单线程循环改成了线程池并发上传 5 个分片。结果一开始就出问题因为多个线程共用同一个RandomAccessFile线程 A 调seek之后线程 B 也调seek两个线程的读取位置全部混乱上传出去的分片数据张冠李戴。解决方式有两个。一是每个线程独立打开RandomAccessFile只在自己的偏移区间内读取二是不用RandomAccessFile改用FileChannel加position参数每次读取时显式指定位置。无论哪种方式核心原则是一样的文件指针不能被多个线程共享。工具类里写成每次循环都打开一次RandomAccessFile的原因就在这里——虽然性能上会有一点损耗但换来了绝对的并发安全。5.5 临时凭证过期导致分片上传时间不够如果项目里使用 STS 临时凭证访问 MinIO这里还有一个隐蔽问题临时凭证默认有效期可能只有几十分钟。正常对象上传几秒钟就结束了无所谓但一个几 GB 的文件串行分片上传可能跑一两个小时。追加上传只能追溯到凭证签发时间凭证过期之后再调uploadPart就会返回AccessDenied。这种场景下要么调大临时凭证过期时间要么把上传逻辑拆成“预签名 URL 前端直传”要么采用更细粒度的“定期刷新凭证”机制。后者实现复杂一般团队用不上所以我平时在项目里会先确认临时凭证的过期时间是否覆盖整个上传周期。如果覆盖不了直接改用长期 AccessKey 做服务端上传反而更省事。6. 生产环境真正上线前值得再补充的几个能力工具类跑通 demo 只是第一步。真实生产环境里有几个点是我建议在上线前就补上的否则后续大概率要返工。6.1 进度回调用户上传大文件时最关心的是“现在传到哪里了”。工具类里可以在每个分片上传完后累计已上传字节数然后回调一个进度接口。比如用BiConsumerLong, Long第一个参数是已上传字节数第二个是文件总字节数调用方可以拿去刷新进度条或者写日志。6.2 断点续传分片上传天然支持断点续传每次初始化时拿到uploadId信息持久化到数据库或 Redis。下次再传同一个文件时先调用listParts查询服务端已有的分片跳过已经完成的分片只续传缺失部分。这个功能听起来很香但实现时要注意清理过期uploadId否则数据库里会积攒大量无效记录。6.3 预签名URL直传如果上传是发生在浏览器或手机端让文件先经过后端再转存到 MinIO 会浪费很多带宽。更合理的方案是后端生成预签名 URL客户端直传 MinIO。针对分片上传MinIO 同样支持生成分片维度的预签名 URL前端可以并行把分片直传到对象存储最后由后端回调完成合并。这套方案比服务端中转复杂不少但带宽成本和响应速度都有明显改善。6.4 上传元数据的扩展分片上传完成后我们通常还想记录文件原始文件名、上传用户、业务 ID 等信息。MinIO 的对象元数据自定义 Header可以承载这些信息。在createMultipartUpload阶段就设置好元数据最终合并出来的对象就会带着这些信息。后续做对象检索、事件通知时都会方便很多。我在实际项目里的习惯是先把工具类做成内部公共组件进度回调、断点续传、预签名 URL 这些都作为独立接口扩展而不是一开始就塞进一个巨型类里。这样既保证 demo 能快速跑通又不会牺牲后续的可维护性。如果你正打算接 MinIO 分片上传建议先复制这套流程完整跑一遍再按自己的业务场景做裁剪。