基于Akka HTTP的REST文件服务实现及响应类型选型问询

刚好做过类似的Akka HTTP文件服务开发，给你梳理下具体的实现方案和关键细节：

对应你熟悉的Java MediaType.APPLICATION_OCTET_STREAM，在Akka HTTP的Java API里用ContentTypes.APPLICATION_OCTET_STREAM就完全合适——它是处理任意格式二进制文件的通用类型，能告诉客户端"这是原始二进制流，按原样处理即可"。

如果你的场景里经常遇到可识别的文件类型（比如图片、文本、PDF），也可以尝试根据文件扩展名自动匹配对应的MediaType（比如ContentTypes.IMAGE_PNG、ContentTypes.TEXT_PLAIN），但对于任意格式文件的需求，APPLICATION_OCTET_STREAM是最稳妥的默认选择。

另外强烈建议配合Content-Disposition响应头一起用，明确告诉客户端是要下载文件还是在线预览：

// 让客户端下载文件
HttpHeader.create("Content-Disposition", "attachment; filename=\"" + fileName + "\"")
// 支持在线预览（如果客户端支持的话）
HttpHeader.create("Content-Disposition", "inline; filename=\"" + fileName + "\"")

下面是完整的Java实现，包含路由定义、安全校验、文件读取和响应构建，完全贴合你的需求：

核心代码实现 #

import akka.actor.ActorSystem;
import akka.http.javadsl.ConnectHttp;
import akka.http.javadsl.Http;
import akka.http.javadsl.ServerBinding;
import akka.http.javadsl.model.ContentTypes;
import akka.http.javadsl.model.HttpEntities;
import akka.http.javadsl.model.HttpResponse;
import akka.http.javadsl.server.AllDirectives;
import akka.http.javadsl.server.Route;
import akka.stream.ActorMaterializer;
import akka.stream.javadsl.FileIO;
import akka.stream.javadsl.Source;
import akka.util.ByteString;

import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.concurrent.CompletionStage;

public class FileService extends AllDirectives {

    // 这里替换成你实际的服务器文件存储目录，务必选非系统敏感的目录
    private static final String FILE_STORAGE_DIR = "/your/secure/storage/path";
    private final Path baseStoragePath = Paths.get(FILE_STORAGE_DIR).toAbsolutePath().normalize();

    public static void main(String[] args) throws Exception {
        ActorSystem system = ActorSystem.create("file-provider-system");
        ActorMaterializer materializer = ActorMaterializer.create(system);
        FileService service = new FileService();

        Http http = Http.get(system);
        CompletionStage<ServerBinding> binding = http.bindAndHandle(
                service.createFileRoute().flow(system, materializer),
                ConnectHttp.toHost("localhost", 8080),
                materializer
        );

        System.out.println("File service running at http://localhost:8080/");
        System.in.read(); // 等待用户输入终止

        binding.thenCompose(ServerBinding::unbind)
                .thenAccept(unbound -> system.terminate());
    }

    private Route createFileRoute() {
        return post(() ->
                path("fetch-file", () ->
                        // 解析请求体中的文件名
                        entity(String.class, requestedFileName -> {
                            // 1. 关键安全校验：防止路径遍历攻击（必须加！）
                            Path targetFile = baseStoragePath.resolve(requestedFileName).normalize();
                            if (!targetFile.startsWith(baseStoragePath)) {
                                return complete(HttpResponse.forbidden().withEntity("Invalid file path - access denied"));
                            }

                            // 2. 检查文件是否存在且可读
                            if (!Files.exists(targetFile) || !Files.isReadable(targetFile)) {
                                return complete(HttpResponse.notFound().withEntity("Requested file does not exist"));
                            }

                            // 3. 构建异步文件流响应
                            Source<ByteString, ?> fileStream = FileIO.fromPath(targetFile);
                            return complete(
                                    HttpResponse.ok()
                                            // 告诉客户端下载文件
                                            .addHeader(HttpHeader.create("Content-Disposition", "attachment; filename=\"" + requestedFileName + "\""))
                                            // 用APPLICATION_OCTET_STREAM作为响应类型
                                            .withEntity(HttpEntities.create(
                                                    ContentTypes.APPLICATION_OCTET_STREAM,
                                                    Files.size(targetFile),
                                                    fileStream
                                            ))
                            );
                        })
                )
        );
    }
}

关键细节说明 #

• 安全防护：绝对不能跳过路径校验！通过normalize()和startsWith(baseStoragePath)确保用户只能访问指定目录下的文件，避免恶意请求（比如../etc/passwd）访问系统敏感文件。
• 异步非阻塞：用Akka Stream的FileIO.fromPath()读取文件，完全符合Akka HTTP的异步设计，不会阻塞线程，能支撑高并发请求。
• 响应完整性：通过HttpEntities.create()把文件流、内容类型和文件大小绑定在一起，配合Content-Disposition头让客户端正确识别和处理文件。

• 智能MediaType匹配：可以通过Files.probeContentType(targetFile)或者自定义扩展名映射表，自动识别文件类型并返回对应的ContentTypes，提升客户端体验（比如图片直接在浏览器预览）。
• 缓存控制：添加Cache-Control响应头，对静态文件设置合理的缓存时长，减少重复请求的服务器负载。
• 统一异常处理：用handleExceptions()包装路由，捕获文件读取时的IO异常，返回更友好的错误响应。

内容的提问来源于stack exchange，提问作者rkabhishek