在 spring boot 中捕获 minio 上传异常，核心做法是配置全局异常处理器 @restcontrolleradvice，并针对 minio sdk 抛出的特定异常类（如 errorresponseexception、noresponseexception）编写具体的 @exceptionhandler 方法。这样可以将底层网络或存储服务的错误转换为标准的 http 响应或业务异常，避免将堆栈信息直接暴露给前端。
MinIO SDK 抛出哪些具体异常类型
MinIO Java SDK 在遇到服务器返回错误状态码（如 403 Forbidden、500 Internal Server Error）时，会抛出 ErrorResponseException；当网络连接中断或读取超时未收到响应时，会抛出 NoResponseException；而一般的 IO 错误或参数校验失败则可能表现为 IOException 或 SdkClientException。理解这些异常类的继承关系有助于精准捕获。
import io.minio.errors.ErrorResponseException; import io.minio.errors.NoResponseException; import io.minio.errors.ServerException; import io.minio.errors.InternalClientException; // 依赖导入示例 // implementation 'io.minio:minio:8.5.2'
如何在全局处理器中区分处理这些异常
在全局异常处理器中，通过定义多个 @ExceptionHandler 方法来分别处理上述异常。对于 ErrorResponseException，可以解析其内部的 XML 响应获取具体的错误代码和消息；对于 NoResponseException，通常归类为网络超时或连接失败。建议将这些异常统一包装为自定义的业务异常或直接返回统一的 JSON 结构，以便前端统一处理。
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import java.util.HashMap;
import java.util.Map;
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ErrorResponseException.class)
public ResponseEntity<map object>> handleMinioError(ErrorResponseException e) {
Map<string object> body = new HashMap();
body.put("error", "MINIO_ERROR");
body.put("message", e.getMessage());
// 可进一步解析 e.response() 获取更详细的 S3 错误码
return ResponseEntity.status(HttpStatus.BAD_GATEWAY).body(body);
}
@ExceptionHandler(NoResponseException.class)
public ResponseEntity<map object>> handleMinioTimeout(NoResponseException e) {
Map<string object> body = new HashMap();
body.put("error", "MINIO_TIMEOUT");
body.put("message", "Connection to MinIO server timed out");
return ResponseEntity.status(HttpStatus.GATEWAY_TIMEOUT).body(body);
}
}</string></map></string></map>
上传大文件时如何处理超时导致的异常
当上传大文件时，MinIO SDK 默认的连接超时和读取超时可能不足以完成传输，从而触发 NoResponseException 或 SocketTimeoutException。解决此问题的关键是在初始化 MinioClient 时调整 HttpUtil 的超时设置，或者在调用 putObject 时指定更大的缓冲区大小。如果仍然超时，全局处理器中的 NoResponseException 捕获块将生效，返回网关超时状态码。
