Java FileTypeDetector 怎样注册自定义文件类型识别器

如果 Java 项目的自定义文件扩展名总是被识别成 null，通常不需要改 JDK 的默认探测器。更稳妥的做法是实现 java.nio.file.spi.FileTypeDetector，再把实现类登记到类路径 JAR 的服务配置中。之后调用 Files.probeContentType(path)，JDK 会自动发现它。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/spi/FileTypeDetector.html

先实现一个只负责自定义后缀的探测器

下面以 .acme 文件为例。探测器只读取文件名，不读取文件内容，因此适合格式约定明确、无需解析文件头的场景。MIME 字符串要保持稳定，不能把扩展名直接当成返回值。

package demo.detector;

import java.io.IOException;
import java.nio.file.Path;
import java.nio.file.spi.FileTypeDetector;
import java.util.Locale;

public final class AcmeFileTypeDetector extends FileTypeDetector {
    // 使用公开零参数构造器，便于服务加载器在包外创建实例。
    public AcmeFileTypeDetector() {}

    @Override
    public String probeContentType(Path path) throws IOException {
        // 文件名缺失时无法按后缀判断，把决定权交还给其他探测器。
        if (path == null || path.getFileName() == null) {
            return null;
        }
        String name = path.getFileName().toString().toLowerCase(Locale.ROOT);
        // 只处理当前探测器拥有的扩展名，避免误报其他格式。
        return name.endsWith(".acme") ? "application/vnd.acme" : null;
    }
}

probeContentType 返回 null 不是失败，而是“这个探测器不认识”。这一步很关键：Files 会依次尝试已安装的探测器，全部没有识别结果时才调用系统默认探测器。

用 META-INF/services 注册实现类

在同一个 JAR 的资源目录下创建下面的文件，文件名必须是服务接口的全限定名：

META-INF/services/java.nio.file.spi.FileTypeDetector

# 每行写一个实现类的全限定名
demo.detector.AcmeFileTypeDetector

这里的注释使用服务配置支持的 # 形式；真正被加载的是最后一行类名。常见错误是把文件放成 META-INF/service/、把接口名写成简单类名，或者只把 Java 类放进 JAR 而漏掉资源文件。

打包时确认资源确实进入类路径 JAR

无论使用 Maven、Gradle 还是直接打包，最终 JAR 至少要同时包含实现类和服务文件。可以把它理解为两张表：类文件提供行为，服务文件提供发现入口。

这个 JAR 要放在应用的类路径上。只放在源码目录、测试资源目录未参与打包，或运行时使用了另一份旧 JAR，都会让代码看起来正确但始终没有被发现。

# 查看 JAR 是否同时包含 class 和服务配置
jar tf file-detector.jar | grep -E 'AcmeFileTypeDetector.class|META-INF/services/java.nio.file.spi.FileTypeDetector'

# 将提供者 JAR 放到应用类路径后再启动程序
java -cp "file-detector.jar:app.jar" demo.Main

通过 Files.probeContentType 调用并处理边界

业务代码不需要直接实例化探测器，也不应该假设所有文件都能识别。调用端只消费 MIME 结果，并为 null 留出明确分支：

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

public final class Main {
    public static void main(String[] args) throws IOException {
        Path path = Path.of("sample.acme");
        // 让 JDK 按已安装探测器顺序完成识别，不绕过服务加载机制。
        String contentType = Files.probeContentType(path);
        if (contentType == null) {
            // 未识别时走业务自己的兜底策略，不把 null 当成异常文本。
            System.out.println("未识别文件类型");
            return;
        }
        System.out.println(contentType);
    }
}

如果输出仍然是 null，按“资源路径、JAR 类路径、实现类构造器、后缀判断”这个顺序排查。若同一扩展名存在多个探测器，不要依赖不明确的优先级；应让每个实现只负责自己的格式，必要时改用应用层显式选择。

常见问题

服务文件可以写实现类的简单类名吗？

不可以。必须写实现类的全限定名，例如 demo.detector.AcmeFileTypeDetector，一行一个类名。

探测器不读取文件内容也能工作吗？

可以。FileTypeDetector 的实现方式没有限定，按后缀、文件属性或文件字节判断都可以，关键是返回合法 MIME 类型或 null。

为什么直接 new 探测器成功，但 Files 仍然返回 null？

直接 new 只能证明类本身可用，不能证明服务文件已被打包或 JAR 已进入运行时类路径。优先检查 JAR 内容和启动参数。

这种扩展点的核心不是替换系统探测器，而是把自定义格式接入标准服务发现机制：实现类负责一个清晰的识别范围，服务文件负责注册，Files.probeContentType 负责统一调用和回退。