1. 문제 상황

API 개발을 하다 보면 파일과 DTO(JSON)를 함께 받아야 하는 경우가 많다.
지금 내가 개발하고 있는 플랫폼에서도, 프로젝트 업로드 기능이 존재한다. 프로젝트 세부 정보(JSON)와 썸네일 파일을 동시에 업로드해야 한다.

@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
ResponseEntity<SuccessResponse<Void>> uploadProject(
        @Parameter(hidden = true)
        @CurrentUserId
        Long userId,

        @RequestPart(value = "thumbnailFile", required = false)
        MultipartFile thumbnailFile,

        @RequestPart @Validated
        UploadProjectWebRequest webRequest
);

여기서 thumbnailFile은 선택 파일이고, webRequest는 JSON DTO다.

문제는 Swagger, Postman, 프론트엔드 코드에서 webRequest 파트의
Content-Type이 application/json이 아닌, application/octet-stream이나
text/plain으로 들어오는 경우가 많다는 것이다. 이때 Spring은 Jackson을
이용한 역직렬화를 시도하지 못하고 다음과 같은 오류가 발생한다. 나도, 처음엔 스웨거, 포스트맨 등에서 테스트를 할 때 현재 조건 내에서 해결해보려고 계속 노력해보았으나 계속하여 실패하였다.

Content type 'application/octet-stream' not supported

---

2. 왜 이런 문제가 발생하는가?

Spring MVC는 multipart 요청을 처리할 때 다음 흐름을 따른다.

Client (multipart/form-data)
        → DispatcherServlet
        → HandlerAdapter
        → @RequestPart(webRequest) 바인딩
        → HttpMessageConverter 선택

이때 Converter 선택 기준은 Content-Type + 파라미터 타입이다.\

• 정상이라면 application/json → MappingJackson2HttpMessageConverter
  선택 → DTO 변환 성공
• 잘못 들어오면 application/octet-stream → Jackson 후보에서 제외 →
  변환 실패

즉, JSON이 octet-stream으로 들어오면 Jackson이 건드리지 못한다는 게
핵심 문제다.

---

3. 해결 전략: 읽기 전용 Jackson 컨버터 추가

이상적인 해결은 프론트/테스트 도구가 반드시 application/json으로
보내도록 강제하는 것이다.
하지만 현실적으로는 실수가 반복된다. 따라서 서버에서 방어적으로
처리해주는 것이 더 실무적이다.

👉 이에 대한 해결방법은 간단함
**Jackson 컨버터가 application/octet-stream이더라도 읽기(read)는 Jackson으로 시도하게 만든다.

그래서 webRequest 파트가 octet-stream으로 들어와도 강제로 JSON 파싱을 시도해서 DTO로 바인딩할 수 있다.
단, 응답(쓰기)에는 관여하지 않도록 canWrite는 모두 false 처리한다.

구현 코드

@Component
public class MultipartJackson2HttpMessageConverter extends AbstractJackson2HttpMessageConverter {

    public MultipartJackson2HttpMessageConverter(ObjectMapper objectMapper) {
        super(objectMapper, MediaType.APPLICATION_OCTET_STREAM);
    }

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

@Configuration
class WebConfig implements WebMvcConfigurer {
    private final MultipartJackson2HttpMessageConverter octetReader;

    WebConfig(MultipartJackson2HttpMessageConverter octetReader) {
        this.octetReader = octetReader;
    }

    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 읽기 전용 octet-stream Jackson 컨버터를 최상단에 추가
        converters.add(0, octetReader);
    }
}

이제 webRequest 파트가 종종 application/octet-stream으로 들어와도
Jackson이 읽어서 DTO 변환을 수행할 수 있다.

---

4. 요청 예시

✅ 정상 (application/json)

curl -X POST http://localhost:8080/projects/upload   -H "Content-Type: multipart/form-data"   -F "thumbnailFile=@/path/to/image.png"   -F 'webRequest={
        "title":"프로젝트명",
        "topicId":2,
        "analysisPurposeId":2,
        "dataSourceId":3,
        "authorLevelId":3,
        "isContinue":true,
        "parentProjectId":3,
        "content":"지금 데이터 출처에 대해서 ~~.",
        "dataIds":[1,3]
      };type=application/json'

⚠️ 실수 (application/octet-stream) → 커스텀 컨버터가 처리

curl -X POST http://localhost:8080/projects/upload   -H "Content-Type: multipart/form-data"   -F "thumbnailFile=@/path/to/image.png"   -F 'webRequest={
        "title":"프로젝트명",
        "topicId":2,
        "analysisPurposeId":2,
        "dataSourceId":3,
        "authorLevelId":3,
        "isContinue":true,
        "parentProjectId":3,
        "content":"지금 데이터 출처에 대해서 ~~.",
        "dataIds":[1,3]
      }'

---

5. DTO 검증 설계

여기 WebRequest에 쓰인 UploadProjectWebRequest는 단순한 JSON 컨테이너가 아니라, 입력 규칙을
명확히 잡아주는 계약이다.

@Schema(description = "프로젝트 업로드 웹 요청 DTO")
public record UploadProjectWebRequest(
        @NotBlank(message = "제목을 입력해주세요")
        String title,

        @NotNull @Min(1)
        Long topicId,

        @NotNull @Min(1)
        Long analysisPurposeId,

        @NotNull @Min(1)
        Long dataSourceId,

        @NotNull @Min(1)
        Long authorLevelId,

        @NotNull
        Boolean isContinue,

        @Min(1)
        Long parentProjectId,

        @NotBlank(message = "내용을 입력해주세요")
        String content,

        @NotNull
        List<Long> dataIds
) {}

---

6. 흐름 다이어그램

---

7. 결론

• 문제 원인: multipart 요청에서 DTO 파트의 Content-Type이
  application/json이 아니면 Jackson 컨버터가 작동하지 않는다.\
• 해결 방법: 읽기 전용 MultipartJackson2HttpMessageConverter를
  등록해 application/octet-stream도 JSON으로 파싱되도록 한다.\
• 실무 포인트: DTO 검증, 에러 응답 표준화, 파일-메타 일관성,
  보안/모니터링까지 함께 챙겨야 한다.

👉 이렇게 설정해두면 Swagger/Postman/프론트 실수까지 방어할 수 있고,
API 사용성이 크게 개선된다. 🚀