Java API上传图片后文件损坏无法打开，请求问题排查

问题描述 #

使用JAX-RS编写的图片上传接口（UploadResource）搭配MediaManager处理文件存储，通过Postman以binary或form-data方式上传图片时，生成的文件路径、名称正确，文件大小也与原文件接近，但文件损坏无法被图片查看器打开。

相关代码如下：

UploadResource 类 #

@Path("uploads")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class UploadResource extends BaseResource {

    private static final int DEFAULT_BUFFER_SIZE = 8192;
    private static final int IMAGE_SIZE_LIMIT = 2000000;
    private static final int PDF_SIZE_LIMIT = 5000000;
    private static final Logger LOGGER = LoggerFactory.getLogger(UploadResource.class);

    private String imageExtension(String type) {
        switch (type) {
            case "image/jpeg":
                return "jpg";
            case "image/png":
                return "png";
            case "image/gif":
                return "gif";
            case "image/webp":
                return "webp";
            case "image/svg+xml":
                return "svg";
            default:
                throw new IllegalArgumentException("Unsupported image type");
        }
    }

    @Path("{entity}/{id}")
    @POST
    @Consumes("image/*")
    public Response uploadImage(@PathParam("entity") String entity, @PathParam("id") long entityId, File file,
                                @HeaderParam(HttpHeaders.CONTENT_TYPE) String type) {
        try {
            // Extract the file extension from the content type
            String extension = type.substring("image/".length());
            String name = entityId + "_" + new Date().getTime();

            // Ensure correct buffer size and image size limit handling
            try (FileInputStream input = new FileInputStream(file);
                 OutputStream output = Context.getMediaManager().createFileStream(entity, name, extension)) {
                byte[] buffer = new byte[8192]; // Use 8 KB buffer
                int read;
                long transferred = 0;
                
                // Read in chunks and write to output
                while ((read = input.read(buffer)) != -1) {
                    output.write(buffer, 0, read);
                    transferred += read;

                    // Check if the image size exceeds the limit
                    if (transferred > IMAGE_SIZE_LIMIT) {
                        throw new IllegalArgumentException("Image size limit exceeded"+transferred);
                    }
                }
                output.flush(); // Ensure all data is written
            }

            // Return successful response with the generated image file name
            Map<String, String> result = new HashMap<>();
            result.put("image", name + "." + extension);
            return Response.ok(ResponseHelper.getResultWith_200(result)).build();
        }
        catch (Exception ex) {
            LOGGER.warn("Image upload failed (LS): ", ex); // Log the entire exception stack trace
            return Response.ok(ResponseHelper.getResultWith_400(ResponseHelper.formatMsg(ex.getMessage()))).build();
        }
    }
}

MediaManager 类 #

public class MediaManager {

    private static final Logger LOGGER = LoggerFactory.getLogger(MediaManager.class);

    private final String path;

    public MediaManager(String path) {
        this.path = path;
    }

    private File createFile(String uniqueId, String name) throws IOException {
        Path filePath = Paths.get(path, uniqueId, name);
        Path directoryPath = filePath.getParent();
        if (directoryPath != null) {
            Files.createDirectories(directoryPath);
        }
        LOGGER.info("Creating file at path: {}", filePath);
        return filePath.toFile();
    }

    public OutputStream createFileStream(String uniqueId, String name, String extension) throws IOException {
        File file = createFile(uniqueId, name + "." + extension);
        LOGGER.info("Opening output stream for file: {}", file.getAbsolutePath());
        return new FileOutputStream(file);
    }
}

问题根源 #

核心问题在于接口参数的错误使用：

• binary模式上传：JAX-RS不会自动将请求体的二进制内容写入File对象，此时file指向的是无效的临时文件，读取后写入的内容并非原始图片数据。
• form-data模式上传：File参数无法正确解析multipart表单的结构，读取到的内容包含表单边界信息等无效数据，导致生成的文件损坏。
• 类上的@Consumes(MediaType.APPLICATION_JSON)与方法上的@Consumes("image/*")存在注解冲突，虽然方法注解会覆盖类注解，但容易引发解析逻辑混乱。

