[새싹 성동 2기] FastAPI 쿼리 매개변수와 Query 클래스 활용법

 

FastAPI에서 쿼리 매개변수는 URL 경로에 포함되지 않고 ? 뒤에 추가되는 매개변수입니다. 주로 필터링, 정렬, 페이징 등의 작업을 위해 사용됩니다. 이번 글에서는 쿼리 매개변수를 활용하여 할 일 검색 기능을 구현하고, Query 클래스를 사용하여 유효성 검사 및 메타데이터 추가 방법을 다룹니다.

 

쿼리 매개변수를 활용한 할 일 검색

할 일을 추가, 조회, 검색하는 간단한 API를 FastAPI로 구현합니다. 먼저 기본적인 코드부터 살펴보겠습니다.

코드: todo.py

from fastapi import APIRouter, Path
from model import Todo

# 라우터 생성
todo_router = APIRouter()

todo_list = []

@todo_router.post("/todo")
def add_todo(todo: Todo) -> dict:
    todo_list.append(todo)
    return {"message": "할 일을 추가합니다."}

@todo_router.get("/todo")
def retrives_todo() -> dict:
    return {"todos": todo_list}

# 할 일 검색(필터링)
@todo_router.get("/todo/search")
def search_todos(item: str) -> dict:
    result = []
    for todo in todo_list:
        if item in todo.item:
            result.append(todo)

    return {"todos": result}

@todo_router.get("/todo/{todo_id}")
def retrive_todo(todo_id: int = Path(..., title="조회할 할 일의 ID", ge=1)) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {"todo": todo}

    return {"message": "일치하는 할 일이 없습니다."}

테스트

할 일 추가

curl http://localhost:8000/todo -X POST -d "{ \"id\": 1, \"item\": \"First Todo\"}" -H "Content-Type: application/json"
# {"message":"할 일을 추가합니다."}

curl http://localhost:8000/todo -X POST -d "{ \"id\": 2, \"item\": \"Second Todo\"}" -H "Content-Type: application/json"
# {"message":"할 일을 추가합니다."}

할 일 목록 조회

curl http://localhost:8000/todo
# {"todos":[{"id":1,"item":"First Todo"},{"id":2,"item":"Second Todo"}]}

할 일 검색

curl http://localhost:8000/todo/search?item=First
# {"todos":[{"id":1,"item":"First Todo"}]}

curl http://localhost:8000/todo/search?item=none
# {"todos":[]}

 

Query 클래스를 활용한 쿼리 매개변수 유효성 검사 및 메타데이터 추가

FastAPI의 Query 클래스를 사용하면 클라이언트로부터 전달된 쿼리 파라미터의 유효성을 검증하고, 메타데이터를 추가하여 API 문서를 보강할 수 있습니다.

Query 클래스의 주요 기능

1. 기본값 설정: 쿼리 파라미터의 기본값을 설정할 수 있습니다.
2. 필수 여부 지정: 쿼리 파라미터의 필수 여부를 명시할 수 있습니다.
3. 유효성 검사: 길이, 정규식, 범위 등 제약 조건을 부여할 수 있습니다.
4. 메타데이터 추가: 설명, 예시 등 API 문서화에 필요한 정보를 제공할 수 있습니다.

코드: todo.py (Query 클래스 적용)

from fastapi import APIRouter, Path, Query
from model import Todo

# 라우터 생성
todo_router = APIRouter()

todo_list = []

@todo_router.post("/todo")
def add_todo(todo: Todo) -> dict:
    todo_list.append(todo)
    return {"message": "할 일을 추가합니다."}

@todo_router.get("/todo")
def retrives_todo() -> dict:
    return {"todos": todo_list}

# 할 일 검색(필터링)
@todo_router.get("/todo/search")
def search_todos(item: str = Query(..., min_length=2, max_length=10)) -> dict:
    result = []
    for todo in todo_list:
        if item in todo.item:
            result.append(todo)

    return {"todos": result}

@todo_router.get("/todo/{todo_id}")
def retrive_todo(todo_id: int = Path(..., title="조회할 할 일의 ID", ge=1)) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {"todo": todo}

    return {"message": "일치하는 할 일이 없습니다."}

테스트

길이 제약 조건 위반

curl http://localhost:8000/todo/search?item=
# {"detail":[{"type":"string_too_short","loc":["query","item"],"msg":"String should have at least 2 characters","input":"","ctx":{"min_length":2}}]}

필수 항목 누락

curl http://localhost:8000/todo/search?x=y
# {"detail":[{"type":"missing","loc":["query","item"],"msg":"Field required","input":null}]}

---

요약

1. 쿼리 매개변수는 URL 경로 뒤에 ?를 사용하여 추가하며, 필터링과 같은 작업에 활용됩니다.
2. Query 클래스를 사용하면 기본값 설정, 유효성 검사, 메타데이터 추가를 통해 API의 안정성과 문서화를 개선할 수 있습니다.
3. 예제를 통해 FastAPI의 강력한 기능과 테스트 방법을 이해할 수 있습니다.

 

 

 

 

*생성형 AI 활용한 클라우드&보안 전문가 양성캠프 과정의 교육내용 정리 자료입니다.