APIRouter로 큰 앱을 어떻게 구조화합니까?

Question

Accepted Answer

**`APIRouter`**는 큰 FastAPI 앱을 여러 모듈로 분할할 수 있게 합니다. 각 라우터는 관련 엔드포인트(예: 모든 `/users` 라우트)를 그룹화하고, 메인 앱이 이를 포함합니다. 이는 커지는 코드베이스를 정돈되고 유지보수 가능하게 유지합니다.

## 자체 모듈에 라우터 정의하기

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # 여기의 모든 라우트는 /users로 시작
    tags=["users"],           # 문서에서 "users"로 그룹화됨
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

`APIRouter`는 미니 앱처럼 동작합니다. 동일한 데코레이터로 경로 작업을 정의하며, `prefix`가 그 모두에 적용됩니다.

## 메인 앱에 라우터 포함하기

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

app = FastAPI()
app.include_router(users.router)     # /users/* 엔드포인트를 마운트
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()`는 각 라우터의 엔드포인트를 메인 앱에 마운트하여, 모듈식 조각들로부터 전체 API를 조립합니다.

## 일반적인 프로젝트 구조

```text
app/
  main.py              # 앱 생성, 라우터 포함
  routers/
    users.py           # /users용 APIRouter
    items.py           # /items용 APIRouter
    auth.py            # /auth용 APIRouter
  models.py            # Pydantic 모델
  database.py          # DB 설정
  dependencies.py      # 공유 의존성
```

각 기능/도메인이 자체 라우터 모듈을 가지므로, 관련 라우트와 코드베이스가 잘 정돈됩니다.

## 라우터 수준 의존성 및 설정

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # 라우터의 모든 라우트에 의존성 적용
)
# 라우터에서 include_router를 통해 라우터를 중첩할 수도 있습니다
```

라우터는 공유 의존성(예: 전체 라우트 그룹에 admin 인증 요구)을 가질 수 있으며, 모든 엔드포인트에 한 번에 적용됩니다.

## 왜 중요한가

`APIRouter`는 사소하지 않은 FastAPI 앱을 구축하는 데 필수적입니다. 그것 없이는 모든 엔드포인트가 한 파일에 있게 되어, API가 커질수록 관리할 수 없게 됩니다.

이를 이해하는 것은 **코드 구성과 유지보수성**에 중요합니다: 엔드포인트를 기능 기반 라우터 모듈(users, items, auth)로 분할하면 관련 코드가 함께 유지되고, 프로젝트를 탐색하기 쉬워지며, 팀이 서로 다른 영역에서 독립적으로 작업할 수 있습니다.

`prefix`와 `tags`는 라우트와 문서를 정돈하고, **라우터 수준 의존성**(예: 전체 그룹에 admin 인증 요구)은 깔끔한 그룹 전체 동작을 제공합니다.

이 모듈식 구조는 실제 FastAPI 애플리케이션의 표준 관행이므로, `APIRouter`와 그 주변의 프로젝트 구성 패턴은 확장 가능하고 유지보수 가능한 API를 구축하기 위한 중요하고 사실상 필수적인 지식입니다.