[Spring] Swagger + RequestPart를 통해 파일, Dto 동시 요청 시 발생 에러 핸들링

현재 Spring Boot를 통한 비디오 스트리밍 서버를 개발하는 간단한 프로젝트를 진행 해보고 있는데, 이를 개발하면서 마주한 에러에 대해 소개하고 이를 해결한 방식, 그리고 어째서 해결이 되는지 까지도 다뤄보고자 한다.

GitHub - One-armed-boy/spring_stream_video: 비디오 스트리밍 서버 with Spring boot

 

문제 상황 묘사

엔드포인트에 대해 직접 요청을 보내서 테스트를 할 때, 포스트맨을 사용할 수도 있겠지만 그것보단 스웨거(OpenAPI)를 활용하는 편이 이후 협업 단계에서 더 좋다고 판단하고 서버 내 Swagger EP를 뚫어둔 상태였다.

띄워둔 Swagger 메인 페이지

그 후 각 엔드포인트에 대해 테스트를 진행하고 있었는데.... 아래 엔드포인트를 테스트할 때 문제가 발생했다.

/videos/upload

발생 예외 바디

"Content-Type 'application/octet-stream' is not supported"라고 예외가 발생한다. 즉, application/octet-stream 형식으로 요청을 건네 받았으며 서버 측에서는 이 형식을 지원하지 않기 때문에 발생하는 예외인 것이다.

 

문제 원인 분석

우선 아래는 문제가 된 엔드포인트의 컨트롤러 메서드의 실제 코드이다.

@PostMapping(path = "/videos/upload", consumes = "multipart/form-data")
public ResponseEntity uploadVideo(@Valid @RequestPart(value = "videoMetadata") UploadVideoRequest request,
	@RequestPart(value = "videoFile") MultipartFile videoFile) {
	var member = securityContextHelper.getMember();
	uploadFacade.uploadVideoSync(UploadVideoCommand.builder()
		.fileName(request.getFileName())
		.extension(request.getExtension())
		.description(request.getDescription())
		.member(member)
		.build(), videoFile);
	return ResponseEntity.ok().build();
}

어노테이션을 보면 알 수 있지만 Content-Type이 'multipart/form-data'로 명시되어 있으며, Swagger에도 이 타입은 정상적으로 반영되어 있기 때문에 애초에 예외 메시지의 'appilication/octet-stream'이 어디에서 등장했는지부터 확인이 필요했다.

application/octet-stream?

이를 알기 위해서는 MIME에 대한 사전 지식이 조금 필요하다. 

MIME이란 Multipurpose Internet Mail Extensions의 약자로 음악이나 사진, 비디오 등의 이진 파일을 네트워크를 통해 전송할 목적으로 텍스트로 변환하고, 이를 수신하는 입장에서 다시 파일화할 때 사용해야 할 기준을 제시하기 위한 목적으로 사용된다.

이 중 이번에 직면한 문제에 등장하는 두 타입에 대해서만 추가적으로 알아보자.

먼저 multipart/form-data 타입이다. 이는 요청 바디에 담기는 내용의 종류가 하나가 아니라서 각 구성요소마다 따로 MIME 타입을 지정해야하는 상황에서 사용한다. 

다음은 application/octet-stream 타입이다. 이는 모든 이진 파일들의 제네릭한 타입을 의미하는데, 말이 좋아 제네릭이지 따지고 보면 어떤 방법을 사용하여 텍스트를 해석해야할지 모를 때 사용하는 방법이다. (Typescript의 any 타입 느낌)

mulitpart/form-data -> application/octet-stream 변환 원인

그렇다면 왜 서버 측에서는 설정해주지도 않은 타입인 application/octet-stream으로 인식하고 있을까? 이를 위해 필터 체인에  OncePerFilter를 하나 추가하고, 요청 내의 모든 Content-Type을 확인할 수 있도록 간단한 로직을 작성해주었다.

log.info(request.getContentType());
for (var part : request.getParts()) {
	log.info(part.getName());
	log.info(part.getContentType());
}

그 후 동일한 문제의 EP를 호출해보았는데 결과는 아래와 같다.

