FastAPI 쿼리 매개변수에 대해 알아야 할 모든 것 (모범 사례 포함)

FastAPI는 Python으로 API를 구축하기 위한 현대적이며 고성능의 웹 프레임워크입니다. 그 중 하나의 눈에 띄는 기능은 FastAPI 쿼리 매개변수를 처리하는 것으로, 개발자들이 유연하고 사용자 친화적인 API를 생성할 수 있게 해줍니다. 이 기사에서는 2024년 FastAPI 쿼리 매개변수를 효과적으로 사용하는 모범 사례와 기술을 살펴보겠습니다.

FastAPI 쿼리 매개변수를 사용하는 이유는 무엇인가요?

유연성: FastAPI 쿼리 매개변수는 클라이언트가 요청 결과를 사용자 정의할 수 있게 해줍니다. 예를 들어, 사용자는 카테고리, 가격 또는 평점과 같은 특정 기준에 따라 검색 결과를 필터링할 수 있습니다.
사용성: 클라이언트와 API 간의 상호작용을 간소화합니다. 클라이언트는 URL에 쿼리 매개변수를 쉽게 추가할 수 있으며, 개발자는 코드에서 이러한 매개변수를 신속하게 검증하고 처리할 수 있습니다.
성능: FastAPI 쿼리 매개변수를 사용하면 API에 필요한 엔드포인트 수를 줄일 수 있습니다. 각 필터링 옵션에 대해 별도의 엔드포인트를 생성하는 대신, 단일 엔드포인트가 여러 쿼리 매개변수를 처리할 수 있습니다.

FastAPI 쿼리 매개변수 사용 방법

FastAPI 쿼리 매개변수 정의하기

FastAPI에서 쿼리 매개변수를 정의하려면, 단순히 엔드포인트 정의의 함수 매개변수로 포함시키면 됩니다. 다음은 기본적인 예입니다:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, max_length=50),
    skip: int = Query(default=0, ge=0),
    limit: int = Query(default=10, le=100)
):
    return {"q": q, "skip": skip, "limit": limit}

이 예에서:

q: 최대 길이 50자의 선택적 문자열 매개변수입니다.
skip: 몇 개의 항목을 건너뛸지를 지정하는 정수 매개변수이며, 기본값은 0이고 최소값은 0입니다.
limit: 반환할 최대 항목 수를 지정하는 정수 매개변수이며, 기본값은 10이고 최대값은 100입니다.

FastAPI 쿼리 매개변수 접근하기

클라이언트가 엔드포인트에 요청을 하면, FastAPI는 URL에서 쿼리 매개변수를 자동으로 추출하여 함수에 전달합니다. 예를 들어, /items/?q=foo&skip=10&limit=5에 요청을 하면, 함수는 다음을 수신합니다:

q = "foo"
skip = 10
limit = 5

이 자동 추출 기능은 추가 파싱 로직 없이 FastAPI 쿼리 매개변수와 쉽게 작업할 수 있게 해줍니다.

선택적 및 필수 FastAPI 쿼리 매개변수

기본적으로 FastAPI 쿼리 매개변수는 선택적입니다. 요청에 매개변수가 제공되지 않으면, FastAPI는 지정된 기본값을 사용합니다. 쿼리 매개변수를 필수로 만들려면, 기본값을 생략하면 됩니다:

@app.get("/items/")
async def read_items(required_param: str):
    return {"required_param": required_param}

만약 required_param이 요청에 포함되지 않으면, FastAPI는 필수 쿼리 매개변수가 누락되었다는 것을 나타내는 422 Unprocessable Entity 오류를 반환합니다.

FastAPI 쿼리 매개변수에 대한 다중 값 처리하기

FastAPI는 여러 값을 수용할 수 있는 쿼리 매개변수를 정의할 수 있게 해줍니다. 매개변수 유형을 목록으로 지정하여 이를 수행할 수 있습니다:

from typing import List

@app.get("/items/")
async def read_items(q: List[str] = Query(default=[])):
    return {"q": q}

이 경우, 클라이언트는 /items/?q=foo&q=bar&q=baz와 같은 요청을 할 수 있으며, FastAPI는 값을 목록으로 파싱합니다. 이 기능은 사용자가 여러 기준에 따라 결과를 필터링하려는 경우에 특히 유용합니다.

💡

