Java文件分片上传与下载实战：秒传、断点续传、并发合并与Range下载

①check   秒传/续传检查   → 已存在？已传哪些分片？
②chunk   分片上传        → 失败只重传该片
③merge   合并分片        → 校验完整性，落正式存储
④download 下载          → Range 断点续传 + 流式输出

CREATE TABLE file_info (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  file_md5    VARCHAR(32)  NOT NULL,           -- 秒传主键
  file_name   VARCHAR(255) NOT NULL,
  file_size   BIGINT       NOT NULL,
  file_path   VARCHAR(500) NOT NULL,
  status      TINYINT      NOT NULL DEFAULT 0, -- 0 上传中 1 完成
  uploader_id BIGINT       NOT NULL,
  create_time DATETIME     NOT NULL,
  UNIQUE KEY uk_md5 (file_md5)
);

CREATE TABLE file_chunk (
  id         BIGINT PRIMARY KEY AUTO_INCREMENT,
  file_md5   VARCHAR(32) NOT NULL,
  chunk_idx  INT         NOT NULL,
  chunk_size BIGINT      NOT NULL,
  UNIQUE KEY uk_md5_idx (file_md5, chunk_idx)
);

@RestController
@RequestMapping("/file")
@RequiredArgsConstructor
public class FileUploadController {

    private final FileInfoMapper fileInfoMapper;
    private final FileChunkMapper fileChunkMapper;
    private final FileStorageService storage;

    /** ① 秒传 + 断点续传检查 */
    @PostMapping("/check")
    public Result<UploadCheckVO> check(@RequestBody FileCheckReq req) {
        UploadCheckVO vo = new UploadCheckVO();
        // 秒传：同 MD5 文件已存在
        FileInfo exist = fileInfoMapper.selectOne(
                new LambdaQueryWrapper<FileInfo>().eq(FileInfo::getFileMd5, req.getMd5()));
        if (exist != null) {
            vo.setUploaded(true);
            vo.setFileId(exist.getId());
            return Result.ok(vo);
        }
        // 断点续传：返回已传分片索引集合
        vo.setUploaded(false);
        vo.setUploadedChunks(fileChunkMapper.selectList(
                        new LambdaQueryWrapper<FileChunk>().eq(FileChunk::getFileMd5, req.getMd5()))
                .stream().map(FileChunk::getChunkIdx).collect(Collectors.toSet()));
        return Result.ok(vo);
    }

    /** ② 单分片上传（幂等：同分片重复上传覆盖即可） */
    @PostMapping("/chunk")
    public Result<Void> uploadChunk(@RequestParam String md5,
                                    @RequestParam int chunkIdx,
                                    @RequestParam("file") MultipartFile part) throws IOException {
        // ⚠️ 路径安全：chunkIdx 必须校验范围，md5 必须正则校验，防目录穿越
        if (!md5.matches("[0-9a-f]{32}")) {
            return Result.fail("非法参数");
        }
        storage.saveChunk(md5, chunkIdx, part.getInputStream(), part.getSize());

        // 记录分片（幂等 upsert）
        fileChunkMapper.insert(new FileChunk()
                .setFileMd5(md5).setChunkIdx(chunkIdx).setChunkSize(part.getSize()));
        return Result.ok();
    }

