FastAPI: Router 설정하기.

Kim yoon beom·2025년 12월 17일

FastAPI: 설치부터 모델서빙까지

목록 보기

3/5

도입: 왜 Router를 쓰는가

FastAPI 프로젝트가 커지면 main.py 하나에 모든 API를 넣기 어렵다.

URL 경로별(예: /user, /post)로 파일을 나눠 관리하면 가독성과 유지보수가 좋아진다.

그래서 이번 글에서는 /user 경로를 예제로 Router구조를 설계하고,
main에 붙여서 실제로 동작시키는 것이 목표.

1. 프로젝트 폴더 구조 소개

구상했던 구조

fastapi-test/
├── venv/
├── src/
│   ├── main.py
│   ├── routers/
│   │    └── user_router.py
│   └── services/
│        └── user_service.py
├── requirements.txt

routers/는 URL 경로를 담당하는 파일들 모음
services/는 비즈니스 로직을 모아둘 예정

2. /user 전용 Router 만들기 (user.py)

/user에 대한 요청만 이 파일에서 관리한다.

# user.py
from fastapi import APIRouter

user_router = router = APIRouter()

@router.get("/")
async def getUser():
  return "유저입니다."

현재 상황

두 길이 이어지지 않고, 끊겨있다.

포인트:

APIRouter()로 라우터 인스턴스를 만들고,

@user_router.get("/")로 /user/에 대한 엔드포인트를 정의
(나중에 /user/{user_id} 같은 것도 이 파일에 추가할 수 있다)

우리가 user.py에서 만든 길은 Fastapi 서버에 적용되지 않고 따로 놀고있다.
우리는 main.py를 실행시켜 Fastapi 서버를 연다.
그래서 길을 만들면, 해당 길을 붙여줘야한다.

길을 붙여주기 위해서는 다음 함수를 사용한다.
app.include_router(router, prefix=prefix)
혹은 router.include_router

그러면 이제 길을 붙여보도록 하자.

먼저 index.py 파일에 다음과 같이 코드를 작성하자.

3. 모든 Router를 모으는 index.py

# index.py
from fastapi import APIRouter
from src.routers.user import user_router

index_router = router = APIRouter()

router.include_router(user_router, prefix="/user")

현재 상황

index_router는 “라우터들의 라우터” 역할.

include_router(user_router, prefix="/user") 덕분에
최종 URL은 prefix + user_router 내부 경로 → /user + / = /user/가 된다

4. main.py에서 최상위로 붙이기

마지막으로 main.py에 index_router를 붙여서 실제 서버에 라우터를 연결

# src/main.py
from fastapi import FastAPI
from src.routers.index import index_router

app = FastAPI(
    docs_url="/docs",
    openapi_url="/open-api-docs",
)

# /api로 시작하는 모든 경로에 index_router를 붙이기
app.include_router(index_router, prefix="/api")

@app.get("/")
async def root():
    return "Hello, World"

이제 URL 전체는
/api(main) + /user(index) + /(user) = /api/user/가 된다.

“Router를 여러 단계로 나눠 붙일 수 있다”

5. 서버 실행 및 테스트

이제 서버를 열어보자

uvicorn src.main:app --host=0.0.0.0 --port=3000 --reload

그리고 이제 브라우저 주소창에 "http://127.0.0.1:3000/api/user/" 를 작성해보자.

혹은 "http://127.0.0.1:3000/docs" 주소로 들어가면 스웨거가 나올텐데

여기서 우측 상단에 “Try it out” -> Execute를 누르면
Swagger에서 자동으로 요청을 보내주어 응답을 받게 된다.

예시

예시 2

얘도 해보면

짜잔

6. 마무리

URL 구조를 기준으로 routers/를 나누면 기능별로 코드가 깔끔해진다.
새로운 도메인(/post, /auth 등)이 생기면
post.py, auth.py를 만들어 같은 패턴으로 추가할 수 있다.
다음 글 예고: Fastapi: Query, Param, Body로
- FastAPI에서 라우터의 데코레이터는
  HTTP 요청 방식(get, post, put, delete 등)과
  경로, 파라미터를 매우 유연하게 정의할 수 있다.
  
  -> 이에 대한 내용.