콘솔 출력 결과

모두 의도대로 Content-Type이 들어가있지만 단 하나 videoMetadata 속성의 타입이 null로 되어있었다...!

null이라서 문제 소지가 있는 것은 알겠는데 왜 하필 application/octet-stream 타입인 것일까?

이를 위해 문제가 될만한 스프링 내부 구현을 좀 찾아봤는데, 아래의 로직을 확인할 수 있었다.

// class AbstractMessageConverterMethodArgumentResolver 내부 구현
protected <T> Object readWithMessageConverters(HttpInputMessage inputMessage, MethodParameter parameter,
			Type targetType) throws IOException, HttpMediaTypeNotSupportedException, HttpMessageNotReadableException {

	Class<?> contextClass = parameter.getContainingClass();
	Class<T> targetClass = (targetType instanceof Class clazz ? clazz : null);
	if (targetClass == null) {
		ResolvableType resolvableType = ResolvableType.forMethodParameter(parameter);
		targetClass = (Class<T>) resolvableType.resolve();
	}

	MediaType contentType;
	boolean noContentType = false;
	try {
		contentType = inputMessage.getHeaders().getContentType();
	}
	catch (InvalidMediaTypeException ex) {
		throw new HttpMediaTypeNotSupportedException(
				ex.getMessage(), getSupportedMediaTypes(targetClass != null ? targetClass : Object.class));
	}
	if (contentType == null) {
		noContentType = true;
		contentType = MediaType.APPLICATION_OCTET_STREAM;
	}
    ...
}

위 코드는 Http Request, Response를 자바 클래스로 만들어주는 HttpMessageConverter의 추상 구현체인 AbstractMessageConverterMethodArgumentResolver의 readWithMessageConverter 메서드의 일부이다. 해당 코드의 아래쪽을 보면 확인할 수 있듯, contentType의 값이 null인 경우엔 기본적으로 application/octet-stream 타입으로 지정해버리는 것을 알 수 있다. 이로 인해 서버 측 예외 메시지에는 해당 타입이 등장했던 것이다.

어디를 수정해야 할까?

결국 Content-Type이 Null일 때 저절로 application/octet-stream으로 할당되는 것은 이해를 했는데, 이 문제를 위해서는 어디를 수정해야할까? 이를 위해 서버 측의 예외가 발생한 콜스택을 추적하였고 이번에도 위에서 상기한 AbstractMessageConverterMethodArgumentResolver.readWithMessageConverter 메서드가 문제가 되고 있음을 알 수 있었다. 아래는 문제가 되는 로직이다. (너무 기니깐 건너 뛰시면 요약 있음)

// AbstractMessageConverterMethodArgumentResolver.readWithMessageConverter 메서드 내 일부 로직
EmptyBodyCheckingHttpInputMessage message = null;
try {
	message = new EmptyBodyCheckingHttpInputMessage(inputMessage);
	for (HttpMessageConverter<?> converter : this.messageConverters) {
		Class<HttpMessageConverter<?>> converterType = (Class<HttpMessageConverter<?>>) converter.getClass();
		GenericHttpMessageConverter<?> genericConverter =
				(converter instanceof GenericHttpMessageConverter ghmc ? ghmc : null);
		if (genericConverter != null ? genericConverter.canRead(targetType, contextClass, contentType) :
				(targetClass != null && converter.canRead(targetClass, contentType))) {
			if (message.hasBody()) {
				HttpInputMessage msgToUse =
						getAdvice().beforeBodyRead(message, parameter, targetType, converterType);
				body = (genericConverter != null ? genericConverter.read(targetType, contextClass, msgToUse) :
						((HttpMessageConverter<T>) converter).read(targetClass, msgToUse));
				body = getAdvice().afterBodyRead(body, msgToUse, parameter, targetType, converterType);
			}
			else {
				body = getAdvice().handleEmptyBody(null, message, parameter, targetType, converterType);
			}
			break;
		}
	}
	if (body == NO_VALUE && noContentType && !message.hasBody()) {
		body = getAdvice().handleEmptyBody(
				null, message, parameter, targetType, NoContentTypeHttpMessageConverter.class);
	}
}
catch (IOException ex) {
	throw new HttpMessageNotReadableException("I/O error while reading input message", ex, inputMessage);
}
finally {
	if (message != null && message.hasBody()) {
		closeStreamIfNecessary(message.getBody());
	}
}

