Android Retrofit POST Multipart上传图片报500错误排查

问题描述 #

使用Retrofit通过Multipart方式发起POST请求上传图片时接口返回500错误，相同接口在Postman中可正常调用，不上传图片时现有代码可正常请求成功。
相关代码及接口文档截图：

• ApiService代码：
  
• 文件路径处理代码：
  
• MediaType配置代码：
  
• Swagger接口文档：
  

常见错误点&修复方式 #

按出现概率从高到低排查：

• 手动配置了错误的Content-Type头
  不要在接口方法注解、OkHttp全局拦截器里给Multipart请求手动写死Content-Type: application/json或者固定值的multipart/form-data。Retrofit会自动为Multipart请求生成带随机boundary的Content-Type头，手动写死会导致boundary缺失，后端无法解析表单内容直接报500，删掉手动配置的Content-Type即可。
• 文件Part构造不符合接口要求
  对照Swagger文档核对文件字段名，必须和接口要求的表单字段名完全一致，同时构造Part时必须传入文件名，否则后端无法识别文件字段。正确的文件Part构造代码参考：

  // Java示例
  File imageFile = new File(你的图片本地真实路径);
  RequestBody requestBody = RequestBody.create(MediaType.parse("image/jpeg"), imageFile);
  // 第一个参数替换为Swagger里标注的文件字段名，不要自定义
  MultipartBody.Part filePart = MultipartBody.Part.createFormData("file", imageFile.getName(), requestBody);
  

  普通表单参数用text/plain类型的RequestBody传递即可，如果用@PartMap传普通参数，Map的value必须是RequestBody类型，不能直接传String值，否则Retrofit会对参数做额外的URL转义，导致后端参数解析失败：

  RequestBody textParam = RequestBody.create(MediaType.parse("text/plain"), "参数值");
  

• MediaType配置与实际文件不匹配
  不要给图片文件设置*/*、application/octet-stream这类不符合实际格式的MediaType，也不要把单个文件Part的MediaType写成multipart/form-data（这是整个请求的类型，不是单文件的类型），根据图片真实格式传image/jpeg、image/png即可，避免后端解析文件类型失败。
• 文件路径读取错误
  如果拿到的是相册返回的content://类型Uri，直接转File对象会读取不到真实文件内容，最终传给后端的是空文件，触发后端解析报错。需要先通过ContentResolver读取Uri对应的文件流，拷贝到应用私有目录拿到真实文件路径后再构造请求体。

快速定位技巧：添加OkHttp的HttpLoggingInterceptor，把日志级别设为BODY，打印出完整的请求报文，和Postman中成功请求的Multipart表单结构逐字段对比，存在差异的部分就是配置错误点。

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