Java MultipartFile 怎么落盘：临时文件、校验和清理的数据流

一个导入接口连续跑了两周后，运维发现 /var/app/upload-tmp 已经塞满。应用日志里没查到明显报错：大部分上传文件都正常入库，只有少数触发网络中断、格式不符合规则、文件移动失败的请求，留下了半截没处理完的临时文件。文件上传远不是把 MultipartFile 一次性写到目标位置这么简单；从请求体进入服务，到最终能被业务逻辑正常读取，中间至少要经过校验、临时落盘、命名、移动和清理几个边界环节。

临时目录变满，通常不是磁盘问题而是数据流断了

Spring 的 MultipartFile 表示一次 multipart 请求中的文件内容。官方接口说明也提醒：内容可能在内存或临时磁盘中，应用若想长期保存，需要自行复制到会话级或持久存储。把它直接交给数据库、对象存储或本地目录之前，先把数据流的链路拆开，后面出异常才能精准定位到该清理哪一段资源。

这时候别急着上来就加个定时删文件的脚本。先理清两个问题：所有临时文件的创建是不是都收敛到同一个专门目录？每个异常分支的逻辑，能不能明确判断自己当前持有的临时文件有没有走完归档流程？前者直接决定后续的清理范围，后者决定异常处理逻辑不会误删已经成功归档到持久目录的正常数据。

先给三类路径各定一个职责

这样拆分路径有个很直接的好处：出问题的时候不用到处翻找零散的文件。还留在临时目录里的文件，说明完全没走完归档流程；已经进到持久目录的文件，后续要跟着业务记录走生命周期，不会被通用的临时文件清理任务误碰。

最小落盘代码：先写临时文件，再移动

下面的示例把后缀白名单、大小上限校验、临时文件生成、持久存储键生成的逻辑都收拢在同一个明确的边界里。它不是能直接套用到所有场景的通用上传组件，病毒扫描、内容识别、对象存储对接、分片上传这类扩展能力，还是要根据自身业务需求另行开发；不过这套基础链路，能先把最常见的“半截无效文件”问题收敛到临时目录范围内处理。

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.Locale;
import java.util.Set;
import java.util.UUID;
import org.springframework.web.multipart.MultipartFile;

public Path store(MultipartFile file, Path tempRoot, Path dataRoot)
        throws IOException {
    if (file.isEmpty() || file.getSize() > 20L * 1024 * 1024) {
        throw new IllegalArgumentException("invalid upload size");
    }

    String suffix = allowedSuffix(file.getOriginalFilename());
    Files.createDirectories(tempRoot);
    Files.createDirectories(dataRoot);

    Path temp = Files.createTempFile(tempRoot, "upload-", suffix);
    try {
        try (InputStream input = file.getInputStream()) {
            Files.copy(input, temp, StandardCopyOption.REPLACE_EXISTING);
        }

        if (Files.size(temp) != file.getSize()) {
            throw new IOException("uploaded byte count changed");
        }

        Path target = dataRoot.resolve(UUID.randomUUID() + suffix);
        try {
            return Files.move(temp, target, StandardCopyOption.ATOMIC_MOVE);
        } catch (AtomicMoveNotSupportedException ignored) {
            return Files.move(temp, target);
        }
    } catch (IOException | RuntimeException error) {
        Files.deleteIfExists(temp);
        throw error;
    }
}

private String allowedSuffix(String originalName) {
    String name = originalName == null ? "" : originalName.toLowerCase(Locale.ROOT);
    if (name.endsWith(".pdf")) return ".pdf";
    if (name.endsWith(".png")) return ".png";
    throw new IllegalArgumentException("unsupported file type");
}

示例里没有直接把 getOriginalFilename() 赋值给 resolve 当存储名用，服务端最终用的文件名，只来自自动生成的UUID和经过校验确认的合法后缀，原始文件名如果需要给前端展示，可以单独写到数据库的业务字段里。这样本地的目录结构不会因为用户提交的特殊字符文件名出现意外，也不会出现不同用户上传的同名文件互相覆盖的问题。

原子移动不是万能开关

同一块文件系统里，ATOMIC_MOVE 能把“校验目标路径是否存在、移动文件”这两个动作收拢成一次文件系统级操作；但JDK文档里也明确说明，跨 FileStore 或者不同文件系统实现的场景下，这个方法大概率会抛出 AtomicMoveNotSupportedException 异常。所以示例里的降级移动逻辑，不是为了追求绝对的操作一致性，而是让应用能明确区分出“无法完成原子移动”和“其他IO异常”这两类问题。

生产环境里更值得留意的是目录部署方式。如果临时目录挂载在本地磁盘，持久目录单独挂载到另一块独立磁盘，常规的文件移动操作会退化成“先全量复制、再删除源文件”的逻辑。一旦这个过程中途出错，源文件和目标文件可能同时存在，而且目标文件大概率是不完整的。这时候不用急着下结论判定故障，先把临时文件路径、目标存储键、异常类型都完整记录到日志里，剩下的残留资源交给后续的定时清理任务处理就好。

清理策略要覆盖“请求没走完”的情况

业务方法里写的 Files.deleteIfExists 逻辑，能正常处理文件复制、尺寸校验、移动环节抛出的绝大多数异常，但它覆盖不了进程被强制重启、容器被销毁、请求长时间中断这类极端场景。临时目录还需要一套独立的清理规则：只扫描指定的专用临时目录、只删除超过预设保留时长的普通文件、删除前先校验文件名符合临时文件的命名规则，同时把本次清理的文件总数、失败的路径和原因都完整写到日志里。

1. 临时目录与持久目录物理隔离，避免扫描范围误伤归档文件。
2. 清理任务根据最后修改时间筛选，并给正在上传的文件留出足够的缓冲时间。
3. 删除失败时记录路径与异常类型，不要静默吞掉，方便识别权限或挂载变化。
4. 业务记录只在文件成功进入持久区后写入“可用”状态，避免数据库先成功、文件却不存在。

相关问题

MultipartFile.transferTo 能不能直接作为最终方案？

可以作为复制到指定位置的接口，但仍要自己决定目标目录、服务端命名、校验时机和失败后的状态处理。临时区域与持久区域分开后，定位问题和回收残留都会更清楚。

只检查 Content-Type 是否够了？

不够。请求头里的类型只是调用方提供的声明，通常还要结合允许后缀、文件尺寸、业务解析结果，以及需要时的内容检测来判断。不同文件类型的验证方式差异很大，别用一条通用规则代替所有检查。

为什么不把临时文件放在默认临时目录？

默认目录未必和应用的保留策略、权限和容量监控匹配。使用专用路径能让清理任务、告警和部署权限都有明确的边界，也能避免和其他组件的临时数据混在一起。

有关 Files.createTempFile、Files.move 与 deleteIfExists 的具体语义可核对 JDK 的 Files 文档；Spring 对上传内容的临时存储与持久复制责任说明见 MultipartFile 接口文档。把文件上传当成一段权责明确的数据流来设计，异常处理和清理逻辑就不会互相冲突。