폼 모델

폼 모델 (Form Models)

Pydantic 모델을 사용해서 FastAPI에서 폼 필드를 선언할 수 있습니다.

!!! note "참고" 폼을 사용하려면 먼저 python-multipart를 설치하세요.

프로젝트에 추가합니다:

```
$ uv add python-multipart
```

!!! note "참고" 이 기능은 FastAPI 버전 0.113.0부터 지원됩니다. 🤓

출처: 공식문서

폼을 위한 Pydantic 모델 (Pydantic Models for Forms)

폼 필드로 받고 싶은 필드로 Pydantic 모델을 선언하고, 그다음 파라미터를 Form으로 선언하기만 하면 됩니다:

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

🤓 다른 버전과 변형

!!! tip "팁" 가능하다면 Annotated 버전을 사용하는 걸 권장합니다.

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

FastAPI는 요청의 form data에서 필드별로 데이터를 추출해서, 여러분이 정의한 Pydantic 모델을 돌려줍니다.

문서에서 확인하기 (Check the Docs)

/docs의 문서 UI에서 확인할 수 있습니다.

추가 폼 필드 금지하기 (Forbid Extra Form Fields)

몇몇 특수한 경우(아마 흔하지는 않겠지만)에는 폼 필드를 Pydantic 모델에 선언된 것들로만 제한하고, 추가 필드는 금지하고 싶을 수 있어요.

!!! note "참고" 이 기능은 FastAPI 버전 0.114.0부터 지원됩니다. 🤓

Pydantic 모델 설정을 사용해서 extra 필드를 forbid할 수 있습니다:

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

🤓 다른 버전과 변형

!!! tip "팁" 가능하다면 Annotated 버전을 사용하는 걸 권장합니다.

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

클라이언트가 추가 데이터를 보내려고 하면 오류 응답을 받게 됩니다.

예를 들어 클라이언트가 다음 폼 필드들을 보내려고 하면:

• username: Rick
• password: Portal Gun
• extra: Mr. Poopybutthole

extra 필드는 허용되지 않는다는 오류 응답을 받게 됩니다:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["body", "extra"],
            "msg": "Extra inputs are not permitted",
            "input": "Mr. Poopybutthole"
        }
    ]
}

요약 (Summary)

FastAPI에서 Pydantic 모델로 폼 필드를 선언할 수 있습니다. 😎

더 알아보기 (Learn more)

• 폼을 받으려면 먼저 python-multipart를 설치해야 합니다.
• 관련 폼 필드들을 Pydantic 모델로 묶어 재사용하고, 검증과 메타데이터를 한 번에 선언하세요.
• model_config = {"extra": "forbid"}로 예상 밖의 폼 필드를 거부할 수 있습니다.