Java MappedByteBuffer.force 怎样只刷指定文件范围

在 Java 中，可用 MappedByteBuffer.force(index, length) 指定需要刷出的映射区间。index 是当前映射缓冲区内的相对索引，不是文件绝对偏移；若映射起点为 mapOffset，应使用 index = fileOffset - mapOffset 换算。这个方法从 Java 13 提供。

标题中的“只刷指定范围”应理解为指定需要持久化的区域，而不是禁止操作系统写出其他字节。官方允许底层按设备相关粒度写出范围之外的数据，因此它不提供逐字节隔离刷盘的保证。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/MappedByteBuffer.html

问题现场：文件偏移正确，force 的下标却错了

设想一个练习文件，程序只映射从文件偏移 4096 开始的 8192 字节窗口。业务更新位置在文件偏移 4608，写入四个字节。这时 force 的正确参数是 force(512, 4)；直接传 4608 会指向该映射内的另一个位置。

这些数字用于说明坐标换算，不是性能测量。若文件映射从零开始，两套坐标恰好相同，错误可能暂时没有暴露；换成非零起点或分段映射后，混用坐标才更明显。排查时应先记录映射起点、容量、文件更新偏移和更新长度，再看换算结果。

先确认范围，再用明确参数调用

按 API 文档，index 必须非负且小于 capacity，length 非负且不能超过 capacity 减 index。用于刷盘的范围依据 capacity，而不是 remaining。无参 force 的范围是从零开始覆盖整个 capacity，不能通过修改 position 和 limit 把它变成局部 force。

下面的辅助方法只修改已经存在且长度足够的练习文件，不创建、不扩容、不截断文件。它采用单线程、外部无并发截断的前提，空 payload 直接返回。示例使用 Java 17+，未在本文运行；不要把打印信息当作实际磁盘恢复结果。

import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.MappedByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
import java.util.Objects;

public final class RangeFlusher {
    // 要求已有文件足够长，且调用期间没有其他线程或进程截断文件。
    public static void patch(Path path, long mapOffset, int mapLength,
                             long fileOffset, byte[] payload)
            throws IOException {
        Objects.requireNonNull(payload, "payload");
        if (mapOffset  mapLength ||
                payload.length > mapLength - relative) {
            throw new IllegalArgumentException("写入区间不在映射范围内");
        }
        if (payload.length == 0) {
            return; // 这是本辅助方法的空更新约定，不调用 force。
        }
        int index = Math.toIntExact(relative);

        try (FileChannel channel = FileChannel.open(path,
                StandardOpenOption.READ, StandardOpenOption.WRITE)) {
            long size = channel.size();
            if (mapOffset > size || mapLength > size - mapOffset) {
                throw new IllegalArgumentException("已有文件不足以覆盖映射范围");
            }
            MappedByteBuffer mapped = channel.map(
                    FileChannel.MapMode.READ_WRITE, mapOffset, mapLength);
            // 新映射的 limit 等于 capacity，绝对 put 不依赖 position。
            for (int i = 0; i 

代码在 long 范围内计算 relative，再判断 payload 能否放进映射剩余空间，最后转换成 int。这样既保留文件偏移的 long 表达，也服从 MappedByteBuffer 的 int 索引。对于一个非空 payload，通过范围判断后 index 必然落在有效容量内。

这里逐字节使用绝对 put，是为了直接展示写入索引与 force 索引的一致性，适合这段短补丁示例，不是大块复制的性能建议。实际程序若另外使用 slice 或 duplicate，必须以调用 force 的那一个缓冲区坐标为准，不能继续套用原视图的索引。

定位另一个误会：选中四字节，不等于只写四字节

底层可能按页或设备相关的数据块粒度处理。即使传入四字节区间，附近区域也可能随同写出。不要据此实现“同一页上某些字段必须落盘、另一些字段绝不能落盘”的协议；也不要把更小的 length 自动等同于更快的调用。

对本地存储上的文件，force 的返回具有文档描述的选中区域写回保证；非本地设备不承诺相同保证。READ_ONLY 和 PRIVATE 映射调用 force 没有效果。本文使用 READ_WRITE，避免把私有修改误认为文件内容更新。

修复后怎样判断，哪些结果不能靠这段代码证明

在这个练习里，坐标修复的判断依据是：文件偏移 4608 减去映射基址 4096 等于 512；长度四字节位于 8192 字节容量内；写入与 force 使用同一个 index。这些是参数推导，不是本文已经执行的验证结果。真正的部署测试还应按存储环境设计，不能只重新读取一次内容就声称经历断电仍可恢复。

force 不是数据库事务，也不提供多字段更新的原子提交、失败回滚或线程同步协议。若更新过程中发生 I/O 失败，示例报告失败，但不撤回已经写入映射的字节。读取者可见性、记录一致性和崩溃恢复格式，需要另外的应用设计。

也不能以 channel.force(...) 一概替代映射缓冲区的 force。FileChannel 文档区分了通道写入与映射修改的保证范围；映射修改应使用映射缓冲区对应的方法。关闭通道同样不等价于立刻解除映射，程序应避免在映射有效期间截断相关文件。

常见追问

为什么 catch IOException 没捕获刷盘失败？

MappedByteBuffer.force 报告 I/O 失败使用 UncheckedIOException；打开通道和建立映射则可能抛 IOException。示例分别处理两类，避免误把“没有进入 IOException 分支”理解为没有错误。

调用 force 之前要 flip 吗？

本例不需要。flip 改变的是读写游标相关状态，不负责确定 force(index, length) 的区间。若随意 flip 后继续绝对 put，还可能因为 limit 变化引出另一类写入越界。

可以用 length 等于零表示刷到文件末尾吗？

不可以。length 就是区间字节数，零不代表剩余全部区域。本辅助方法选择对空更新直接返回，避免利用零长度边界推测持久化语义。

处理这类问题，关键在于把文件位置、缓冲区索引和存储粒度分别说明，再让写入和 force 使用同一套相对坐标。

参考资料：MappedByteBuffer API、FileChannel 映射与 force 说明。