    /** ③ 合并：顺序写 + 校验大小 + 校验 MD5 */
    @PostMapping("/merge")
    public Result<Long> merge(@RequestBody FileMergeReq req) throws Exception {
        String md5 = req.getMd5();
        File tmpDir = new File(storage.chunkDir(md5));
        File[] parts = tmpDir.listFiles((d, n) -> n.endsWith(".part"));
        if (parts == null || parts.length != req.getTotalChunks()) {
            return Result.fail("分片缺失，请重传");
        }

        File target = new File(storage.filePath(md5, req.getSuffix()));
        long total = 0;
        // ⚠️ 别用 Files.write 一次性读入 byte[]（OOM 元凶），用流式追加
        try (FileOutputStream fos = new FileOutputStream(target)) {
            for (int i = 0; i < req.getTotalChunks(); i++) {
                File part = new File(tmpDir, i + ".part");
                try (InputStream in = new FileInputStream(part)) {
                    total += in.transferTo(fos);     // 流式拷贝，JDK 21 transferTo
                }
            }
        }

        // 完整性校验：大小 + MD5（合并后重算一次）
        if (total != req.getTotalSize() || !req.getMd5().equals(storage.md5(target))) {
            target.delete();
            return Result.fail("文件校验失败");
        }

        Long fileId = storage.saveFileInfo(req, target);   // 落库 + 清理临时分片
        FileUtils.deleteDirectory(tmpDir);                 // 合并成功即清分片
        return Result.ok(fileId);
    }
}

// 切片（每片 5MB）
const CHUNK_SIZE = 5 * 1024 * 1024;
const chunks = [];
for (let i = 0; i * CHUNK_SIZE < file.size; i++) {
  chunks.push(file.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE));
}
// MD5 用 Web Worker 算（别卡主线程）；并发上传用 Promise 池（并发 3~4）
const { uploaded, uploadedChunks } = await axios.post('/file/check', { md5 });
if (uploaded) return;                                   // 秒传直接完成
await pool(3, chunks.map((c, i) =>
  uploadedChunks.has(i) ? Promise.resolve() :         // 断点续传跳过
    () => uploadChunk(md5, i, c)));                    // 失败自动重试 3 次
await axios.post('/file/merge', { md5, totalChunks: chunks.length, totalSize: file.size });

    /** ④ 支持 Range 的流式下载 */
    @GetMapping("/download/{id}")
    public void download(@PathVariable Long id,
                         HttpServletRequest request,
                         HttpServletResponse response) throws IOException {
        FileInfo info = fileInfoMapper.selectById(id);
        File file = new File(info.getFilePath());
        long fileLen = file.length();

        // 解析 Range 头：bytes=start-end
        String range = request.getHeader("Range");
        long start = 0, end = fileLen - 1;
        if (range != null && range.startsWith("bytes=")) {
            String[] parts = range.substring(6).split("-");
            start = Long.parseLong(parts[0]);
            if (parts.length > 1 && !parts[1].isEmpty()) {
                end = Long.parseLong(parts[1]);
            }
            response.setStatus(HttpStatus.PARTIAL_CONTENT.value());   // 206
            response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileLen);
        } else {
            response.setStatus(HttpStatus.OK.value());
        }

        response.setContentType("application/octet-stream");
        response.setHeader("Accept-Ranges", "bytes");
        // ⚠️ 中文文件名：RFC 5987 编码，直接放会乱码
        String encoded = URLEncoder.encode(info.getFileName(), StandardCharsets.UTF_8)
                .replace("+", "%20");
        response.setHeader("Content-Disposition",
                "attachment; filename*=UTF-8''" + encoded);
        response.setContentLengthLong(end - start + 1);

        // 流式输出（RandomAccessFile 支持从任意位置读）
        try (RandomAccessFile raf = new RandomAccessFile(file, "r")) {
            raf.seek(start);
            OutputStream out = response.getOutputStream();
            byte[] buf = new byte[8192];
            long remaining = end - start + 1;
            while (remaining > 0) {
                int read = raf.read(buf, 0, (int) Math.min(buf.length, remaining));
                if (read < 0) break;
                out.write(buf, 0, read);
                remaining -= read;
            }
        }
    }

location /file/download/ {
    proxy_buffering off;            # 大文件下载关缓冲
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range;
}

前端 → 向后端要"分片上传凭证"（STS 临时密钥/签名）
     → 直传 OSS（Multipart Upload，不占应用带宽）
     → 全部分片完成后调"合并"（OSS CompleteMultipartUpload）
     → 回调通知后端落库