[새싹 성동 2기] FastAPI 라우팅 가이드

웹 애플리케이션에서 라우팅은 클라이언트 요청을 특정 함수나 로직에 매핑하는 중요한 과정입니다. FastAPI에서는 이를 "경로 운영자 데코레이터"를 사용해 손쉽게 정의할 수 있습니다. 또한, APIRouter 클래스를 이용해 라우트를 모듈화하고 그룹화할 수 있습니다. 이번 글에서는 FastAPI의 라우팅 개념과 사용 방법을 단계별로 설명합니다.

 

1. 경로 운영자 데코레이터

FastAPI에서 경로와 HTTP 메서드를 연결하기 위해 경로 운영자 데코레이터를 사용합니다. 이는 특정 HTTP 메서드와 경로에 요청이 들어왔을 때 실행할 함수를 정의합니다. 함수는 보통 비동기 함수(async def)로 작성되지만, 동기 함수(def)로도 가능합니다.

주요 데코레이터 종류:

• @app.get() : HTTP GET 요청 처리
• @app.post() : HTTP POST 요청 처리
• @app.put() : HTTP PUT 요청 처리
• @app.delete() : HTTP DELETE 요청 처리
• @app.patch() : HTTP PATCH 요청 처리
• @app.options() : HTTP OPTIONS 요청 처리
• @app.head() : HTTP HEAD 요청 처리
• @app.trace() : HTTP TRACE 요청 처리

예시:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def welcome() -> dict:
    return {"message": "Hello World"}

2. APIRouter 클래스를 이용한 라우팅 모듈화

APIRouter는 라우트를 모듈화하고 그룹화하는 데 유용합니다. 이를 사용하면 대규모 애플리케이션에서도 유지보수가 용이해집니다.

예제: 할 일 목록 애플리케이션

1. todo.py 파일 생성 및 라우트 정의:

   from fastapi import APIRouter
   
   todo_router = APIRouter()
   
   todo_list = []  # 할 일 목록 저장 리스트
   
   # 할 일 추가 라우트
   @todo_router.post("/todo")
   def add_todo(todo: dict) -> dict:
       todo_list.append(todo)
       return {"message": "할 일을 추가합니다."}
   
   # 할 일 조회 라우트
   @todo_router.get("/todo")
   def retrieve_todo() -> dict:
       return {"todos": todo_list}

   
   
2. app.py에서 APIRouter 추가:

   from fastapi import FastAPI
   from todo import todo_router
   
   app = FastAPI()
   
   @app.get("/")
   def welcome() -> dict:
       return {"message": "Hello World"}
   
   app.include_router(todo_router)

3. 테스트

FastAPI 서버를 실행하고 curl 명령어로 테스트합니다.

테스트 명령어 및 결과:

기본 경로 확인

curl http://localhost:8000/

출력:

{"message": "Hello World"}

 

할 일 목록 조회

curl http://localhost:8000/todo

출력:

{"todos": []}

 

할 일 추가

curl http://localhost:8000/todo -X POST -d "{ \"id\": 1, \"item\": \"첫번째 할 일\" }" -H "Content-Type: application/json"

출력:

{"message": "할 일을 추가합니다."}

 

할 일 목록 재조회

curl http://localhost:8000/todo

출력:

{"todos": [{"id": 1, "item": "첫번째 할 일"}]}

 

두 번째 할 일 추가

curl http://localhost:8000/todo -X POST -d "{ \"id\": 2, \"item\": \"두번째 할 일\"}" -H "Content-Type: application/json"

출력:

{"message": "할 일을 추가합니다."}

 

4. 요청 설명

curl 명령어의 주요 구성 요소:

• -X POST: 요청 방식을 POST로 지정 (기본값은 GET)
• -d: 요청 본문 데이터를 설정
• -H "Content-Type: application/json": 요청 헤더에 JSON 형식임을 명시
• 요청 데이터는 문자열 안에서 이스케이프 처리 필요

예시 명령어:

curl http://localhost:8000/todo -X POST -d "{ \"id\": 1, \"item\": \"첫번째 할 일\" }" -H "Content-Type: application/json"

• 요청 본문 데이터: { "id": 1, "item": "첫번째 할 일" }
• 데이터 내부의 쌍따옴표(")는 이스케이프(\) 처리

 

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