[Fastapi] 유효성 검사, 필수 매개변수, 쿼리 매개변수 목록/다중 값 처리

Fastapi 에서의 매개변수에 대한 유효성 검사

Fastapi을 사용한다면, 매개 변수에 대한 추가 정보 및 유효성 검사를 선언 할 수 있다. 

from typing import Union을 통해서 처리할 필요없이 | 이걸로 처리 하면 된다. 하지만 공식 문서에서는 | 처리보다는 Union[str, None] 처럼 명시적으로 처리하는 것을 더 추천하고 있다. 

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = None):
    
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

 

추가 유효성 검증

쿼리 매개변수에 대하여 추가적인 유효성을 검증하고 싶다면 Annotated와 Query을 이용한다. 

Python 3.9 version + 부터는 Annotated도 표준 라이브러리 일부분으로 나타내고 있다. fastapi 문서에서는 Annotated 사용을 적극 권장하는 편이다. 

 

예시)

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(max_length=50)] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

Annotated, Query() 을 통해서 매개변수의 default 값을 지정할 수 있다. 하지만 일반적인 Python 문법으로 매개변수에 기본 값을 지정할 때와 동시에 쓴다면 일관성에서의 문제가 있기 때문에 한 가지를 선택해서 하는 것을 추천한다. 문서에서는 Annoted을 통해 default 값을 지정하는 것을 추천하고 있다. 

 

- Annotated는 Query()을 쓰기 위한 하나의 장치라고 생각하면 편할 듯 하다. 

# 가능한 방법
q: Annotated[str, Query(default="rick")]
q: str = "rick"

# 불가능한 방법
q: Annotated[str, Query(default="rick")] = "mory"

 

 

 

더 많은 유효성을 검증하고 싶거나, 정규표현식을 나타내고 싶다면 다음과 같이 작성이 가능하다.

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[
        str | None, Query(min_length=3, max_length=50, regex="^fixedquery$")
    ] = None
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

 

Query에 사용할수 있는 매개변수들 

- min_legnth : 최소 길이를 제어 할 때 사용한다. 

- max_legnth : 최대 길이를 제어 할 때 사용한다.

- default : 기본 값을 지정 할 때 사용한다. 

- alias : 해당 쿼리 이름에 대항 별칭을 만들어준다. 

 

예제) q 가 아니라 item-query가 들어와도 q의 로직에 따라 처리 된다. 

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str | None, Query(alias="item-query")] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

실질적으로 유효성 검증하는 것들은 아니지만, API문서 (/redoc)에서 매개변수에 대한 설명을 첨부 할때 사용한다.

- title : 제목

- description : 설명

 

예제) 

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[
        str | None,
        Query(
            title="Query string",
            description="Query string for the items to search in the database that have a good match",
            min_length=3,
        ),
    ] = None
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

 

 

 

 

 

 

 

필수 매개 변수로 설정

다른 유효성 검사가 필요 없을 경우에는 기본 값을 선언하지 않고 매개 변수를 필수로 만들 수 있다.

q: str
q: Union[str, None]
q: Annotated[Union[str, None], Query(min_length=3)]

 

또는 줄임표 (...)을 통해서 해당 매개 변수의 값이 필수 임을 나타 낼 수 있다. 

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)] = ...):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

 

 

 

 

 

쿼리 매개변수 목록/다중 값 처리하기

만약 Get 요청으로 해당과 같은 쿼리 매개변수들이 담겨왔다고 가정한다. 

http://localhost:8000/items/?q=foo&q=bar

 

fastapi에서는 해당 매개변수들의 목록이나 다중 값들을 다음과 같이 처리 가능하다.

python 3.6 + 부터는 from typing import List을 가져와서 list[str]을 List[str]로 처리할수도 있다.

from typing import Annotated, Union

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[Union[list[str], None], Query()] = None):
    query_items = {"q": q}
    return query_items

 

 

목록/다중값이 제공되지 않는다면 기본값을 정의하여 처리 할 수 있다. 

from typing import Annotated

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Annotated[list[str], Query()] = ["foo", "bar"]):
    query_items = {"q": q}
    return query_items