🛤️ FastAPI 라우팅 완전 정복

🕒 약 2분 읽는 데 소요됩니다

이전 글 보기(FastAPI 기본 애플리케이션 만들기)

– 경로 매개변수와 쿼리 매개변수, 그리고 경로 연산자

“API 설계의 본질은 라우팅이다!”
FastAPI는 라우팅을 매우 직관적으로 설계할 수 있게 해주며, Flask와 비슷한 문법을 제공하면서도 훨씬 강력하고 명확한 타입 기반 처리를 제공합니다. 이 글에서는 경로 매개변수와 쿼리 매개변수, 그리고 HTTP 메서드별 경로 연산자를 자세히 다뤄보겠습니다.

---

✅ 라우팅이란 무엇인가?

라우팅(Routing)이란 사용자가 요청한 URL 경로에 따라 서버가 어떤 함수를 실행할지 결정하는 규칙을 말합니다. 예를 들어, 사용자가 /items/1로 GET 요청을 보내면, FastAPI는 이 경로를 핸들링할 함수를 찾아 응답합니다.

---

1. 📌 경로 연산자: @app.get, @app.post 등

FastAPI에서는 각 HTTP 요청 메서드(GET, POST, PUT, DELETE 등)에 대응하는 **데코레이터(Decorator)**를 제공합니다.

기본 예시:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

@app.post("/submit")
def submit_data():
    return {"status": "Data submitted"}

• @app.get("/"): 루트 경로에 GET 요청을 처리
• @app.post("/submit"): /submit 경로에 POST 요청을 처리

이 외에도 다음과 같은 연산자가 있습니다:

• @app.put() – 기존 자원의 전체 수정
• @app.patch() – 일부 수정
• @app.delete() – 삭제 요청

FastAPI는 HTTP 명세를 정확히 따르므로, RESTful API 설계에 매우 적합합니다.

---

2. 🛣 경로 매개변수 (Path Parameters)

경로 내에 변수처럼 값을 받을 수 있습니다. 예를 들어, /users/5처럼 URL에 포함된 숫자를 파라미터로 받을 수 있습니다.

사용 예:

@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

• {user_id}는 경로상의 변수이며,
• user_id: int는 해당 값이 정수임을 명시합니다.

타입 검사도 자동

• /users/5 → 정상 작동
• /users/abc → 422 오류 발생 (자동 유효성 검사)

Pydantic이나 별도의 검사 코드 없이도 타입을 자동으로 체크해주는 FastAPI의 큰 장점입니다.

---

3. 🔎 쿼리 매개변수 (Query Parameters)

쿼리 매개변수는 URL 뒤에 ?key=value 형식으로 추가되는 값입니다. 여러 개도 가능하고, 선택적으로 사용할 수 있습니다.

예를 들어 /items/?name=keyboard&price=49.99처럼 사용할 수 있죠.

사용 예:

@app.get("/items/")
def read_item(name: str = "default", price: float = 0.0):
    return {"name": name, "price": price}

• /items/?name=mouse&price=19.99 → { "name": "mouse", "price": 19.99 }
• /items/ → { "name": "default", "price": 0.0 }

필수 파라미터로 만들기

기본값 없이 정의하면 해당 쿼리 파라미터는 필수입니다.

@app.get("/search/")
def search(keyword: str):
    return {"result": f"Searching for {keyword}"}

• /search/?keyword=python → OK
• /search/ → 422 오류 (keyword 누락)

---

4. 🎯 경로 + 쿼리 매개변수 혼합 사용

FastAPI에서는 경로 매개변수와 쿼리 매개변수를 함께 사용할 수 있습니다. 예를 들어 특정 유저의 특정 게시글을 쿼리한다고 해볼까요?

@app.get("/users/{user_id}/posts/")
def read_user_post(user_id: int, sort_by: str = "date"):
    return {"user_id": user_id, "sort_by": sort_by}

• /users/10/posts/?sort_by=title → { "user_id": 10, "sort_by": "title" }
• /users/10/posts/ → { "user_id": 10, "sort_by": "date" } (기본값 사용)

---

5. 🎛 고급 라우팅: 경로 우선순위와 타입 구분

FastAPI는 경로 우선순위와 타입을 매우 엄격하게 구분합니다. 다음은 좋은 예시입니다:

@app.get("/items/{item_id}")
def read_item_by_id(item_id: int):
    return {"item_id": item_id}

@app.get("/items/special")
def read_special_item():
    return {"item": "special item"}

• /items/special → read_special_item 실행
• /items/42 → read_item_by_id 실행

하지만 순서가 반대였다면 /items/special이 숫자로 인식돼 오류가 날 수도 있습니다. 특정 문자열 경로는 위쪽에 먼저 정의해야 합니다.

---

6. 🧼 경로 파라미터의 검증 옵션

FastAPI는 Path, Query 객체를 사용해 세부 조건을 걸 수도 있습니다.

from fastapi import Path

@app.get("/products/{product_id}")
def get_product(product_id: int = Path(..., gt=0, lt=1000)):
    return {"product_id": product_id}

• gt=0: 0보다 큰 값만 허용
• lt=1000: 1000 미만 값만 허용

입력값이 조건을 만족하지 않으면 자동으로 422 에러를 반환합니다.

---

🧾 마무리: FastAPI 라우팅은 강력하면서도 직관적이다

FastAPI의 라우팅 시스템은 단순한 URL-함수 연결을 넘어서, 타입 안정성과 자동 유효성 검사, 문서 자동 생성, 명확한 코드 가독성까지 제공합니다. 이 기능들은 다른 프레임워크에선 추가 라이브러리를 붙여야 가능한 일들이지만, FastAPI에서는 기본입니다.

다음 글에서는 실제 데이터 모델을 정의하고, 응답 스키마와 예외 처리를 적용하면서 더 견고한 API를 만드는 방법을 소개할 예정입니다. FastAPI가 왜 백엔드 개발자들에게 사랑받는지, 더 깊이 체감할 수 있을 거예요.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/