🧩 APIRouter – 프로젝트를 분해하는 기술

FastAPI로 간단한 API를 만들 때는 하나의 파일로도 충분하다.

하지만 크기가 점점 커지게 되면,
main.py 파일 하나에 사용자 API, 상품 API, 주문 API, 인증 로직, 데이터베이스 연결 코드까지 전부 들어가게 된다.

수백, 수천 줄의 코드가 한 파일에 모이면

• 원하는 코드를 찾기 어렵고
• 수정 범위가 커지고
• 여러 명이 동시에 작업하면 충돌이 잦아진다

이 문제를 해결하는 방법이 바로 APIRouter다.

관련된 API들을 파일 단위로 분리하고, 마지막에 메인 앱에서 조립하는 방식이다.

핵심 용어 이해하기

📡 Router (라우터)

👉여러 컴퓨터 네트워크를 연결하고 데이터 패킷의 최적 경로를 찾아 전송하는 장비

인터넷에서 들어오는 요청을 보고

"이 요청은 누구에게 보내야 하지?" 를 결정하는 장치다.

FastAPI의 APIRouter도 같은 역할을 한다.

HTTP 요청이 들어오면 어떤 함수가 처리할지 안내하는 이정표 역할을 한다.

🧱 Module (모듈)

레고 블록을 떠올리면 된다.

• 각 블록은 독립적
• 여러 개를 조립하면 하나의 완성품

Python에서 모듈은 .py 파일 하나다.

각 파일은 독립적인 코드 단위이고, 여러 모듈을 조합해 하나의 프로그램을 만든다.

📦 Package (패키지)

레고 블록들을 담아두는 상자다.

Python에서 패키지는 모듈들을 담고 있는 폴더다.

단, 일반 폴더와 다른 점이 하나 있다.

예제 코드

Step 1. 프로젝트 폴더와 파일 생성

mkdir -p app/routers
touch app/__init__.py
touch app/main.py
touch app/routers/__init__.py
touch app/routers/users.py

완성된 폴더 구조는 아래와 같다.

app/
├── __init__.py          # app 패키지 선언
├── main.py              # FastAPI 앱 진입점
└── routers/
    ├── __init__.py      # routers 패키지 선언
    └── users.py         # 사용자 관련 API

Step 2. users.py 작성

from fastapi import APIRouter

router = APIRouter()  # 핵심 객체

@router.get("/users/")
async def read_users():
    return [{"username": "jay"}, {"username": "철수"}]

@router.get("/users/{username}")
async def read_user(username: str):
    return {"username": username}

여기서 중요한 포인트

• FastAPI()가 아니라
• APIRouter()를 사용한다

Step 3. main.py 작성

from fastapi import FastAPI
from .routers import users

app = FastAPI()

app.include_router(users.router)

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

include_router() 한 줄로 외부 파일의 API를 앱에 결합한다.

Step 4. 서버 실행 및 확인

fastapi dev app/main.py

브라우저에서 아래 주소로 이동한다.

http://127.0.0.1:8000/docs

Swagger UI에서 다음 엔드포인트들이 보이면 성공이다.

• GET /
• GET /users/
• GET /users/{username}

APIRouter 이해하기

APIRouter는 FastAPI의 축소판

APIRouter는 FastAPI와 사용법이 거의 같다.

차이점은 단 하나다.

prefix로 경로 접두사 붙이기

users.py를 보면 /users가 계속 반복된다.

/users/
/users/{username}

prefix를 사용하면 이 반복을 제거할 수 있다.

from fastapi import APIRouter

router = APIRouter(prefix="/users")

@router.get("/")
async def read_users():
    return [{"username": "jay"}, {"username": "철수"}]

@router.get("/{username}")
async def read_user(username: str):
    return {"username": username}

tags로 API 문서 그룹화하기

Swagger UI에서 API를 보기 좋게 묶을 수 있다.

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

🧩 여러 라우터 결합하기

실제 프로젝트에서는 하나의 라우터로는 절대 부족하다.
도메인(기능) 단위로 라우터를 분리하고, 메인 앱에서 조립하는 구조가 기본이다.

📁 전체 구조 한눈에 보기

app/
 ├── main.py                ← FastAPI 앱 진입점
 ├── dependencies.py        ← 공통 의존성 (인증, 권한 등)
 └── routers/
     ├── __init__.py
     ├── users.py           ← 사용자 도메인
     └── items.py           ← 상품 도메인

👉 핵심 원칙
• 라우터 = 도메인 단위
• main.py = 조립만 담당
• 공통 로직 = dependencies로 분리

🛠 Step 1. items 라우터 생성

touch app/routers/items.py

🧱 Step 2. items.py 작성

from fastapi import APIRouter

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

fake_items_db = {
    "물총": {"name": "물총", "price": 32000.0},
    "수류탄": {"name": "수류탄", "price": 19900.0}
}

@router.get("/")
async def read_items():
    return fake_items_db

@router.get("/{item_id}")
async def read_item(item_id: str):
    if item_id not in fake_items_db:
        return {"error": "Item not found"}
    return fake_items_db[item_id]

🧲 Step 3. 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!"}

요청 흐름 (라우터 결합 구조)

Client
  ↓
FastAPI app
  ├─ users.router  → /users/**
  └─ items.router  → /items/**

📦 import 방식 이해하기

1️⃣ 상대 경로 import

from .routers import users

. 은 현재 패키지(app)를 의미한다.
패키지 내부 참조에 강하지만, 단독 실행에는 약하다.

2️⃣ 절대 경로 import

from app.routers import users

경로가 명확하고 IDE 자동완성이 강력하다.
실무에서는 이 방식을 더 많이 쓴다.

🧠 공통 의존성 분리하기

인증, 권한, 토큰 검증 같은 로직은
라우터마다 반복하면 망한다.

Step 1. dependencies.py

from typing import Annotated
from fastapi import Header, HTTPException

async def verify_token(
    x_token: Annotated[str, Header()]
):
    if x_token != "fake-super-secret-token":
        raise HTTPException(
            status_code=400,
            detail="X-Token header invalid"
        )

Step 2. 라우터 전체에 적용

from fastapi import APIRouter, Depends
from ..dependencies import verify_token

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

요청 처리 흐름

Client
  ↓
verify_token (공통 의존성)
  ↓
items router
  ↓
endpoint 함수

⚠️ import 이름 충돌 방지

from .routers.users import router
from .routers.items import router  # 앞의 router 덮어씀

항상 모듈 단위로 import

from .routers import users, items

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