HTTP Multipart/form-data 직접 파서 만들며 원리 이해하기

📦 Multipart/form-data 직접 파서 만들며 원리 이해하기

웹 개발을 하다 보면 파일 업로드 기능을 구현할 일이 많습니다. 보통은 Express에서 multer 같은 미들웨어를 쓰면 손쉽게 끝나는데요. 하지만 이번에는 라이브러리를 쓰지 않고, 직접 multipart/form-data를 파싱해보면서 동작 원리를 이해해고자 했습니다.

 

1. 왜 multipart/form-data인가?

일반적인 HTML <form>은 기본적으로 application/x-www-form-urlencoded 방식으로 데이터를 보냅니다.
하지만 파일 업로드처럼 대용량 이진 데이터가 포함되면 단순 URL 인코딩으로는 처리가 어렵습니다.
이때 사용하는 방식이 바로 multipart/form-data입니다.
여러 개의 파트를 하나의 요청에 담고, 각 파트를 boundary(경계 문자열) 로 구분하는 구조를 가집니다.

 

2. 요청 예시 살펴보기

예를 들어, 사용자가 username과 profile 이미지를 업로드했다고 해봅시다. 요청은 대략 다음과 같이 전송됩니다.
 

const formData = new FormData();
formData.append("title", "오늘의 점심");
formData.append("content", "김밥천국에서 라면 먹었다 🍜");
formData.append("date", "2025-10-01");
formData.append("photo", document.querySelector("input[type=file]").files[0]);

fetch("/upload", {
  method: "POST",
  body: formData
});

POST /upload HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryABC123
Content-Length: 51234

------WebKitFormBoundaryABC123
Content-Disposition: form-data; name="title"

오늘의 점심
------WebKitFormBoundaryABC123
Content-Disposition: form-data; name="content"

김밥천국에서 라면 먹었다 🍜
------WebKitFormBoundaryABC123
Content-Disposition: form-data; name="date"

2025-10-01
------WebKitFormBoundaryABC123
Content-Disposition: form-data; name="photo"; filename="lunch.jpg"
Content-Type: image/jpeg

(여기에 lunch.jpg 바이너리 데이터)
------WebKitFormBoundaryABC123--

 

• boundary 는 각 데이터 파트를 구분하는 문자열 이고
• 각 파트 는 헤더 + 공백줄 + 실제 데이터 로 이루어져 있습니다.

3. 파싱 절차 정리

1. Content-Type 헤더에서 boundary 추출→ boundary = ----WebKitFormBoundaryX
2. multipart/form-data; boundary=----WebKitFormBoundaryX
3. body를 boundary 기준으로 split
4. 각 파트에서 헤더/본문 분리
   • \r\n\r\n 기준으로 헤더와 데이터 구분
5. 헤더 해석
   • Content-Disposition에서 name, filename 추출
   • Content-Type이 있으면 파일 데이터
6. 데이터 저장
   • 일반 필드 → 문자열
   • 파일 → filename, contentType, 내용(Buffer)

 

4. 간단 파서 구현 (string split 버전)

아래는 이해를 위해 AI 에게 부탁한 간단 문자열 기반 간단 파서입니다.  ( 실제로는 Buffer 기반으로 확장이 필요 )
 
첫 헤더 기준으로 바운더리 문자열을 파악하고,
boundary 기준으로 바디 파트를 쪼개는 모습을 확인할 수 있습니다.

function getBoundary(contentType) {
  const match = contentType.match(/boundary=(.+)$/);
  return match && match[1];
}

function parseMultipart(body, contentType) {
  const boundary = getBoundary(contentType);
  const rawParts = body.split(`--${boundary}`);
  const result = {};

  for (const rawPart of rawParts) {
    if (rawPart.trim() === '' || rawPart === '--') continue;

    const [rawHeaders, rawBody] = rawPart.split('\r\n\r\n');
    if (!rawHeaders) continue;

    const nameMatch = rawHeaders.match(/name="([^"]+)"/);
    const filenameMatch = rawHeaders.match(/filename="([^"]+)"/);
    const contentTypeMatch = rawHeaders.match(/Content-Type: (.+)/);

    const name = nameMatch?.[1];
    const filename = filenameMatch?.[1];
    const contentType = contentTypeMatch?.[1];
    let value = rawBody.trim();

    if (filename) {
      result[name] = { filename, contentType, content: value };
    } else {
      result[name] = value;
    }
  }
  return result;
}

 

실행 예시

const body = `
------WebKitFormBoundaryX
Content-Disposition: form-data; name="username"

seoyeon
------WebKitFormBoundaryX
Content-Disposition: form-data; name="profile"; filename="me.png"
Content-Type: image/png

(binary-data-here)
------WebKitFormBoundaryX--
`;

const contentType = "multipart/form-data; boundary=----WebKitFormBoundaryX";
console.log(parseMultipart(body, contentType));

 
출력:

{
  username: "seoyeon",
  profile: {
    filename: "me.png",
    contentType: "image/png",
    content: "(binary-data-here)"
  }
}