🧱 FastAPI 기본 애플리케이션 만들기

🕒 약 2분 읽는 데 소요됩니다

이전글 보기(FastAPI 개발 환경 설정)

– Hello, FastAPI! 그다음 단계, FastAPI 앱 만들기

“기초부터 탄탄하게!”
이제 환경 설정도 끝났으니, FastAPI의 핵심 기능들을 직접 코드로 작성해보며 하나하나 익혀볼 차례입니다. 이번 글에서는 라우팅, 경로 매개변수, 쿼리 매개변수, POST 요청 처리까지 FastAPI의 기본 기능을 모두 경험해보겠습니다.

---

✅ 프로젝트 구조 만들기

우선 깔끔한 구조를 위해 기본 폴더 구성을 잡아줄게요.

fastapi-tutorial/
│
├── main.py
├── models.py
├── schemas.py
└── requirements.txt

이 구조는 앞으로 규모가 커져도 유지보수가 쉬운 구조입니다.
지금은 간단하게, 모든 코드를 main.py에 작성하면서 기능별로 구분만 이해해볼게요.

---

🚦 1. 라우팅(Routing) 이해하기

FastAPI는 URL 경로와 Python 함수(엔드포인트)를 연결해서 API를 만듭니다. 이를 라우팅이라고 해요.

main.py 파일을 열고 다음 코드를 작성해보세요:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Welcome to FastAPI!"}

@app.get("/hello")
def say_hello():
    return {"message": "Hello, World!"}

실행 방법

터미널에서 아래 명령어 입력:

uvicorn main:app --reload

브라우저로 접속:

• http://127.0.0.1:8000/ → Welcome 메시지
• http://127.0.0.1:8000/hello → Hello 메시지

---

📦 2. 경로 매개변수 (Path Parameters)

특정한 데이터를 URL 경로로부터 받아올 수 있습니다.

예: /users/3 → 사용자 ID가 3인 데이터를 받고 싶을 때

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

• user_id는 함수 인자이자, URL의 변수입니다.
• int 타입 힌트 덕분에 숫자가 아닐 경우 자동 오류 반환됩니다.

접속 예:

http://127.0.0.1:8000/users/42
→ {"user_id": 42}

---

🔍 3. 쿼리 매개변수 (Query Parameters)

쿼리 매개변수는 ?key=value 형식으로 전달되는 추가 정보입니다.

@app.get("/items/")
def read_item(q: str = "default"):
    return {"query": q}

접속 예:

• /items/?q=fastapi → {"query": "fastapi"}
• /items/ → {"query": "default"}

q: str = "default"는 선택적 매개변수이며 기본값을 가집니다.

복수 매개변수도 가능:

@app.get("/search/")
def search(keyword: str, page: int = 1):
    return {"keyword": keyword, "page": page}

예:

/search/?keyword=python&page=2
→ {"keyword": "python", "page": 2}

---

📬 4. POST 요청과 Request Body 처리

데이터를 서버에 보내기 위해 사용하는 POST 요청도 FastAPI에선 매우 간단합니다.

1. 데이터 모델 정의 (Pydantic 사용)

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None

2. POST 요청 핸들러 작성

@app.post("/items/")
def create_item(item: Item):
    return {"received_item": item}

이제 Swagger 문서(→ /docs)에서 직접 POST 요청을 시뮬레이션해볼 수 있습니다.

예시 요청 본문(JSON):

{
  "name": "Laptop",
  "price": 1299.99,
  "description": "High-performance laptop"
}

응답:

{
  "received_item": {
    "name": "Laptop",
    "price": 1299.99,
    "description": "High-performance laptop"
  }
}

---

🧪 5. 필수 테스트 포인트 요약

기능	경로	설명
기본 라우팅	/	Welcome 메시지 반환
단순 GET	/hello	Hello 메시지
경로 변수	/users/1	사용자 ID 반환
쿼리 변수	/items/?q=fastapi	문자열 입력 받아 반환
POST 요청	/items/	JSON 본문 받아 처리

---

🛠 팁: FastAPI 디버깅과 리로드

• --reload 옵션을 항상 사용하세요. 파일 저장 시 서버가 자동으로 반영됩니다.
• 에러 메시지가 직관적으로 출력되므로 디버깅이 매우 쉽습니다.
• Swagger UI에서 직접 API 요청을 보내보고 결과를 확인하세요. GUI 기반이라 초보자에게 매우 친절합니다.

---

🧾 마무리: FastAPI는 진입 장벽이 낮지만 강력하다

이제 여러분은 FastAPI에서 가장 핵심이 되는 기능들인 라우팅, 경로/쿼리 매개변수, POST 요청 처리를 경험해보았습니다. Flask보다 훨씬 정돈된 구조로, 더 빠르고 명확한 API를 만들 수 있다는 것이 실감나죠?

다음 편에서는 응답 모델, 상태 코드 처리, 예외 핸들링 등에 대해 배워보며 한층 더 탄탄한 API를 만들어봅시다!

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/