Java Files.mismatch 做配置目录核对：从命令行参数到差异报告的小工具

部署前最容易踩的坑，就是把看起来没差别的配置文件夹直接往服务器上拷贝。很多时候单个文件末尾多了个空行、少写了一个配置字符，或是某个环境变量模板没同步到位，等到应用启动报错才发现问题。Java 12 之后推出的 Files.mismatch(Path, Path) 方法可以直接返回两份文件第一个出现差异的字节位置，我们完全可以基于它写一个零第三方依赖的轻量配置目录核对小工具。

这个工具的判断逻辑很简单：同名文件逐字节完全一致才算校验通过；文件缺失、多出多余文件、内容不一样都会单独列出来，最终用进程退出状态码对接后续的发布流程脚本。

先把配置目录核对问题缩小成三种结果

假设项目有 config-prod/ 和 config-candidate/ 两个文件夹，里面既有 application.properties、feature-flags.json，也可能混着证书包、压缩包这类二进制文件。我们不需要把整个文件读进内存，只要给每一个匹配到的相对路径归类成三种结果：完全一致、内容不同、仅在单侧目录存在。

这个边界定义非常关键。对比工具只需要客观反馈两个文件夹是否一致，不要擅自猜测哪份文件是正确版本，更不能自动覆盖目标目录的内容。

用 Java NIO 收集两边的相对路径

第一步只做目录遍历和排序，不用急着对比文件内容。用相对路径作为判断的键，可以避免不同机器的绝对路径出现在最终报告里，输出结果也会稳定统一，后续排查日志对比也方便。

static SortedSet relativeFiles(Path root) throws IOException {
    if (!Files.isDirectory(root)) {
        throw new IOException("不是目录: " + root);
    }

    try (Stream paths = Files.walk(root)) {
        return paths
                .filter(Files::isRegularFile)
                .map(root::relativize)
                .collect(Collectors.toCollection(TreeSet::new));
    }
}

Files.walk 返回的文件流必须主动关闭，所以要放在 try-with-resources 代码块里处理。这里默认没有跟随符号链接，如果你的配置目录场景需要用到软链接，可以在工具说明里明确标注这个规则，避免不同机器上的链接行为偷偷缩小核对范围。

把 Files.mismatch 接到逐文件核对循环

把两个目录收集到的路径集合合并之后再逐个处理。某个路径只在左侧基准目录出现，就代表右侧目标目录缺了这个文件；只在右侧目录出现，就代表候选目录多出来了额外文件。两边路径都存在的情况下再调用 Files.mismatch，返回 -1 才能确认两份文件内容完全相同。

static List compare(Path expected, Path actual) throws IOException {
    SortedSet left = relativeFiles(expected);
    SortedSet right = relativeFiles(actual);
    SortedSet all = new TreeSet(left);
    all.addAll(right);
    List findings = new ArrayList();

    for (Path relative : all) {
        boolean inLeft = left.contains(relative);
        boolean inRight = right.contains(relative);
        if (!inLeft) {
            findings.add(Finding.extra(relative));
            continue;
        }
        if (!inRight) {
            findings.add(Finding.missing(relative));
            continue;
        }

        long offset = Files.mismatch(expected.resolve(relative), actual.resolve(relative));
        if (offset != -1L) {
            findings.add(Finding.different(relative, offset));
        }
    }
    return findings;
}

mismatch 返回的偏移量是从 0 开始计数的，代表第一个不一样的字节所在的位置。它既不是两份文件总共有多少处差异，也不是文本的行号。报告里把对应字段命名为 firstDifferentByte，比写个表意模糊的 line 更不容易误导后续问题排查。

做成一个能接入发布脚本的命令行入口

小工具好不好用，核心就在于入口边界的定义。这里约定命令调用格式为 java ConfigDiff ，参数不全的时候直接打印用法提示；核对发现差异仍然输出完整报告，最后程序返回状态码2。

public static void main(String[] args) {
    if (args.length != 2) {
        System.err.println("用法: java ConfigDiff  ");
        System.exit(1);
    }

    try {
        Path expected = Path.of(args[0]).toAbsolutePath().normalize();
        Path actual = Path.of(args[1]).toAbsolutePath().normalize();
        List findings = compare(expected, actual);
        findings.forEach(System.out::println);
        System.out.printf("核对完成: findings=%d%n", findings.size());
        System.exit(findings.isEmpty() ? 0 : 2);
    } catch (IOException | InvalidPathException ex) {
        System.err.println("核对失败: " + ex.getMessage());
        System.exit(1);
    }
}

生产侧的发布脚本只需要判断程序退出状态就可以，不要用“报告最后一行是否包含通过”这类字符串匹配逻辑做判断。如果目录里有不可读的文件，工具直接返回状态码1，让发布流程停在人工可以介入的节点。

文本和二进制文件的报告方式不要混用

对 application.properties 这类纯文本配置文件，可以额外读取差异位置之前的字节内容统计换行符数量，给出“大概在第18行附近”的辅助提示。但这个只是快速定位的参考，不是精确的语义级对比；遇到UTF-16编码、混合换行格式或者二进制文件时，还是要以字节偏移的结果为准。

建议把差异结果对象设计成三个字段：kind、path、firstDifferentByte。缺失和额外文件的偏移量字段直接留空，只有内容不同的场景才填非负整数值。这样后续不管是输出JSON还是格式化文本，都不会把“文件不存在”误判成“第0个字节不一致”。

本地运行验证四个典型边界场景

自己建一个测试小目录就能完整复现工具的所有行为：

mkdir -p config-prod config-candidate
printf 'mode=prod\nport=8080\n' > config-prod/application.properties
cp config-prod/application.properties config-candidate/application.properties
printf '{"checkout":true}\n' > config-prod/feature-flags.json
printf '{"checkout":false}\n' > config-candidate/feature-flags.json
printf 'temporary\n' > config-candidate/debug.txt

javac ConfigDiff.java
java ConfigDiff config-prod config-candidate
echo $?

运行之后你应该能看到 feature-flags.json 的差异偏移记录，还有 debug.txt 的多余文件记录，最终程序退出状态是2。之后删掉 debug.txt，把两份配置文件的内容改回完全一致，重新运行工具应该返回状态0。再把输入参数改成一个不存在的文件夹，确认程序返回状态1，就完成了基础校验。

常见问题：Files.mismatch 适合放在哪一层

Files.mismatch 能直接传入两个目录做对比吗？

不行。它原生只能对比两个具体文件，目录核对需要你自己先遍历目录、建立好相对路径的全集映射，再对同名文件逐个调用方法做对比。

为什么不直接把文件读成字符串再做equals比较？

配置目录里可能存着大文件或者二进制内容。直接逐字节对比可以省去不必要的字符集转换，也不会把整个大文件一次性加载到JVM内存里。

方法返回的偏移量可以直接当文本行号用吗？

不能直接当行号用。它是从0开始计数的字节位置，只有先确定文件的编码格式、自行统计完换行符的位置之后，才能给出一个近似的行号提示。

把核对环节放在发布执行之前

这个小工具的价值不是替代完整的专业diff工具，而是给发布流程加一个明确的校验节点：先核对全量文件集合是否匹配，再逐字节比对文件内容，最后通过退出状态码让自动化流程自己决定继续往下走还是暂停告警。后续如果要扩展JSON格式报告、自定义忽略规则、哈希缓存加速这类功能，也建议保留最开始定义的三类基础结果，不要用“两边文件总数相同”这种简单判断代替真实的内容一致性校验。