Java中如何通过POST表单参数上传二进制文件至Mastodon API

我尝试将图片上传至Mastodon API，该API要求表单包含file=(binary)参数。但我的Java代码返回500错误（服务器无法处理图片），相关代码片段如下：

public int uploadImage(Path imageLocation) throws MalformedURLException, IOException {
    int imageID = 0;
    try {
        HttpURLConnection connection = (HttpsURLConnection) new URL("https", instanceURL, "/api/v2/media").openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Content-Type", "multipart/form-data");
        connection.setRequestProperty("Authorization", "Bearer " + accessToken);
        connection.setDoOutput(true);
        DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream());
        outputStream.writeBytes("file=" + Files.readAllBytes(imageLocation));
        imageID = connection.getResponseCode();
    } catch (Exception e) {
        e.printStackTrace();
    }
    return imageID;
}

用curl执行相同操作可以成功，curl命令如下：

curl \
-X POST \
-H "Authorization: Bearer [hidden]" \
-H "Content-Type: multipart/form-data" \
--form "file=@${FILE_LOC}" \
https://mstdn.plus.st/api/v2/media

你的Java代码核心问题是没按multipart/form-data的规范构建请求体，直接拼接字符串和二进制数据的方式完全不符合协议要求，导致服务器无法解析：

• 缺边界分隔符：multipart请求必须指定随机的boundary字符串区分不同表单字段，你只设置了Content-Type却没加boundary，服务器不知道怎么拆分内容
• 二进制数据被破坏：用writeBytes拼接字符串和图片字节，会把非ASCII字节错误编码，直接损坏文件结构
• 缺少字段元信息：multipart的每个字段需要包含字段名、文件名、文件类型等头信息，你的代码完全没处理这些

修复后的完整代码 #

import java.io.*;
import java.net.HttpsURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public int uploadImage(Path imageLocation) throws IOException {
    int responseCode = 0;
    // 生成随机边界字符串，避免和文件内容冲突
    String boundary = "----MastodonUploadBoundary" + System.currentTimeMillis();
    
    try {
        HttpsURLConnection connection = (HttpsURLConnection) new URL("https", instanceURL, "/api/v2/media").openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Authorization", "Bearer " + accessToken);
        // Content-Type必须带上boundary
        connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
        connection.setDoOutput(true);

        try (OutputStream output = connection.getOutputStream()) {
            // 写入file字段的头部信息
            StringBuilder fieldHeader = new StringBuilder();
            fieldHeader.append("--").append(boundary).append("\r\n");
            fieldHeader.append("Content-Disposition: form-data; name=\"file\"; filename=\"")
                    .append(imageLocation.getFileName()).append("\"\r\n");
            // 自动探测图片的MIME类型
            String mimeType = Files.probeContentType(imageLocation);
            fieldHeader.append("Content-Type: ").append(mimeType != null ? mimeType : "application/octet-stream").append("\r\n\r\n");
            
            output.write(fieldHeader.toString().getBytes(StandardCharsets.UTF_8));
            
            // 直接写入图片二进制数据，避免编码错误
            Files.copy(imageLocation, output);
            
            // 写入请求结束的边界标记
            String endBoundary = "\r\n--" + boundary + "--\r\n";
            output.write(endBoundary.getBytes(StandardCharsets.UTF_8));
        }

        responseCode = connection.getResponseCode();
        
        // 出错时读取错误响应，方便排查具体问题
        if (responseCode >= 400) {
            try (BufferedReader errorReader = new BufferedReader(new InputStreamReader(connection.getErrorStream()))) {
                String line;
                System.err.println("服务器错误响应：");
                while ((line = errorReader.readLine()) != null) {
                    System.err.println(line);
                }
            }
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
    return responseCode;
}

关键修复点说明 #

• 添加boundary：在Content-Type里指定随机生成的边界字符串，这是multipart请求的强制要求
• 正确构建字段头：通过Content-Disposition指定字段名file和文件名，Content-Type指定图片的MIME类型，让服务器明确接收的文件信息
• 直接写入二进制数据：用Files.copy把图片字节直接写入输出流，完全避免编码转换导致的文件损坏
• 补充结束边界：请求体最后必须用--boundary--结尾，告诉服务器请求已结束

另外，保留错误响应读取逻辑很有用，遇到500、400这类错误时，能看到服务器返回的具体错误信息（比如文件大小超限、格式不支持等），比只看响应码更便于排查问题。

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