if (body == NO_VALUE) {
	if (httpMethod == null || !SUPPORTED_METHODS.contains(httpMethod) || (noContentType && !message.hasBody())) {
		return null;
	}
	throw new HttpMediaTypeNotSupportedException(contentType,
			getSupportedMediaTypes(targetClass != null ? targetClass : Object.class), httpMethod);
}

코드가 너무 많으니 간략히 요약하면 아래와 같다.

1. this.messageConverters에서 특정 Content-Type을 처리할 수 있는 컨버터를 찾아서 처리를 위임한다.
2. 만약 body의 내용이 존재하나 적절한 컨버터를 찾지 못하는 경우, "Content-Type ~ is not supported" 예외를 발생시킨다.

따라서 이 문제를 해결하기 위해서는 application/octet-stream 타입을 처리할 수 있는 메시지 컨버터를 Spring 컨텍스트에 추가해야 함을 알 수 있다.

 

문제 해결

위에서 분석한 문제의 배경을 통해, 결국 문제를 해결하기 위해서는 application/octet-stream을 다뤄주는 HttpMessageConverter를 추가하면 된다는 것을 알았다. 이를 위해, 다음 두 클래스를 프로젝트에 추가해주었다.

@Configuration
public class WebConfig implements WebMvcConfigurer {
	private OctetStreamReadMsgConverter octetStreamReadMsgConverter;

	@Autowired
	public WebConfig(OctetStreamReadMsgConverter octetStreamReadMsgConverter) {
		this.octetStreamReadMsgConverter = octetStreamReadMsgConverter;
	}

	@Override
	public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
		converters.add(octetStreamReadMsgConverter);
	}
}

@Component
public class OctetStreamReadMsgConverter extends AbstractJackson2HttpMessageConverter {
	@Autowired
	public OctetStreamReadMsgConverter(ObjectMapper objectMapper) {
		super(objectMapper, MediaType.APPLICATION_OCTET_STREAM);
	}

	// 기존 application/octet-stream 타입을 쓰기로 다루는 메시지 컨버터가 이미 존재 (ByteArrayHttpMessageConverter)
	// 따라서 해당 컨버터는 쓰기 작업에는 이용하면 안됨
	@Override
	public boolean canWrite(Class<?> clazz, MediaType mediaType) {
		return false;
	}

	@Override
	public boolean canWrite(Type type, Class<?> clazz, MediaType mediaType) {
		return false;
	}

	@Override
	protected boolean canWrite(MediaType mediaType) {
		return false;
	}
}

각 파일에 대한 설명은 아래와 같다.

WebConfig

Spring이 기본적으로 생성하는 HttpMessageConverter 리스트에 추가로 생성해 줄 커스텀 메시지 컨버터를 추가해주기 위한 설정 파일. 이 설정을 통해, 새로 추가할 메시지 컨버터가 Http 메시지를 변환하는 과정에서 참여할 수 있어짐.

OctetStreamReadMsgConverter

application/octet-stream 타입의 Http 메시지에 대한 읽기 작업(Http 메시지 -> Java class)을 수행할 커스텀 메시지 컨버터. 이 때 AbstractJackson2HttpMessageConverter를 상속해준 이유는 이를 통하면 Jackson 라이브러리 기반으로 문자열 형태의 json을 클래스로 변환해줄 수 있는데, 현재 서버 측에서 문제가 되는 경우는 Multipart/form-data 이하의 application/json 타입이 누락되는 것이기 때문.

 

결과

문제의 EP를 다시 호출해보면 아래처럼 200을 반환하며 잘되는 것을 확인할 수 있다!

 

참조

MIME types (IANA media types) - HTTP | MDN

@RequestPart with mixed multipart request, Spring MVC 3.2