API 개발을 강화하고 싶으신가요? Apidog을 사용해 보세요. 이 강력한 도구는 FastAPI 프로젝트를 향상시키는 데 적합합니다. 무료로 사용해 보시고, 여러분의 작업 흐름을 얼마나 간소화하고 효율성을 높일 수 있는지 확인해 보세요.

button

FastAPI 쿼리 매개변수 검증하기

FastAPI는 Query 함수를 사용하여 쿼리 매개변수에 대한 내장 검증을 제공합니다. 최소 및 최대 값, 길이 제한, 정규 표현식 패턴과 같은 제약 조건을 지정할 수 있습니다. 다음은 예입니다:

@app.get("/items/")
async def read_items(
    q: str = Query(default=None, min_length=3, max_length=50),
    item_id: int = Query(ge=1, le=100)
):
    return {"q": q, "item_id": item_id}

이 예제에서 q는 최소 길이 3 및 최대 길이 50인 문자열이어야 합니다. item_id는 1과 100 사이의 정수여야 합니다. FastAPI는 이러한 제약 조건을 자동으로 검증하고, 입력이 지정된 기준을 충족하지 않으면 오류를 반환합니다.

FastAPI와 OpenAPI를 사용한 자동 문서 생성

FastAPI를 사용하는 눈에 띄는 장점 중 하나는 OpenAPI와의 원활한 통합으로, 상호작용 가능한 API 문서를 자동으로 생성할 수 있다는 점입니다. 이 기능은 API의 사용성을 높이고, API를 사용하는 개발자에게 더 나은 경험을 제공합니다. FastAPI가 이를 어떻게 달성하는지, 쿼리 매개변수 문서를 어떻게 향상시킬 수 있는지 자세히 살펴보겠습니다.

OpenAPI란 무엇인가요?

OpenAPI는 API를 구축하기 위한 사양으로, API의 기능을 설명하는 표준 방법을 제공합니다. 이를 통해 인간과 기계 모두 서비스의 기능을 파악할 수 있으며, 소스 코드를 액세스하거나 추가 문서를 볼 필요가 없습니다. FastAPI는 이 사양을 활용하여 API 엔드포인트의 상호작용 문서를 자동으로 생성합니다.

FastAPI가 문서를 생성하는 방법

FastAPI 애플리케이션과 그 엔드포인트를 정의하면, FastAPI는 정의한 함수 시그니처와 매개변수 유형을 기반으로 OpenAPI 스키마를 자동으로 생성합니다. 이 스키마는 다음을 포함합니다:

엔드포인트 경로: 애플리케이션에서 정의한 라우트입니다.
HTTP 메서드: 각 엔드포인트와 연결된 메서드(GET, POST, PUT, DELETE 등)입니다.
매개변수: 경로 및 쿼리 매개변수, 그 유형, 기본값 및 제약 조건을 포함합니다.
응답 모델: 각 엔드포인트의 예상 응답 형식입니다.

FastAPI와 함께하는 인터랙티브 문서 만들기

FastAPI는 기본 제공으로 두 가지 인터랙티브 문서 인터페이스를 제공합니다:

Swagger UI: /docs에서 액세스할 수 있는 이 인터페이스는 사용자가 API의 엔드포인트를 탐색하고, 요청 및 응답 형식을 보고, 심지어 브라우저에서 직접 엔드포인트를 테스트할 수 있게 해줍니다.
ReDoc: /redoc에서 사용 가능한 이 인터페이스는 API 문서의 보다 자세하고 구조화된 보기를 제공하여 여러 엔드포인트와 그 매개변수를 쉽게 탐색하고 이해할 수 있게 만듭니다.

두 인터페이스 모두 FastAPI에 의해 생성된 OpenAPI 스키마를 기반으로 자동 생성되므로, 문서가 항상 코드와 일치하곤 합니다.

쿼리 매개변수 문서 향상하기

FastAPI는 쿼리 매개변수에 대한 기본 문서를 생성하지만, 명확한 설명, 예제 및 추가 메타데이터를 제공하여 이를 더욱 향상시킬 수 있습니다. 방법은 다음과 같습니다:

설명 텍스트: Query 함수의 description 매개변수를 사용하여 각 쿼리 매개변수가 수행하는 작업에 대한 명확한 설명을 제공합니다. 이는 API에 익숙하지 않은 사용자에게 특히 유용합니다.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="아이템 필터링을 위한 검색어입니다."),
    skip: int = Query(default=0, ge=0, description="건너뛸 아이템 수입니다."),
    limit: int = Query(default=10, le=100, description="반환할 최대 아이템 수입니다.")
):
    return {"q": q, "skip": skip, "limit": limit}

