Java Files.move 怎样选择 ATOMIC_MOVE 与 REPLACE_EXISTING

我在做文件发布替换时，最容易把 ATOMIC_MOVE 和 REPLACE_EXISTING 当成一组“增强移动参数”。其实它们承诺的是两件不同的事：前者要求底层文件系统用原子操作完成移动，后者允许目标文件已存在时被源文件替换。

官方资料：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/Files.html

需要可靠切换时，先判断是否必须原子可见，再判断是否允许覆盖。通常同一 FileStore 内的临时文件替换优先尝试 ATOMIC_MOVE；只是希望覆盖普通目标文件时使用 REPLACE_EXISTING。不能把两者的语义混为一谈。

先把两个选项拆成两种承诺

Files.move(source, target, options) 默认在目标存在时失败。REPLACE_EXISTING 改变的是“目标已经存在怎么办”：如果目标是普通文件，移动可以替换它；非空目录不能这样被替换，目标是符号链接时替换的是链接本身。

ATOMIC_MOVE 改变的是“移动过程必须怎样发生”：要求文件系统把移动当作一个原子文件系统操作。如果做不到，规范允许抛出 AtomicMoveNotSupportedException。更重要的是，官方 API 明确说明，使用 ATOMIC_MOVE 时其他选项都会被忽略，所以不要把它和 REPLACE_EXISTING 组合后理解成“必然原子覆盖”。目标已存在时究竟替换还是抛出 IOException，是实现相关行为。

可以先用下面这张表做判断：

目标不存在时，默认移动就够了

如果目标路径明确不存在，而且业务只要求把文件移到新名字或新位置，默认调用即可。不要为了“更强”随意加入覆盖选项，因为选项越多，代码对目标状态的假设越复杂。

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

public final class FileMover {
    private FileMover() {
        // 工具类不需要实例化，避免把文件移动策略变成隐式状态。
    }

    public static Path moveToNewTarget(Path source, Path target) throws IOException {
        // 不传 CopyOption：目标已存在时让 Files.move 明确失败，避免静默覆盖。
        return Files.move(source, target);
    }
}

默认移动失败时，常见原因是目标已经被其他进程创建。这个失败本身通常比静默覆盖更容易处理：调用方可以记录冲突、生成新的版本名，或者把它交给上层重试策略。

允许覆盖普通文件时，使用 REPLACE_EXISTING

配置文件、导出结果或缓存快照经常需要“新文件替换旧文件”。这时 REPLACE_EXISTING 表达的是业务意图：目标存在不算异常，源文件内容应该成为目标的新内容。

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

public static Path replaceRegularTarget(Path source, Path target) throws IOException {
    // 允许替换目标普通文件；非空目录仍不能被该选项替换。
    return Files.move(source, target, StandardCopyOption.REPLACE_EXISTING);
}

这里没有使用 Files.exists(target) 作为前置条件。先检查再移动会产生竞态窗口：检查完成后，另一个进程仍可能创建、删除或替换目标。让 Files.move 一次性处理目标状态，再按异常类型决定后续动作，更符合文件系统操作的边界。

同一 FileStore 内需要可靠切换时，优先 ATOMIC_MOVE

典型做法是先把完整内容写到目标目录中的临时文件，再把临时文件改名为正式文件。这样读者不会看到“写到一半”的中间内容；但这个效果的前提是移动确实由同一文件系统以原子方式完成。

import java.io.IOException;
import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

public static Path publishAtomically(Path staged, Path published) throws IOException {
    try {
        // 临时文件和正式文件应放在同一目录，降低跨 FileStore 的概率。
        return Files.move(staged, published, StandardCopyOption.ATOMIC_MOVE);
    } catch (AtomicMoveNotSupportedException ex) {
        // 原子性是硬要求时不能静默降级，否则读者可能看到不完整文件。
        throw new IOException("当前文件系统不支持原子发布: " + published, ex);
    }
}

这段代码刻意没有同时加入 REPLACE_EXISTING。因为 ATOMIC_MOVE 会忽略其他选项，目标已存在时的替换行为并不由 REPLACE_EXISTING 兜底。若业务要求“原子地替换已有文件”，必须先确认目标文件系统和 provider 对这个场景的实际支持，再决定是否允许目标先被清理，或改用带版本名的切换模型。

跨 FileStore 时，不要假设原子性

源文件在本地磁盘、目标在网络挂载或另一个文件系统时，移动可能需要复制文件内容后再删除源文件。Oracle API 特别指出，跨 FileStore 或关联不同 provider 时，原子移动可能不支持；如果使用 ATOMIC_MOVE，应准备接收 AtomicMoveNotSupportedException。

如果业务绝不能暴露半成品，就保留失败并让调用方选择同一文件系统的暂存目录。如果业务允许降级，则需要明确接受非原子过程，并记录源文件、目标文件和清理结果。非原子移动发生 IOException 后，源文件和目标文件可能同时存在，目标也可能不完整，不能只凭“抛过异常”判断最终状态。

把选择封装成可读的策略方法

实际项目里可以把“原子发布”和“允许覆盖”拆成两个名字清楚的方法，而不是在调用点堆叠布尔参数。下面的方法用于同一目录内的版本切换：原子性失败直接向上抛出，避免隐藏数据一致性问题。

import java.io.IOException;
import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

public static void publish(Path directory, String tempName, String finalName) throws IOException {
    Path staged = directory.resolve(tempName);
    Path published = directory.resolve(finalName);

    try {
        // staged 与 published 在同一目录，适合尝试原子改名。
        Files.move(staged, published, StandardCopyOption.ATOMIC_MOVE);
    } catch (AtomicMoveNotSupportedException ex) {
        // 原子性是发布协议的一部分，失败时保留现场并交给上层处理。
        throw new IOException("无法原子切换发布文件", ex);
    }
}

如果你的需求只是替换一个已有的普通文件，而不是“读者必须看不到切换中间态”，就用 REPLACE_EXISTING 并围绕 IOException 做日志和重试。不要先调用 exists 再决定选项，也不要在捕获 AtomicMoveNotSupportedException 后无条件改成覆盖移动。

最后用这张清单做选择

1. 只改名且目标应当不存在：不传选项。
2. 目标存在也允许替换普通文件：使用 REPLACE_EXISTING。
3. 必须让切换对观察者呈现为一次原子动作：使用 ATOMIC_MOVE，并处理不支持异常。
4. 使用 ATOMIC_MOVE 时，不要依赖 REPLACE_EXISTING 提供覆盖保证。
5. 源和目标可能跨 FileStore 或 provider：先定义失败或降级策略，不把复制加删除伪装成原子移动。

相关问题

ATOMIC_MOVE 和 REPLACE_EXISTING 可以一起传吗？

API 允许把多个选项传入，但 ATOMIC_MOVE 被采用时其它选项会被忽略，因此不能把组合调用理解成“原子覆盖已存在目标”的跨平台保证。

为什么临时文件要和正式文件放在同一目录？

同一目录通常更容易处于同一 FileStore，原子改名的成功概率更高，也能避免暂存文件先写在另一个文件系统再跨盘移动。

捕获 AtomicMoveNotSupportedException 后可以改用 REPLACE_EXISTING 吗？

只有在业务明确允许非原子替换时才可以。若发布过程不能让读者看到不完整文件，应保留失败并把暂存位置或文件系统调整为支持原子移动的方案。