FastAPI 서버개발, 경로 매개변수 및 쿼리 매개변수 사용하기

FastAPI는 현대적인 웹 애플리케이션 개발을 위한 강력하고 효율적인 웹 프레임워크입니다. 특히 RESTful API를 쉽게 구축할 수 있도록 설계되어 있으며, Python의 타입 힌트를 활용하여 높은 성능을 자랑합니다. 본 포스트에서는 FastAPI에서 경로 매개변수와 쿼리 매개변수를 사용하는 방법에 대해 상세히 설명하겠습니다.

1. FastAPI 소개

FastAPI는 Starlette와 Pydantic을 기반으로 만들어진 현대적인 웹 프레임워크로, 다음과 같은 특징을 가지고 있습니다:

  • 비동기 프로그래밍 지원
  • 자동화된 문서화 지원 (Swagger UI, ReDoc)
  • 입력 데이터의 유효성 검사 및 직렬화
  • 높은 성능

2. 환경 설정

FastAPI를 사용하기 위해서는 Python과 pip가 설치되어 있어야 합니다. FastAPI와 Uvicorn을 설치하려면 다음 명령어를 실행합니다:

pip install fastapi uvicorn

3. FastAPI 서버 기본 구조

다음은 FastAPI 서버의 기본 구조를 정의한 예제입니다. 아래와 같이 구조를 잡아 초기 설정을 진행합니다:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Welcome to FastAPI!"}

위 코드를 main.py라는 파일에 저장합니다. 서버를 실행하기 위해 아래 명령어를 실행하십시오:

uvicorn main:app --reload

이제 브라우저에서 http://127.0.0.1:8000에 접속하면 “Welcome to FastAPI!”라는 메시지를 확인할 수 있습니다.

4. 경로 매개변수 사용하기

경로 매개변수는 URL 경로의 일부로 사용되는 매개변수입니다. 예를 들어, 특정 유저의 정보를 조회하는 API를 만들 때 사용할 수 있습니다.

4.1 기본적인 경로 매개변수 예제

경로 매개변수를 사용하는 예제를 살펴보겠습니다. 아래 코드는 유저 ID를 받아 해당 유저의 정보를 반환하는 API를 구현한 것입니다:

from fastapi import FastAPI

app = FastAPI()

# 간단한 유저 데이터베이스 (예: 딕셔너리)
users = {1: {"name": "Alice"}, 2: {"name": "Bob"}}

@app.get("/users/{user_id}")
async def read_user(user_id: int):
    user = users.get(user_id)
    if user:
        return user
    return {"message": "User not found"}

위 예제에서 user_id는 경로 매개변수입니다. 사용자가 /users/1를 요청하면, 서버는 유저 ID가 1인 유저의 정보를 반환합니다. 만약 존재하지 않는 ID를 요청할 경우, “User not found” 메시지를 반환합니다.

4.2 경로 매개변수의 유효성 검사

FastAPI는 경로 매개변수의 타입을 자동으로 검사합니다. 예를 들어, user_id: int로 정의했기 때문에, 만약 사용자가 /users/abc와 같이 요청하면 422 Unprocessable Entity 에러가 발생합니다. 적절한 데이터 타입을 전송할 것이라는 기대를 통해 API의 안정성을 증가시킵니다.

4.3 경로 매개변수와 다양한 타입

경로 매개변수는 다양한 타입을 사용할 수 있습니다. 아래 예제에서는 문자열과 부동 소수점 숫자를 사용하는 방법을 보여드립니다:

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: float):
    return {"item_id": item_id, "query": q}

여기서 item_id는 문자열이며, q는 쿼리 매개변수로 부동 소수점 타입입니다. /items/abc?q=3.14와 같은 요청은 정상적으로 처리됩니다.

5. 쿼리 매개변수 사용하기

쿼리 매개변수는 URL의 쿼리 문자열에서 전달되는 매개변수입니다. GET 요청에서 주로 사용되며, 주어진 데이터에 대해 필터링하거나 추가 정보를 요청하는 데 사용됩니다.