2. 예제: 쿼리 매개변수 예제를 제공하여 사용 방법을 보여주십시오. 이는 복잡한 매개변수나 따라야 할 특정 형식이 있는 경우에 특히 유용합니다.

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="아이템 필터링을 위한 검색어입니다.", example="apple"),
    skip: int = Query(default=0, ge=0, description="건너뛸 아이템 수입니다.", example=5),
    limit: int = Query(default=10, le=100, description="반환할 최대 아이템 수입니다.", example=20)
):
    return {"q": q, "skip": skip, "limit": limit}

3. 검증 제약 조건: 쿼리 매개변수에 대한 모든 검증 제약 조건을 명확히 명시하십시오. 여기에는 최소 및 최대 값, 길이 제한 및 특정 형식이 포함됩니다. FastAPI는 이러한 검증을 자동으로 처리하지만, 이를 문서화하면 사용자가 제한을 이해하는 데 도움이 됩니다.

4. 유형 주석: 쿼리 매개변수에 적절한 유형 주석을 사용하십시오. FastAPI는 이러한 주석을 사용하여 문서에 예상 데이터 유형을 자동으로 생성하며, 이는 사용자가 제공해야 할 데이터 유형을 이해하는 데 도움이 됩니다.

5. 관련 매개변수 그룹화: API에 여러 관련 쿼리 매개변수가 있는 경우, 논리적으로 그룹화하는 것을 고려하십시오. 이는 사용자가 매개변수 간의 상호작용과 유효한 조합을 이해하는 데 도움이 될 수 있습니다.

향상된 문서의 장점

향상된 사용성: 잘 문서화된 쿼리 매개변수는 개발자가 API와 상호작용하는 방법을 이해하는 데 도움이 됩니다. 이는 학습 곡선을 줄이고 채택을 증가시킵니다.
지원 요청 감소: 명확한 문서는 일반적인 질문에 대한 답변을 제공하고, 사용자가 API 사용 방법을 이해하려고 할 때 지원 요청 수를 줄여줄 수 있습니다.
빠른 개발: 개발자는 애플리케이션을 구축하는 동안 문서를 신속하게 참조할 수 있으며, 이는 빠른 통합 및 개발 주기로 이어집니다.
API 채택 증가: 포괄적이고 사용자 친화적인 문서는 더 많은 개발자가 API를 사용하도록 유도할 수 있어, API의 전체 성공과 범위를 향상시킵니다.
일관성: 자동 문서는 API 문서가 실제 구현과 일관되도록 보장하여 혼란을 초래할 수 있는 불일치를 줄여줍니다.

FastAPI 쿼리 매개변수에 대한 고급 기술

FastAPI 쿼리 매개변수에 Enum 사용하기

Python Enum을 사용하여 FastAPI 쿼리 매개변수를 미리 정의된 값 집합으로 제한할 수 있습니다. 이는 특정 옵션만 허용해야 하는 매개변수에 유용합니다:

from enum import Enum

class ItemType(str, Enum):
    fruit = "fruit"
    vegetable = "vegetable"
    dairy = "dairy"

@app.get("/items/")
async def read_items(item_type: ItemType):
    return {"item_type": item_type}

이 예제에서 item_type 쿼리 매개변수는 ItemType Enum에 정의된 값 중 하나만 사용할 수 있습니다. 클라이언트가 잘못된 값을 제공하면, FastAPI는 422 오류를 반환합니다.

쿼리 매개변수 종속성

FastAPI는 여러 엔드포인트에서 논리를 재사용하는 데 도움이 되는 쿼리 매개변수에 대한 종속성을 생성할 수 있게 해줍니다. 쿼리 매개변수를 기반으로 값을 반환하는 종속성 함수를 정의할 수 있습니다:

from fastapi import Depends

def query_param_dependency(q: str | None = None):
    return q if q else "default"

@app.get("/items/")
async def read_items(q: str = Depends(query_param_dependency)):
    return {"q": q}

이 예제에서 query_param_dependency 함수는 쿼리 매개변수 q가 제공되었는지 확인합니다. 제공되지 않으면 기본값을 반환합니다. 이 접근 방식은 코드 재사용성을 촉진하고 엔드포인트 함수를 깔끔하게 유지합니다.

