SpringMVC 接收手機端上傳圖片的完整實作

互動流程

1. 手機端：將圖片轉為位元組陣列，透過 HTTP POST (multipart/form-data) 上傳。
2. 伺服端：SpringMVC Controller 使用 MultipartFile 接收，儲存至檔案系統/雲端存儲，回傳 JSON 結果。

手機端實作要點

Android (OkHttp 範例)

OkHttpClient client = new OkHttpClient();
RequestBody requestBody = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("file", "photo.jpg",
        RequestBody.create(MediaType.parse("image/jpeg"), imageBytes))
    .addFormDataPart("userId", "12345")
    .build();

Request request = new Request.Builder()
    .url("https://api.example.com/upload")
    .post(requestBody)
    .build();

client.newCall(request).enqueue(new Callback() { ... });

iOS (URLSession 範例)

var request = URLRequest(url: URL(string: "https://api.example.com/upload")!)
request.httpMethod = "POST"
let boundary = UUID().uuidString
request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

var body = Data()
body.append("--\(boundary)\r\n".data(using: .utf8)!)
body.append("Content-Disposition: form-data; name=\"file\"; filename=\"photo.jpg\"\r\n".data(using: .utf8)!)
body.append("Content-Type: image/jpeg\r\n\r\n".data(using: .utf8)!)
body.append(imageData)
body.append("\r\n--\(boundary)--\r\n".data(using: .utf8)!)

URLSession.shared.uploadTask(with: request, from: body).resume()

SpringMVC 伺服端實作

1. 設定 Multipart Resolver (Spring Boot 自動配置，傳統 XML 需手動)

@Bean
public MultipartResolver multipartResolver() {
    StandardServletMultipartResolver resolver = new StandardServletMultipartResolver();
    return resolver;
}
// 或 application.properties
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=100MB

2. Controller 接收

@PostMapping("/upload")
@ResponseBody
public Result uploadImage(
        @RequestParam("file") MultipartFile file,
        @RequestParam("userId") Long userId) {
    
    // 1. 校驗
    if (file.isEmpty()) return Result.error("檔案為空");
    if (!Arrays.asList("image/jpeg", "image/png").contains(file.getContentType())) 
        return Result.error("僅支援 JPG/PNG");
    
    // 2. 產生唯一檔名
    String ext = FilenameUtils.getExtension(file.getOriginalFilename());
    String fileName = UUID.randomUUID() + "." + ext;
    String saveDir = "/data/uploads/" + LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE);
    
    // 3. 儲存
    File dir = new File(saveDir);
    if (!dir.exists()) dir.mkdirs();
    
    File dest = new File(dir, fileName);
    try {
        file.transferTo(dest);
    } catch (IOException e) {
        log.error("儲存失敗", e);
        return Result.error("伺服器錯誤");
    }
    
    // 4. 回傳可存取 URL
    String accessUrl = "https://cdn.example.com/uploads/" + fileName;
    return Result.success(accessUrl);
}

常見坑與解決

• 400 Bad Request：檔案大小超過 max-file-size 設定；或未設定 enctype="multipart/form-data" (表單上傳時)。
• 中文檔名亂碼：Tomcat 8+ 需設定 URIEncoding="UTF-8"；Spring Boot 設定 server.tomcat.uri-encoding=UTF-8。
• 大檔案記憶體溢位：Spring 預設小檔案存記憶體，大檔案寫暫存檔。調整 file-size-threshold。
• 權限問題：確保執行 Java 進程的使用者對儲存目錄有寫入權限。

參考資源

完整範例專案：SpringMVC 文件上傳實戰

結論

手機上傳圖片的標準協定是 HTTP POST + multipart/form-data。SpringMVC 透過 MultipartFile 抽象化處理，搭配雲端存儲 (S3/OSS) 與 CDN，即可構建高可用、高擴展的圖片上傳服務。