Java Files.move 原子替换配置文件：临时文件、同目录改名与失败回退

配置热更新最怕的不是写失败，而是读线程恰好读到“写了一半”的文件。直接对 app.properties 调用 Files.writeString，大文件或磁盘繁忙时都可能让下一次读取拿到不完整内容。更稳的做法是先在目标文件同一目录写完临时文件，再用 Files.move 把它替换到目标位置。

先写同目录临时文件，关闭并核对内容后再改名；优先尝试 ATOMIC_MOVE，不支持时明确记录回退结果，不要把“写入成功”误当成“替换成功”。

先把“写文件”和“替换文件”分成两个动作

一次配置更新其实有两个调用方需求：生成新内容的一方希望写入过程可控，读取配置的一方希望每次打开都只看到旧版本或新版本。把目标文件截断后逐段写入，会让这两个需求互相冲突。

临时文件策略把风险隔开：app.properties.next 负责承接新内容，app.properties 在替换完成前继续提供旧内容。临时文件名应放在目标目录下，避免临时目录和配置目录不在同一文件系统时无法完成一次改名。

Files.move 的参数如何表达替换意图

最小的替换调用如下：

Files.move(temp, target,
        StandardCopyOption.ATOMIC_MOVE,
        StandardCopyOption.REPLACE_EXISTING);

REPLACE_EXISTING 表示目标已存在时允许替换；ATOMIC_MOVE 则表达“改名动作尽量作为一个不可分割的文件系统操作完成”。两者缺一不可：只写前者，仍然没有明确的原子替换意图；只写后者，目标存在时可能因实现限制而失败。

一个可运行的配置替换方法

下面的实现把写入、关闭、替换和读取核对放在一条清晰链路里。示例中的临时文件只在目标目录存在，方法返回后不会留下成功替换所需之外的中间状态。

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

public final class ConfigReplacer {
    private ConfigReplacer() {}

    public static void replace(Path target, String content) throws IOException {
        Path directory = target.toAbsolutePath().getParent();
        if (directory == null) {
            throw new IOException("配置文件没有父目录");
        }
        Files.createDirectories(directory);

        Path temp = Files.createTempFile(directory, target.getFileName().toString(), ".next");
        boolean replaced = false;
        try {
            Files.writeString(temp, content, StandardCharsets.UTF_8);
            long bytes = Files.size(temp);
            if (bytes == 0 && !content.isEmpty()) {
                throw new IOException("临时配置文件大小异常");
            }
            Files.move(temp, target,
                    StandardCopyOption.ATOMIC_MOVE,
                    StandardCopyOption.REPLACE_EXISTING);
            replaced = true;
        } finally {
            if (!replaced) {
                Files.deleteIfExists(temp);
            }
        }
    }
}

这里的 finally 只清理未完成的临时文件。替换已经完成后，临时路径通常已经不存在，再次清理也不会碰到目标文件。

不支持 ATOMIC_MOVE 时怎么回退

网络盘、特殊文件系统或不同实现可能不接受原子改名。捕获 AtomicMoveNotSupportedException 后，可以在已经完成写入和核对的前提下，使用带 REPLACE_EXISTING 的普通改名作为降级路径；这条路径要在日志中显式标出，因为它的可见性保证低于原子改名。

import java.nio.file.AtomicMoveNotSupportedException;

try {
    Files.move(temp, target,
            StandardCopyOption.ATOMIC_MOVE,
            StandardCopyOption.REPLACE_EXISTING);
} catch (AtomicMoveNotSupportedException ex) {
    // 只在临时文件已完整关闭并核对后走这里
    Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
}

如果普通改名也失败，旧目标文件应继续保留。不要为了“清理现场”先删除 target，否则一次权限或磁盘错误就可能把可用配置也删掉。

替换完成后还要核对什么

成功返回只说明文件系统调用没有抛出异常，不能替代应用层检查。至少做三项核对：

• 重新读取目标文件，确认关键配置键存在，不能只检查文件路径存在。
• 记录临时文件写入字节数和最终读取字节数，差异明显时暂停加载。
• 热更新线程切换配置对象时保留旧对象，解析失败就继续使用旧版本。

如果配置中有版本字段，可以让每次内容带上递增版本号。读取线程发现版本倒退时不切换，这比只看文件修改时间更容易定位并发更新问题。

常见问题

为什么临时文件一定建议放在目标目录？

同目录更容易保证临时文件和目标文件位于同一文件系统，改名时不需要先复制跨盘内容，也更容易获得完整替换语义。

REPLACE_EXISTING 能不能代替 ATOMIC_MOVE？

不能。前者只说明目标已存在时允许覆盖，后者才是对改名可见性的明确要求；如果环境不支持，应该记录并走已核对过的回退路径。

替换失败时要不要删除旧配置？

不要。旧配置是恢复副本，失败时保留它，并清理未完成的临时文件即可。

配置内容为空时一定是错误吗？

不一定，是否允许空配置取决于业务规则。示例只检查非空输入却生成零字节的异常情况，生产代码还应校验必填键和取值范围。

把替换动作纳入发布检查

这套方法适合小型配置、规则文件和本地生成的索引快照。真正上线前，再用目标运行用户验证目录权限、磁盘空间、文件系统类型和回退日志；把“原子替换成功”“普通改名回退”“旧配置继续生效”分别做成可观测状态，问题会比只看一个成功计数更容易追踪。