[참고] x-www-form-urlencoded 파싱

Jan 29, 2026

Contents

1️⃣ 핵심 요약 2️⃣ x-www-form-urlencoded가 자동으로 파싱되는 이유 3️⃣ 왜 JSON은 자동으로 안 될까?4️⃣ multipart/form-data도 자동이 아닌 이유 5️⃣ 정리: Content-Type별 처리 방식 6️⃣ 실습에서 기억하면 좋은 한 문장

💡

Spring MVC 실습 - @PostMapping에서 x-www-form-urlencoded는 자동으로 파싱된다!

1️⃣ 핵심 요약

Spring MVC에서 @PostMapping으로 요청을 받을 때

✅ application/x-www-form-urlencoded

→ 자동으로 파싱됨

❌ application/json, multipart/form-data 등

→ 추가 설정이나 어노테이션이 필요

이 차이는 Spring의 데이터 바인딩 방식과 HttpMessageConverter 동작 차이 때문입니다.

2️⃣ x-www-form-urlencoded가 자동으로 파싱되는 이유

1) HTML `<form>`의 기본 전송 방식


<form method="post" action="/users">
  <input name="name" value="kim"/>
  <input name="age" value="20"/>
</form>

이 경우 브라우저는 기본적으로


Content-Type: application/x-www-form-urlencoded

형태로 요청을 보냄

전송되는 실제 바디는:


name=kim&age=20

2) Spring MVC의 기본 동작

Spring MVC는 이 타입을 보면 내부적으로 다음 과정을 거침

Servlet 컨테이너(Tomcat) 가 먼저 파싱

파싱된 값들을 HttpServletRequest.getParameter() 로 제공

Spring은 이를 기반으로 Data Binding 수행

➡️ 아래 코드가 아무 설정 없이 동작


@PostMapping("/users")
public String create(User user) {
    // name, age 자동 바인딩
}

또는


@PostMapping("/users")
public String create(
    @RequestParam String name,
    @RequestParam int age
) {
}

➡️ 이 과정은 **JSON 파싱이 아니라 “파라미터 매핑”**

3️⃣ 왜 JSON은 자동으로 안 될까?

1) JSON 요청 예시


POST /users
Content-Type: application/json

{
  "name": "kim",
  "age": 20
}

이 경우:

getParameter() 로는 값을 꺼낼 수 ❌

요청 바디를 직접 읽어서 객체로 변환해야 함

➡️ Spring은 HttpMessageConverter 를 사용

2) 이때 필요한 것


@PostMapping("/users")
public String create(@RequestBody User user) {
}

@RequestBody를 붙이면

MappingJackson2HttpMessageConverter

JSON → Java 객체 변환 수행

➡️ **어노테이션이 없으면 Spring은 “바디를 읽지 않는다”**고 생각하면 됨

4️⃣ multipart/form-data도 자동이 아닌 이유

파일 업로드 예시:


Content-Type: multipart/form-data

이 경우도:

단순 key-value가 아님

boundary 기반으로 파싱 필요

그래서 아래처럼 받아야 함


@PostMapping("/upload")
public String upload(
    @RequestParam MultipartFile file,
    @RequestParam String title
) {
}

5️⃣ 정리: Content-Type별 처리 방식

Content-Type	처리 방식	어노테이션
`x-www-form-urlencoded`	Servlet 파라미터 바인딩	❌ 불필요
`query string`	Servlet 파라미터 바인딩	`@RequestParam`
`application/json`	HttpMessageConverter	`@RequestBody`
`multipart/form-data`	Multipart Resolver	`@RequestParam`, `MultipartFile`

6️⃣ 실습에서 기억하면 좋은 한 문장

Spring에서 “자동으로 파싱되는 것처럼 보이는 x-form”은 사실 JSON 파싱이 아니라 Servlet 파라미터 매핑이다.