修复方案 #

方案1：适配binary模式上传 #

将方法参数中的File替换为InputStream，直接读取请求体的二进制内容：

修改后的uploadImage方法：

@Path("{entity}/{id}")
@POST
@Consumes("image/*")
public Response uploadImage(@PathParam("entity") String entity, 
                            @PathParam("id") long entityId, 
                            InputStream inputStream, // 替换为InputStream
                            @HeaderParam(HttpHeaders.CONTENT_TYPE) String type) {
    try {
        // 校验contentType合法性，避免substring抛出异常
        if (!type.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported media type");
        }
        String extension = type.substring("image/".length());
        String name = entityId + "_" + new Date().getTime();

        try (OutputStream output = Context.getMediaManager().createFileStream(entity, name, extension)) {
            byte[] buffer = new byte[8192];
            int read;
            long transferred = 0;
            
            while ((read = inputStream.read(buffer)) != -1) {
                output.write(buffer, 0, read);
                transferred += read;

                if (transferred > IMAGE_SIZE_LIMIT) {
                    throw new IllegalArgumentException("Image size limit exceeded: " + transferred);
                }
            }
            output.flush();
        }

        Map<String, String> result = new HashMap<>();
        result.put("image", name + "." + extension);
        return Response.ok(ResponseHelper.getResultWith_200(result)).build();
    } catch (Exception ex) {
        LOGGER.warn("Image upload failed (LS): ", ex);
        return Response.ok(ResponseHelper.getResultWith_400(ResponseHelper.formatMsg(ex.getMessage()))).build();
    }
}

同时移除类上的冲突注解：

@Path("uploads")
@Produces(MediaType.APPLICATION_JSON)
// 移除@Consumes(MediaType.APPLICATION_JSON)
public class UploadResource extends BaseResource {
    // ... 其他代码不变
}

方案2：支持form-data模式上传 #

如果需要兼容form-data上传，需引入JAX-RS的multipart扩展（如Jersey的jersey-media-multipart依赖），并修改方法参数：

@Path("{entity}/{id}")
@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
public Response uploadImage(@PathParam("entity") String entity, 
                            @PathParam("id") long entityId, 
                            @FormDataParam("file") InputStream inputStream,
                            @FormDataParam("file") FormDataContentDisposition contentDisposition,
                            @HeaderParam(HttpHeaders.CONTENT_TYPE) String type) {
    try {
        if (!type.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported media type");
        }
        String extension = type.substring("image/".length());
        String name = entityId + "_" + new Date().getTime();

        try (OutputStream output = Context.getMediaManager().createFileStream(entity, name, extension)) {
            byte[] buffer = new byte[8192];
            int read;
            long transferred = 0;
            
            while ((read = inputStream.read(buffer)) != -1) {
                output.write(buffer, 0, read);
                transferred += read;

                if (transferred > IMAGE_SIZE_LIMIT) {
                    throw new IllegalArgumentException("Image size limit exceeded: " + transferred);
                }
            }
            output.flush();
        }

        Map<String, String> result = new HashMap<>();
        result.put("image", name + "." + extension);
        return Response.ok(ResponseHelper.getResultWith_200(result)).build();
    } catch (Exception ex) {
        LOGGER.warn("Image upload failed (LS): ", ex);
        return Response.ok(ResponseHelper.getResultWith_400(ResponseHelper.formatMsg(ex.getMessage()))).build();
    }
}

额外优化 #

可以使用Files.copy简化文件拷贝逻辑，替代手动buffer读写：

// 替换手动读写代码
File outputFile = Context.getMediaManager().createFile(entity, name + "." + extension);
Files.copy(inputStream, outputFile.toPath(), StandardCopyOption.REPLACE_EXISTING);

内容的提问来源于stack exchange，提问作者M Hamza Javed