📝 Form Data – 폼 데이터 처리

웹에서 데이터를 서버로 보내는 방식은 하나가 아니다. 우리가 흔히 사용하는 JSON 외에도, 오래전부터 지금까지 계속 사용되는 방식이 있다.

바로 Form Data다.

Form Data는 단순한 옛날 방식이 아니다. 로그인, 회원가입, 파일 업로드처럼 지금도 가장 많이 쓰이는 핵심 데이터 전송 방식이다.

---

📌 1. Form이란 무엇인가

Form은 말 그대로 “양식”이다.

은행에서 계좌를 만들 때를 떠올려보자.

• 이름
• 전화번호
• 주소

정해진 칸에 값을 채워서 제출한다. 웹의 Form도 정확히 같은 역할을 한다.

HTML의 <form> 태그는 기본적으로 Form Data 형식으로 데이터를 전송한다.

---

⚙️ 2. FastAPI에서 Form Data 직접 받아보기

FastAPI에서 Form 데이터를 처리하려면 추가 패키지 하나가 필요하다.

📦 필수 패키지 설치

pip install python-multipart

FastAPI는 내부적으로 이 패키지를 사용해 Form 데이터를 파싱한다.

---

🧪 첫 번째 Form API

from typing import Annotated
from fastapi import FastAPI, Form
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
async def read_root():
    with open("login.html", "r", encoding="utf-8") as f:
        return f.read()

@app.post("/login/")
async def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()]
):
    return {"username": username}

---

🧭 실제로 무슨 일이 벌어질까?

브라우저에서 로그인 폼을 제출하면 요청은 이렇게 전송된다.

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

username=jay&password=1234

FastAPI 내부에서는 다음과 같이 변환된다.

login(username="jay", password="1234")

---

🧠 3. Form 데이터의 원리

서버로 데이터를 보내는 방식은 크게 두 가지다.

구분	JSON	Form Data
Content-Type	application/json	application/x-www-form-urlencoded
데이터 형태	{"username": "jeff"}	username=jeff&password=1234
주 사용처	API 통신, SPA	HTML 폼, 로그인

HTML의 <form> 태그는 무조건 Form Data 형식으로 전송한다.

❓ 왜 Form()을 꼭 써야 할까?

FastAPI는 파라미터의 출처를 매우 엄격하게 구분한다.

# ❌ 이렇게 쓰면 Query 파라미터로 인식
async def login(username: str, password: str):
    ...

# ✅ Form Data로 받으려면 반드시 Form() 필요
async def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()]
):
    ...

---

🔬 Form 클래스의 정체

Form은 내부적으로 Body를 상속한다.

그래서 다음과 같은 옵션들이 가능하다.

async def signup(
    username: Annotated[str, Form(min_length=3, max_length=20)],
    user_email: Annotated[str, Form(alias="email")],
    nickname: Annotated[str | None, Form()] = None
):
    return {"username": username, "email": user_email}

• 길이 제한
• 필드 이름 매핑(alias)
• 선택 값(None)

이 모든 것이 Form Data에서도 그대로 동작한다.

📤 전체 요청 흐름

 [브라우저]
   |
   | POST /login/
   | Content-Type: application/x-www-form-urlencoded
   | Body: username=jeff&password=1234
   v
[FastAPI]
   |
   | python-multipart
   | → Form 데이터 파싱
   v
[엔드포인트 함수]
   |
   | login(username="jeff", password="1234")
   v
[응답 반환]
   |
   | HTTP 200 OK
   | {"username": "jeff"}
   v
[브라우저]

🧩 단계별로 뜯어보기

① 브라우저 → 서버 요청

HTML <form> 태그를 통해 전송된 요청은 항상 Form Data 형식을 사용한다.

POST /login/ 
Content-Type: application/x-www-form-urlencoded 
username=jay&password=1234 

• JSON 아님
• Key=Value 형태
• & 로 필드 연결

---

② FastAPI 내부 처리

FastAPI는 요청을 받자마자 Content-Type을 먼저 확인한다.

• application/x-www-form-urlencoded
• → Form Data 요청이라고 판단

이때 내부적으로 python-multipart가 동작한다.

---

③ 함수 파라미터로 자동 주입

엔드포인트 함수가 다음과 같이 정의되어 있다면,

async def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()]
):
    ...

FastAPI는 자동으로 이렇게 호출한다.

 login(username="jay", password="1234") 

개발자가 직접 파싱할 필요는 전혀 없다.

---

④ 응답 반환 → 브라우저

함수의 반환값은 다시 HTTP 응답으로 변환되어 브라우저로 전달된다.

 HTTP 200 OK { "username": "jay" } 

이 모든 과정은 자동으로 처리된다.

---

⚠️ Form과 JSON을 함께 쓸 수 없는 이유

Form Data를 배우다 보면 반드시 한 번은 이런 질문이 나온다.

“Form으로 username 받고, JSON으로 다른 데이터도 같이 받으면 안 되나요?”

정답은 ❌ 불가능이다.

🚫 왜 불가능할까?

HTTP 요청의 Body는 하나의 Content-Type만 가질 수 있다.

구분	Content-Type
JSON	application/json
Form Data	application/x-www-form-urlencoded

즉,

• Form 파라미터가 하나라도 있으면 → Form 요청
• JSON Body를 동시에 받을 수 없음

---

🧠 추가로 반드시 알아야 할 핵심 개념

✔ Form 사용 체크리스트

• ☑ python-multipart 설치
• ☑ from fastapi import Form
• ☑ Annotated[타입, Form()] 사용
• ☑ JSON Body와 혼용하지 않기

---

✔ 언제 Form을 사용할까?

상황	이유
로그인 / 회원가입	HTML Form 표준
OAuth2 인증	스펙에서 Form 사용
파일 업로드	multipart/form-data 필요
레거시 시스템	JSON 미지원 환경

---

📌 5. 최종 정리

• Form Data는 HTML의 기본 데이터 전송 방식이다
• FastAPI에서는 Form()을 명시해야 한다
• Form 요청은 python-multipart가 파싱한다
• Form과 JSON은 동시에 사용할 수 없다