[FastAPI] APIRouter로 라우팅 구조화하기

※ 이 글은 이노그리드 교육 과정의 일부로, 저만의 관점과 해석을 더해 작성되었습니다.

 

Intro

FastAPI로 간단한 웹 API를 만들면서

"주소(URL)에 따라 다양한 기능을 나누는 것"이

생각보다 쉽다는 걸 알게 된다.

 

이때 이 URL과 함수의 연결을 '라우팅(routing)'이라고 부른다.

초보 단계에서 한 파일에 쭉 나열해도 괜찮지만,

기능이 많아질수록

코드를 잘게 나눠 체계적으로 관리해야

유지보수가 편해진다.

 

이번 글에서는 FastAPI의 APIRouter 기능을 활용해

라우팅을 한 단계 "우아하게" 설계하는 방법을

예제와 함께 소개해 보겠다.

 

 

라우팅, 왜 분리해야 할까?

예를 들어보자.

• 처음엔 사용자 로그인/회원가입만 있던 API 서버가
• 어느새 상품 관리, 주문, 알림 등 기능이 늘어난다

 

이럴 때 한 파일에 모든 라우터를 몰아넣으면,

코드가 길어지고, 어디서 무슨 일을 하는지 찾기 힘들어진다.

 

마치 "모든 방이 하나로 연결된 집"에

모든 짐을 쑤셔 넣은 꼴이다.

 

 

APIRouter - 코드의 방을 따로 만드는 도구

APIRouter는 FastAPI에서
각 기능별로 "코드의 방"을 따로 만들어주는 도구다.

 

• 기능 단위로 라우터를 쪼갬
• 나중에 "메인 앱"에 합쳐서 실행
• 유지보수/확장성이 훨씬 좋아짐

 

현실 세계로 비유하면

기존 라우팅이 원룸이라면,

APIRouter는 방이 구분된 아파트 같은 느낌이다.

 

 

사용자와 상품 기능을 분리해보기

 

1. 프로젝트 구조 잡기

예를 들어, 아래처럼 폴더와 파일을 나눈다고 해보자.

myapp/
├── main.py
├── routers/
│   ├── users.py
│   └── items.py

• main.py
  앱의 시작점
• routers/
  각 기능별 라우터 모음

 

2. 사용자 기능 라우터 만들기

# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # 모든 경로 앞에 /users가 붙음
    tags=["users"],           # docs에서 구분되는 이름
)

@router.get("/")
def list_users():
    return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]

@router.get("/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": f"User{user_id}"}

 

3. 상품 기능 라우터 만들기

# routers/items.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/items",
    tags=["items"],
)

@router.get("/")
def list_items():
    return [{"id": 1, "title": "책"}, {"id": 2, "title": "노트북"}]

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id, "title": f"상품{item_id}"}

 

4. 라우터들을 합치기

# main.py
from fastapi import FastAPI
from routers import users, items

app = FastAPI()

app.include_router(users.router)
app.include_router(items.router)

• 각 라우터 모듈의 router를 메인 앱에 등록하는 것만으로
• /users, /items로 시작하는 모든 API가 자연스럽게 생긴다.

 

 

APIRouter 활용의 장점

• 기능별 코드 분리
  협업, 확장, 유지보수에 강하다
• 공통 prefix, 태그 지정
  자동 문서화에 카테고리로 구분
• 독립적인 미들웨어, 의존성 추가 가능
  (예: 특정 라우터만 별도 인증 적용 등)

 

 

마무리

FastAPI에서

APIRouter로 라우팅을 분리하는 것은

"코드를 방마다 깔끔하게 정리"하는 것과 같다.

 

코드가 많아질수록,

기능이 다양해질수록

APIRouter는 필수적인 도구가 된다.

 

 

참고 자료:

FastAPI Official Web Site - APIRouter.class

APIRouter class - FastAPI