5.1 기본적인 쿼리 매개변수 예제

다음은 쿼리 매개변수를 사용하여 사용자 목록을 필터링하는 예제입니다:

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

users = {
    1: {"name": "Alice", "age": 28},
    2: {"name": "Bob", "age": 34},
    3: {"name": "Charlie", "age": 22},
}

@app.get("/users/")
async def filter_users(min_age: Optional[int] = None):
    filtered_users = {uid: user for uid, user in users.items() if (min_age is None or user["age"] >= min_age)}
    return filtered_users

위의 예제에서 min_age는 선택적인 쿼리 매개변수로 어떤 유저 목록을 반환할지를 결정합니다. 사용자가 /users/?min_age=30를 호출하면 나이가 30세 이상의 사용자만 반환됩니다.

5.2 쿼리 매개변수의 기본값

쿼리 매개변수는 기본값을 지정할 수 있습니다. 예를 들어, 기본값을 0으로 설정하면 클라이언트가 매개변수를 제공하지 않는 경우에도 호출이 가능해집니다:

@app.get("/users/")
async def filter_users(min_age: int = 0):
    filtered_users = {uid: user for uid, user in users.items() if user["age"] >= min_age}
    return filtered_users

이 경우, 기본적으로 모든 사용자가 반환됩니다. 사용자가 /users/?min_age=30와 같이 요청하면, 나이가 30세 이상의 사용자만 필터링되어 반환됩니다.

5.3 복수의 쿼리 매개변수 사용하기

쿼리 매개변수를 여러 개 지정할 수도 있습니다. 예를 들어, 사용자 나이와 이름으로 필터링하는 API는 아래와 같이 구현할 수 있습니다:

@app.get("/users/")
async def filter_users(min_age: Optional[int] = None, name: Optional[str] = None):
    filtered_users = {uid: user for uid, user in users.items() 
                      if (min_age is None or user["age"] >= min_age) and 
                      (name is None or user["name"] == name)}
    return filtered_users

위 예제는 나이와 이름으로 필터링하는 구조입니다. 예를 들어, /users/?min_age=28&name=Alice를 호출하면 나이가 28세 이상이면서 이름이 ‘Alice’인 사용자만 반환됩니다.

6. FastAPI의 데이터 모델 사용하기

데이터베이스와 상호작용하는 API를 개발할 때 Pydantic 모델을 활용하면, 입력 데이터의 유효성을 더욱 쉽게 검사할 수 있습니다. 모델을 정의하고 이를 경로 매개변수 또는 쿼리 매개변수로 사용할 수 있습니다.

6.1 Pydantic 모델 정의하기

다음은 FastAPI에서 Pydantic 모델을 사용하여 유저의 정보를 구조화하는 예제입니다:

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

@app.post("/users/")
async def create_user(user: User):
    user_id = len(users) + 1
    users[user_id] = user.dict()
    return {"user_id": user_id, "user": user}

위 코드는 유저 정보를 JSON으로 전송받아 새로운 유저를 생성하는 API를 구현한 것입니다. JSON 형식의 데이터를 입력하면 유저 ID와 함께 생성된 사용자 정보를 반환합니다.

7. 결론

FastAPI는 경로 매개변수와 쿼리 매개변수를 유연하고 강력하게 처리할 수 있는 기능을 제공합니다. 이러한 매개변수들을 통해 다양한 형태의 API를 쉽게 설계할 수 있습니다. 본 블로그 포스트에서는 기본적인 사용 방법을 소개하였으나, 실무에서는 보다 복잡한 비즈니스 로직을 구현하고, 다양한 데이터 처리 기법을 활용하여 제품의 가치를 높일 수 있습니다.

FastAPI를 활용한 서버 개발을 통해 성능 높은 API를 손쉽게 구축해보세요. 이제 여러분도 FastAPI의 매력을 느끼고 실제 애플리케이션에 적용하여 더욱 발전된 서비스를 만들어 나가길 바랍니다!