FastAPI 쿼리 매개변수 오류 처리하기

FastAPI는 쿼리 매개변수와 관련된 오류를 자동으로 처리합니다. 필수 쿼리 매개변수가 누락되거나 매개변수가 검증에 실패하면 FastAPI는 422 Unprocessable Entity 응답과 상세한 오류 메시지를 반환합니다. 예외 처리기를 사용하여 오류 처리를 사용자화할 수 있습니다:

from fastapi import HTTPException

@app.get("/items/")
async def read_items(q: str | None = Query(default=None)):
    if q is None:
        raise HTTPException(status_code=400, detail="쿼리 매개변수 'q'는 필수입니다.")
    return {"q": q}

이 예제에서는 필수 쿼리 매개변수가 제공되지 않았을 때 사용자 지정 HTTP 예외를 발생시키는 방법을 보여줍니다. 이 접근 방식은 클라이언트에게 더 많은 정보를 제공하는 오류 메시지를 제공할 수 있게 해줍니다.

FastAPI 쿼리 매개변수 테스트하기

FastAPI 애플리케이션을 테스트하는 것은 쿼리 매개변수가 예상대로 작동하는지 확인하는 데 매우 중요합니다. httpx 라이브러리를 사용하여 FastAPI 엔드포인트에 대한 테스트를 수행할 수 있습니다. 다음은 예제입니다:

import httpx
import pytest

@pytest.mark.asyncio
async def test_read_items():
    async with httpx.AsyncClient() as client:
        response = await client.get("http://localhost:8000/items/?q=test&skip=0&limit=10")
        assert response.status_code == 200
        assert response.json() == {"q": "test", "skip": 0, "limit": 10}

이 테스트에서는 쿼리 매개변수로 /items/ 엔드포인트에 GET 요청을 하고, 응답이 예상대로인지 확인합니다. 테스트는 개발 과정에서 필수적인 부분으로, FastAPI 쿼리 매개변수를 처리할 때 API가 올바르게 작동하는지 확인합니다.

결론

FastAPI 쿼리 매개변수는 URL을 통해 API 엔드포인트에 추가 데이터를 전달할 수 있는 강력한 기능입니다. 이는 FastAPI로 API를 구축할 때 유연성, 사용성 및 성능 이점을 제공합니다. 이 가이드에서는 FastAPI 쿼리 매개변수를 정의하고, 접근하고, 검증하고, 문서화하는 방법을 자세한 예와 함께 살펴보았습니다. 우리는 선택적 및 필수 매개변수, 다중 값, 복잡한 유형 및 자동 문서 생성과 같은 주제를 다루었습니다. 또한 고급 기술, 오류 처리, 테스트 및 일반적인 함정을 논의하였습니다. FastAPI 쿼리 매개변수를 활용함으로써 여러 전용 엔드포인트 없이도 다양한 필터링, 정렬 및 페이지 요구 사항을 처리할 수 있는 더 유연하고 사용자 친화적인 API를 생성할 수 있습니다. 적절한 매개변수 유형, 검증 및 설명을 선택하여 API가 사용하기 쉽고 고객을 위해 잘 문서화되도록 하십시오. FastAPI의 강력한 쿼리 매개변수 기능은 API의 기능과 사용성을 크게 향상시켜 현대 웹 애플리케이션에 적합한 선택이 됩니다.

FastAPI에 대한 추가 자료

FastAPI 쿼리 매개변수에 대한 이해를 더욱 향상시키기 위해 다음 자료를 살펴보는 것을 고려해 보십시오:

FastAPI 문서: 공식 FastAPI 문서는 쿼리 매개변수 및 기타 기능에 대한 포괄적인 정보를 제공합니다.
FastAPI GitHub 저장소: FastAPI GitHub 저장소에서 소스 코드, 예제 및 커뮤니티 기여를 확인하세요.
FastAPI 튜토리얼: FastAPI에 중점을 둔 온라인 튜토리얼 및 강의를 찾아 지식과 기술을 심화해 보세요.

FastAPI 쿼리 매개변수에 대한 이러한 모범 사례와 기술을 따르면, 2024년 및 그 이후에 사용자의 요구를 충족하는 견고하고 효율적인 API를 구축할 수 있습니다.

button