[FastAPI] APIRouter

FastAPI에서 APIRouter를 사용하여 코드를 더 깔끔하고 모듈화된 방식으로 구성하는 방법에 대해 알아본다.

---

목차

• APIRouter가 필요한 이유
• APIRouter 기본 사용법
  • 1. 라우터 생성하기 (users.py)
  • 2. 메인 애플리케이션에 라우터 등록하기 (main.py)
• APIRouter의 고급 기능
  • 1. 공통 prefix 및 태그 설정
  • 2. 의존성 주입
• APIRouter 사용의 장점
• 실제 활용 예시
• 마무리

---

APIRouter가 필요한 이유

대규모 FastAPI 애플리케이션을 개발할 때, 모든 엔드포인트를 main.py 파일 하나에 작성하는 것은 비효율적이다. 코드가 길어지고 유지보수가 어려워진다. 이럴 때 APIRouter를 사용하면 관련된 엔드포인트들을 논리적으로 그룹화하고 모듈화할 수 있다.

 

APIRouter 기본 사용법

다음과 같이 프로젝트 구조를 만들어본다:

my_fastapi_app/
├── main.py
└── routers/
    ├── users.py
    └── items.py

1. 라우터 생성하기 (users.py)

from fastapi import APIRouter

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

@router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

@router.get("/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

2. 메인 애플리케이션에 라우터 등록하기 (main.py)

from fastapi import FastAPI
from routers import users, items

app = FastAPI()

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

@app.get("/")
async def root():
    return {"message": "Hello World"}

 

APIRouter의 고급 기능

1. 공통 prefix 및 태그 설정

router = APIRouter(
    prefix="/users",
    tags=["users"],
    responses={404: {"description": "Not found"}},
)

2. 의존성 주입

from fastapi import APIRouter, Depends

def get_token_header():
    return {"X-Token": "fake-token"}

router = APIRouter(
    dependencies=[Depends(get_token_header)]
)

 

APIRouter 사용의 장점

1. 코드 구조화: 관련된 엔드포인트들을 논리적으로 그룹화할 수 있다.
2. 재사용성: 라우터를 다른 프로젝트에서도 쉽게 재사용할 수 있다.
3. 유지보수성: 각 기능별로 코드가 분리되어 있어 유지보수가 쉬워진다.
4. 가독성: 전체 애플리케이션의 구조를 더 쉽게 이해할 수 있다.

 

실제 활용 예시

대형 프로젝트에서는 다음과 같이 라우터를 구성할 수 있다:

# routers/auth.py
router = APIRouter(prefix="/auth", tags=["authentication"])

# routers/users.py
router = APIRouter(prefix="/users", tags=["users"])

# routers/products.py
router = APIRouter(prefix="/products", tags=["products"])

# routers/orders.py
router = APIRouter(prefix="/orders", tags=["orders"])

 

마무리

APIRouter는 FastAPI 애플리케이션을 구조화하는 강력한 도구이다. 적절히 활용하면 코드의 가독성과 유지보수성을 크게 향상시킬 수 있다. 특히 대규모 프로젝트에서는 필수적인 요소라고 할 수 있다.

APIRouter를 사용할 때는 다음 사항들을 고려하는 게 좋다:

• 논리적으로 관련된 엔드포인트들을 하나의 라우터로 그룹화하기
• 명확한 prefix와 태그 사용하기
• 공통된 의존성은 라우터 레벨에서 설정하기
• 적절한 에러 핸들링 추가하기