개발환경 구축과 Django 프로젝트 시작

처음 Django를 설치하고 프로젝트를 시작할 때,
어디서부터 손대야 할지 막막하셨죠?
이 글 하나면 OK! 🔧

안녕하세요,  여러분! 😄

오늘은 여러분이 Django라는 강력한 웹 프레임워크를 사용해 첫 프로젝트를 시작할 수 있도록 개발환경을 세팅하고, Django 프로젝트를 만드는 첫걸음을 함께 해보려 해요.

이 글은 단순히 코드를 나열하는 튜토리얼이 아니라, 왜 그렇게 해야 하는지까지도 친절히 설명할 테니, 걱정은 접어두시고 커피 한잔과 함께 따라와 주세요! ☕

특히 Python 기초만 알고 있어도 충분히 이해할 수 있게 구성되어 있어, Django 입문에 완벽한 가이드가 될 거예요.

1. 가상환경이란? 왜 필요한가요?

처음 Django를 공부하거나 개발 프로젝트를 시작할 때 가장 먼저 듣게 되는 단어가 바로 가상환경(virtual environment)입니다. 근데, 왜 굳이 이런 걸 써야 할까요? 🤔

그냥 파이썬 깔고 바로 쓰면 되는 거 아닌가요?

사실, 간단한 스크립트나 학습용 코드에는 크게 상관이 없을 수 있어요.

하지만 프로젝트마다 사용하는 라이브러리 버전이 다르거나 충돌이 발생하는 상황에서는 이야기가 달라집니다.

예를 들어, 프로젝트 A에서는 Django 3.2를, 프로젝트 B에서는 Django 4.0을 쓴다고 해보죠.

이런 경우, 시스템 전체에 Django를 설치했다면 서로 충돌이 날 수밖에 없어요.

💡 가상환경을 쓰면 좋은 점!

• 프로젝트마다 독립된 환경 제공 → 충돌 방지
• 불필요한 시스템 오염 방지 → 유지보수 용이
• 협업 시, 환경 일관성 유지 → 배포도 쉬움

📌 실제로 어떻게 동작하나요?

가상환경은 단순히 파이썬 인터프리터와 라이브러리 디렉토리를 복사해서 독립된 환경으로 만들어 주는 거예요.

우리가 만든 가상환경 안에서는 시스템에 설치된 다른 라이브러리와 상관없이, 내가 원하는 버전만 설치해서 쓸 수 있죠.

🧪 예시로 알아보는 상황

가상환경에 대해 좀더 알아보실 분들은 아래 포스트를 참고해주세요

https://firstcoding.net/74

이제 감이 오셨죠? 😀

다음 글에서는 가상환경을 직접 만들고 Django를 설치하는 실습을 해볼게요!

명령어 한 줄 한 줄, 왜 그런지까지 설명하며 알려드릴게요.

바로 다음 단계에서 만나죠!

2. 가상환경 만들기와 Django 설치하기

이번에는 실제로 가상환경을 만들고, Django를 설치하는 과정을 하나씩 해보겠습니다.

윈도우 사용자 기준으로 설명하지만, macOS나 리눅스도 거의 동일해요.

다만 경로나 명령어가 조금 다를 수 있으니 참고만 해주세요.

⚙️ Step-by-step: 가상환경 만들기

1. 프로젝트를 위한 디렉토리를 만듭니다. 
2. CLI 환경에서 아래 코드 실행
3. mkdir my_django_project cd my_django_project
4. 가상환경을 생성합니다. venv는 파이썬 기본 제공 가상환경 툴입니다.

   python -m venv venv

5. 가상환경을 활성화합니다.
   • Windows: venv\Scripts\activate
   • macOS/Linux: source venv/bin/activate

🎉 명령어를 실행한 후, 프롬프트 앞에 (venv)가 붙으면 성공적으로 가상환경에 들어온 것입니다!

🌐 Django 설치하기

이제 본격적으로 Django를 설치해볼게요.

pip는 Python의 패키지 관리자로, Django도 pip를 통해 간단히 설치할 수 있어요.

pip install django

설치가 완료되면 다음과 같이 버전을 확인할 수 있습니다.

django-admin --version

💡 Tip: requirements.txt 만들기

앞으로 협업하거나 서버에 배포할 땐 requirements.txt 파일이 꼭 필요해요.

지금 설치된 패키지를 저장해두면 나중에 pip install -r requirements.txt 명령으로 똑같이 설치할 수 있죠!

pip freeze > requirements.txt

📎 설치 요약 정리

이제 준비는 끝났습니다. 🎉

다음 단계에서는 Django 프로젝트를 생성하고 실행하는 법을 배워볼 거예요.

준비되셨죠? 바로 다음 STEP에서 만나봐요!

3. Django 프로젝트 생성과 폴더 구조 이해

이제 드디어 본격적인 Django 프로젝트를 시작할 차례입니다!

가상환경도 만들고 Django도 설치했으니, 첫 프로젝트를 만들어볼까요?

이 단계에서는 django-admin이라는 명령어를 사용해서 새로운 프로젝트를 생성합니다.

🚀 django-admin startproject 명령어 사용하기

django-admin startproject config .

위 명령어에서 config는 프로젝트 이름입니다.

원하는 이름으로 바꿔도 돼요! 뒤에 붙은 .(점)은 “현재 디렉토리에 바로 생성하겠다”는 뜻인데, 폴더 구조가 한 번 더 중첩되는 걸 막아줘요.

💡 점(.)을 안 붙이면 어떻게 되나요?

config/config/처럼 디렉토리가 두 겹이 돼서 조금 헷갈릴 수 있어요.

.을 붙여주면 루트 디렉토리에 필요한 파일만 깔끔하게 생성됩니다!

📂 Django 프로젝트 기본 구조 설명

명령어를 실행하면 다음과 같은 디렉토리 구조가 만들어집니다.

my_django_project/
├── manage.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py

VSCode 실행

아직은 생소한 파일이 많을 수 있지만, 앞으로 차근차근 다룰 거니까 걱정 마세요. 😊

이제 다음 단계에서는 manage.py를 이용해 Django 개발 서버를 실행하고, 환영 페이지를 띄워보는 실습을 진행할게요!

4. 개발 서버 실행하고 환영 페이지 보기

지금까지 프로젝트를 생성했고, 폴더 구조도 확인했죠?

이제 실제로 Django가 어떻게 동작하는지, 개발 서버를 실행해보고 웹 브라우저에서 결과를 확인해볼 시간이에요.

딱 10초만에 Django의 기본 환영 페이지를 만나볼 수 있어요! 🌈

▶️ 개발 서버 실행하기

가상환경이 활성화되어 있고, Django 프로젝트 디렉토리 안에 있다면 아래 명령어만 입력하면 됩니다.

python manage.py runserver

✅ 명령어 실행 후, 아래와 같은 메시지가 보이면 성공적으로 서버가 실행된 거예요!

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
April 17, 2025 - 22:30:02
Django version 4.x, using settings 'config.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

🌐 Django 환영 페이지 보기

웹 브라우저를 열고 주소창에 다음을 입력해보세요:

http://127.0.0.1:8000/

이 주소는 로컬호스트(localhost), 즉 여러분의 컴퓨터를 의미합니다.

성공적으로 실행되었다면, Django의 멋진 초록색 체크 표시가 있는 환영 화면을 보게 될 거예요! 🎉

🤔 에러가 난다면?

• 가상환경이 활성화되지 않았을 수 있어요.
• venv\Scripts\activate 또는 source venv/bin/activate를 다시 확인!
• manage.py 파일이 있는 디렉토리에서 실행했는지 확인!

📌 Django 개발 서버의 특징

어떠셨나요?

처음으로 브라우저에서 Django 프로젝트가 돌아가는 걸 확인하면 꽤 뿌듯하실 거예요!

다음은 프로젝트 내부 파일들 — 특히 settings.py, urls.py — 들의 역할을 자세히 살펴보겠습니다. 🛠️

5. 프로젝트 주요 파일 설명 (settings.py, urls.py 등)

Django 프로젝트를 만들고 서버도 돌려봤는데, 폴더 안에 있는 파일들... 솔직히 처음 보면 좀 겁나죠? 😅

settings.py, urls.py, wsgi.py, asgi.py 등등… 이름은 많은데 도대체 다 무슨 역할을 하는 걸까요?

이번에는 이 중요한 파일들을 하나하나 살펴보면서, Django가 어떤 구조로 움직이는지 확실히 이해해보는 시간을 가질게요. 🧠

⚙️ settings.py – 프로젝트 설정의 본부

Django에서 가장 중요한 파일 중 하나예요.

이름 그대로 프로젝트 전반의 설정을 담당합니다.

데이터베이스 연결부터 앱 등록, 보안 설정까지 모두 여기에 있어요.

• INSTALLED_APPS – 사용할 앱 목록 (예: admin, auth 등)
• MIDDLEWARE – 요청/응답을 가로채는 중간 처리기 리스트
• DATABASES – 어떤 DB를 쓸지 (기본은 SQLite)
• STATIC_URL – 정적 파일(CSS, JS 등)의 기본 경로

🌐 urls.py – URL과 View를 연결해주는 라우터

클라이언트가 어떤 URL로 접근했을 때 어떤 페이지나 기능을 보여줄지를 설정하는 파일입니다.

즉, URL ↔ View 함수의 연결고리 역할을 하죠.

from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
]

위 코드는 /admin/ 경로로 접속하면 Django의 관리자 페이지로 이동하도록 설정한 예입니다.
앞으로 여기에 직접 만든 뷰 함수들을 추가해가며 프로젝트를 확장할 거예요!

🌐 wsgi.py & asgi.py – 서버와 Django의 연결고리

이 두 파일은 웹 서버(Gunicorn, Daphne 등)가 Django 앱과 통신할 수 있도록 해주는 인터페이스 스크립트입니다. 단, 개발 단계에서는 거의 사용할 일이 없어요. 프로젝트를 실제 배포할 때 사용된다고 기억만 해두시면 충분합니다!

이처럼 Django 프로젝트의 각 파일은 서로 역할을 나누어 구조적으로 움직입니다.

각각을 이해하고 있으면 앞으로 앱 개발 시 어떤 파일을 수정해야 하는지, 어디를 먼저 살펴봐야 하는지 훨씬 수월해질 거예요.

6. 자주 묻는 질문 및 초보자 팁 ✨

처음 Django를 접할 때 헷갈리는 부분이 정말 많죠?

특히 에러 메시지가 뜨면 ‘뭐가 뭔지 모르겠어!’ 하고 당황하기 쉬워요.

그래서 이 섹션에서는 실제 수강생이나 독자들이 자주 물어봤던 질문과, 제가 직접 겪으며 깨달았던 꿀팁들을 정리해드릴게요.

“아 이거 나만 몰랐던 거 아니었구나!” 싶은 순간이 올지도 몰라요. 😅

❓ 자주 묻는 질문 (FAQ)

1. Q. 가상환경은 프로젝트마다 꼭 만들어야 하나요?
   네, 무조건 만드는 걸 추천드려요!
   그래야 라이브러리 버전 충돌을 막을 수 있고, 협업 시에도 동일한 환경을 유지할 수 있어요.
2. Q. pip install이 안 될 때는 어떻게 해야 하나요?
   인터넷 연결 상태를 먼저 확인해보세요.
   그리고 python -m pip install --upgrade pip로 pip 버전을 최신으로 유지하는 것도 중요해요.
3. Q. runserver 했는데 접속이 안 돼요!
   가상환경이 활성화되어 있는지, manage.py가 있는 디렉토리에서 명령어를 실행했는지 다시 확인해보세요.
4. Q. Django 버전은 어떤 게 좋아요?
   최신 버전을 사용하는 것이 보안과 성능 면에서 좋아요.
   다만, 공식 문서에서 권장하는 LTS 버전을 사용하는 것도 안정적인 선택이에요.

💡 실수 방지용 초보자 꿀팁!

• 매번 서버를 끄고 켤 필요 없어요!
  Django는 코드 변경 사항을 자동으로 감지해서 반영해줘요.
  서버만 켜두면 실시간으로 확인할 수 있어요.
• settings.py는 손댈 땐 복사본부터!
  혹시 오류 나면 되돌릴 수 있도록 settings.py 파일을 백업해두세요.
• 에러 메시지를 잘 읽자!
  Django는 에러 메시지를 정말 친절하게 써줘요.
  천천히 읽으면 해결 실마리가 보입니다.
• pyenv나 poetry 등 도구도 나중에 배워보자!
  파이썬 프로젝트를 더 잘 관리할 수 있는 도구들이에요.
  초보 땐 몰라도 되지만, 나중엔 꼭 도움이 될 거예요.

처음부터 완벽할 필요는 없어요. 저도 Django 처음 시작할 땐 runserver 한 줄 치는 것도 긴장했거든요. 😅

중요한 건 에러를 두려워하지 않고 천천히 쌓아가는 태도입니다.

이제 여러분도 Django의 첫 문을 열었으니, 계속해서 앱을 만들고 실습하면서 자신감을 키워보세요!

Django 입문의 첫 발걸음을 축하합니다! 🎉

여기까지 오신 여러분, 정말 수고 많으셨어요. 👏

처음에는 생소했던 가상환경 생성부터 Django 설치, 프로젝트 구조 이해, 그리고 서버 실행까지 모두 직접 해보셨습니다.

처음 접하면 낯설고 어색했던 단계들이 이제는 조금은 익숙해졌을 거예요.

Django는 강력하고 유연한 웹 프레임워크입니다.

아직은 단순한 “Hello Django” 단계지만, 앞으로 여러분은 이걸 기반으로 블로그, 게시판, 로그인 시스템, API 서버까지 만들 수 있어요.

이제 정말 웹 개발자가 되는 길이 시작된 것이죠.

다음 단계로는 앱 생성 및 라우팅, 데이터베이스 모델 만들기, CRUD 구현, 템플릿 시스템 등으로 나아가면 됩니다.

이 블로그 시리즈에서도 그 모든 과정들을 차근차근 함께 걸어갈 예정이니, 즐겁게 따라와 주세요!

🌱 작은 성공이 쌓이면, 어느새 성장합니다

오늘처럼 하나씩 직접 따라해보고 작은 성취감을 느껴보세요.

그게 쌓이면 진짜 실력이 됩니다.

개발은 재능보다 꾸준함이 더 중요한 분야랍니다. 저도 그랬고요. 😉

여러분의 Django 첫 걸음을 응원합니다! 🚀

다음 글에서는 앱 생성과 URL 연결로 한 걸음 더 나아가볼게요.

웹 개발 기초와 Django 프레임워크 개요

여러분, Python만 알면 웹 사이트도 뚝딱 만들 수 있다면 믿으시겠어요?
Django는 그걸 가능하게 해주는 도구예요!

안녕하세요, 여러분~! 😊
혹시 "웹 개발"이라는 말만 들어도 벌써 머리가 복잡해지는 분 계신가요? 저도 처음엔 그랬어요.

HTML, CSS, JavaScript, 서버, 데이터베이스... 어디서부터 시작해야 할지 막막했거든요.

그래서 이 시리즈에서는 여러분이 편안하게 웹 개발의 기초를 익힐 수 있도록, 정말 친절하고 쉽게!

Django라는 프레임워크를 중심으로 하나하나 알려드릴 거예요.

오늘은 그 첫 걸음으로, 웹 개발이 무엇인지, HTTP란 무엇이며, Django는 어떤 역할을 하는지, 그리고 개발을 시작하기 위한 로컬 환경은 어떻게 준비하는지 이야기해볼게요.

마치 요리를 시작하기 전 재료부터 차근히 준비하듯, 개발도 준비가 반이니까요!

1. HTTP란 무엇인가요? 🌐

웹 개발을 제대로 이해하려면 가장 먼저 HTTP라는 용어부터 알아야 해요.

HyperText Transfer Protocol의 약자인 HTTP는 인터넷에서 정보를 주고받을 때 사용하는 기본 규칙이에요.

쉽게 말해, 웹 브라우저와 서버가 대화할 때 사용하는 언어죠.

우리가 웹 브라우저에 주소를 입력하면 HTTP 요청(Request)이 발생하고, 서버는 거기에 맞는 HTTP 응답(Response)을 보냅니다.

예를 들어,

여러분이 https://www.google.com에 접속하면 브라우저는 "이 주소에 해당하는 내용을 주세요!"라고 요청하고, 서버는 "여기 있어요!" 하면서 응답을 보내는 거예요.

📋 주요 HTTP 메서드 정리

• 클라이언트 = 웹 브라우저, 서버 = 정보를 제공하는 곳
• HTTP는 이 둘의 소통을 위한 ‘공용 언어’예요
• 다양한 메서드를 통해 어떤 ‘행동’을 할지 서버에 알려줘요

정리하자면, HTTP는 웹 개발의 기본 중의 기본입니다.

이 개념을 확실히 이해하고 있어야 웹 프레임워크가 하는 일을 자연스럽게 받아들일 수 있어요.

다음 섹션에서는 웹 프레임워크가 도대체 무슨 일을 해주는지도 살펴볼게요.

2. 웹 프레임워크의 개념과 역할 🧱

웹 개발을 처음 접하는 분들은 "웹 프레임워크"라는 말이 좀 낯설게 느껴질 수 있어요.

웹 프레임워크란 쉽게 말해서, 웹사이트를 만들기 위한 재료와 조리도구가 모두 포함된 요리 세트라고 생각하면 됩니다.

우리가 만약 웹 프레임워크 없이 개발한다면, 요청 처리, URL 연결, 폼 검증, 데이터 저장, 보안, 세션 등 모든 걸 직접 다 만들어야 해요.

마치 라면도 면부터 직접 뽑고, 스프도 만들고, 그릇도 빚는 느낌... 😵‍💫 하지만 프레임워크를 사용하면 이런 반복적인 작업들을 자동화하고 간편화해줍니다.

💡 웹 프레임워크가 하는 일

• 사용자가 입력한 URL을 어떤 기능과 연결할지 결정해요 (라우팅)
• 사용자의 입력값을 안전하게 처리해줘요 (폼 검증, 보안 필터)
• 데이터베이스와 연결해서 정보를 읽고 쓰게 해줘요
• 사용자가 보는 웹 페이지도 만들어 줘요 (템플릿 렌더링)

✔ 왜 웹 프레임워크를 써야 할까?

1. 복잡한 웹 기능을 빠르고 쉽게 구현할 수 있어서
2. 보안, 성능, 유지보수 등 전문가들이 설계한 기능을 그대로 활용할 수 있어서
3. 문서화와 커뮤니티가 잘 되어 있어서 문제 해결이 쉬워요

이제 왜 웹 프레임워크가 중요한지 감이 오시죠?

Django는 그런 프레임워크 중에서도 아주 강력하고, 쉬우며, 실무에서도 많이 쓰이는 대표적인 녀석이에요. 다음 장에서는 Django가 왜 그렇게 많은 사랑을 받는지 그 매력을 살펴보죠!

3. Django의 특징과 장점 ✨

Django(장고)는 Python 기반의 웹 프레임워크예요.

"The web framework for perfectionists with deadlines"라는 슬로건처럼, 빠르고 깔끔한 개발을 원하는 사람들에게 안성맞춤이에요. 🧑‍💻

처음 접하면 다소 방대해 보일 수 있지만, 알고 보면 개발자의 귀차니즘을 가장 잘 이해하는 프레임워크랍니다!

💎 Django의 대표적인 장점

📌 이런 분들에게 강력 추천!

• 프론트엔드보다 백엔드가 더 궁금한 분
• 서비스 MVP를 빠르게 만들어보고 싶은 스타트업 창업자
• Python을 배워봤고 이제 웹을 해보고 싶은 분!

Django는 국내외 수많은 웹사이트에서 실전(!)으로 쓰이고 있어요.

여러분도 곧 Django로 진짜 작동하는 웹 서비스를 만들 수 있을 거예요.

이제 Django가 어떻게 구조화되어 있는지, 그 핵심인 MVT 패턴으로 넘어가 볼까요?

4. Django의 MVT 아키텍처 이해 🧩

웹 프레임워크마다 나름의 아키텍처 구조를 갖고 있어요.

Django에서는 MVT(Model-View-Template) 패턴을 사용합니다.

이건 흔히 들어본 MVC(Model-View-Controller)와 비슷하면서도 Django만의 방식이 녹아 있어요.

📚 MVT 구성요소 한눈에 보기

📌 Django에서의 흐름 정리

1. 사용자가 웹사이트에 어떤 요청을 보냅니다 (예: 게시글 목록 보기).
2. View가 그 요청을 받고, 필요한 데이터를 Model에서 가져옵니다.
3. 가져온 데이터를 Template에 넘겨서 예쁘게 보여줍니다.

이렇게 역할을 명확히 나눔으로써 개발자는 로직만, 디자이너는 UI만 집중할 수 있어요.

협업도 편하고, 유지보수도 쉬워지는 Django의 큰 장점 중 하나랍니다!

이제 Django의 구조까지 살펴봤으니, 실전 준비를 해볼 차례죠.

다음 파트에서는 여러분의 PC에서 Django 개발을 시작할 수 있도록 Windows 개발 환경을 셋업하는 방법을 알아봅니다!

5. Windows에서 개발환경 준비하기 🛠️

본격적으로 Django를 사용해서 웹 개발을 하려면, 먼저 내 PC에 개발환경부터 갖춰야 해요.

이번 파트에서는 Windows 기반의 로컬 개발환경을 단계별로 구성하는 법을 알려드릴게요.

🔧 Step-by-Step 개발환경 설정 가이드

1. Python 설치
2. 가상환경(venv) 설정
3. 필수 패키지 설치 (pip 이용)
4. Django 설치 및 프로젝트 시작

1. Python 설치하기 🐍

공식 사이트에 들어가서 Python 최신 버전을 다운로드하고 설치합니다.

설치 시 "Add Python to PATH" 옵션을 꼭 체크해야 해요!

파이썬 설치 관련 내용 확인
https://firstcoding.net/54

2. 가상환경 만들기 💡

가상환경은 프로젝트마다 독립적인 패키지 공간을 만들어줘요. 아래 명령어를 실행해볼게요.

python -m venv venv
venv\Scripts\activate

성공하면 명령 프롬프트에 (venv)가 붙어요.

가상환경에 대해 좀더 알아보실 분들은 아래 포스트를 참고해주세요

https://firstcoding.net/74

이제 여기서 Django를 설치하면 됩니다!

3. Django 설치 및 프로젝트 시작 🚀

pip install django
django-admin startproject mysite
cd mysite
python manage.py runserver

위 명령어까지 완료했다면 127.0.0.1:8000 주소로 접속해보세요!

Django 환영 페이지가 나온다면 성공이에요! 🎉

여러분은 지금 Django 웹 개발의 첫 발을 디디셨어요.

앞으로 이 환경에서 앱을 만들고, 데이터베이스를 연결하고, 멋진 서비스를 구현하게 될 거예요!

6. Python 설치와 가상환경 설정 ⚙️

앞선 STEP에서 간단하게 개발환경을 구성해봤다면, 이번에는 조금 더 자세히 Python 설치와 가상환경 설정에 대해 알아보겠습니다. 특히 여러 프로젝트를 동시에 개발하려면 가상환경을 잘 활용하는 습관이 정말 중요해요.

📌 Python 설치 팁

• 설치 중 반드시 “Add Python to PATH” 체크!
• 버전 충돌 방지를 위해 최신 버전 사용 권장

설치 후 명령 프롬프트에서 다음 명령어로 확인해볼 수 있어요.

python --version
pip --version

🌱 가상환경(venv) 개념 다시 보기

가상환경은 말 그대로 프로젝트마다 독립적인 Python 공간이에요.

예를 들어,

블로그 웹사이트에선 Django 4.2 버전을 쓰고, 쇼핑몰 웹사이트에선 3.2 버전을 쓸 수도 있어요.

이런 걸 가능하게 해주는 게 바로 가상환경입니다.

✔ 가상환경 관리 명령어

📎 실전 꿀팁

• Visual Studio Code를 쓰면 터미널에서 바로 가상환경을 인식해줘요!
• requirements.txt 파일을 만들어 두면 나중에 패키지 설치가 훨씬 쉬워요.

지금까지 Python 설치와 가상환경 설정에 대해 배워봤어요.

이제 여러분은 Django 개발을 위한 기초 체력을 모두 갖췄다고 볼 수 있죠.

그럼 이제, 이 여정을 마무리하면서 여러분이 앞으로 어떻게 시작하면 좋을지 정리해볼게요!

🧩 이제 Django 세계로 출발해볼까요?

여기까지 따라오셨다면 정말 수고 많으셨어요!

HTTP의 기본 구조부터 Django의 매력, MVT 패턴, 그리고 개발환경 설정까지 웹 개발을 시작하는 데 꼭 필요한 기초를 차근차근 다졌습니다. 👏

이제 여러분은 개발자 노트북을 열고, Django로 나만의 웹 서비스를 만들 준비가 된 셈이죠.

"아직 잘 모르겠어요..."라는 생각이 드시더라도 괜찮아요.

개발은 해보면서 익히는 것이니까요.

다음 글부터는 Django 프로젝트를 하나씩 만들어보면서 실습 중심으로 배워볼 거예요.

"왜 이렇게 동작하지?"라는 의문이 들면 이 글로 다시 돌아와 주세요.

기초는 늘 탄탄하게, 다시 반복할수록 더 잘 보이거든요 😉

그럼 우리 다음 글에서는 Django 프로젝트를 직접 만드는 방법으로 이어가 볼게요.

같이 실습하면서 진짜 서비스를 만들 준비되셨죠? 🎯

파이썬 FastAPI 실전 프로젝트 구현 (2) – 기능 보완 및 마무리

여러분, 프로젝트 마무리할 때 뭔가 찝찝하게 끝낸 적 있으시죠?
이번에는 FastAPI로 만든 API를 제대로 다듬고,
진짜 ‘완성된’ 느낌을 만들어봐요!

안녕하세요, 개발자 여러분 😊

드디어 FastAPI 실전 프로젝트의 마지막 단계에 도달했습니다.

앞서 API를 설계하고 기본적인 CRUD 기능을 구현했지만, 사실 프로젝트가 ‘완성됐다’고 말하기 위해서는 몇 가지 마무리 작업이 꼭 필요하죠.

예를 들어 빠진 기능을 채우거나, 리팩토링을 통해 코드 품질을 끌어올리고, 전체 테스트를 통해 문제가 없는지 꼼꼼히 검증하는 과정 말이에요.

이번 글에서는 Update/Delete API 구현, 리팩토링, 테스트 마무리, 추가 기능 구현까지 포함해서, 진짜 실전에 가까운 프로젝트 완성 과정을 함께 해볼 거예요.

이제 진짜 개발자 포트폴리오에 올릴 수 있는 API를 만들어볼 준비되셨나요? 😎 그럼 시작해볼게요!

1. CRUD 기능 보완: Update/Delete 엔드포인트 구현 🛠️

1.1 글(Post) 및 할일(Todo) 수정 API 구현

이제 남은 CRUD 기능 중 '수정(Update)' 엔드포인트부터 완성해볼 차례입니다.

블로그 API와 Todo API 모두에 해당하는 기능으로, RESTful한 방식에 따라 PUT 메서드를 사용합니다.

FastAPI에서는 @router.put("/posts/{id}") 형식으로 경로를 선언하고, 입력 데이터는 schemas.PostUpdate 같은 Pydantic 모델을 사용해 받습니다.

- 수정 대상이 존재하지 않으면 404 Not Found
- 성공 시에는 수정된 객체를 JSON으로 반환
- 인증 기능이 있다면 작성자만 수정 가능하게 조건을 걸 수 있음 (지금은 생략)

예시 코드

@router.put("/posts/{id}")
def update_post(id: int, post_update: PostUpdate, db: Session = Depends(get_db)):
    post = db.query(Post).filter(Post.id == id).first()
    if not post:
        raise HTTPException(status_code=404, detail="Post not found")
    post.title = post_update.title
    post.content = post_update.content
    db.commit()
    db.refresh(post)
    return post

1.2 삭제(Delete) API 구현

삭제 기능은 프로젝트의 정돈을 위해 반드시 필요한 부분이에요.

블로그의 경우 글 삭제, Todo의 경우 할일 삭제가 이에 해당합니다.

완전 삭제 방식으로 구현하되, 보안이나 감사 로그가 필요한 경우에는 Soft Delete 방식도 고민해볼 수 있어요.

예시 코드

@router.delete("/todos/{id}", status_code=204)
def delete_todo(id: int, db: Session = Depends(get_db)):
    todo = db.query(Todo).filter(Todo.id == id).first()
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    db.delete(todo)
    db.commit()
    return Response(status_code=204)

1.3 마무리 요약

• PUT 메서드로 수정 API를 추가한다.
• DELETE 메서드로 삭제 API를 완성한다.
• 없는 리소스에 접근 시 404 예외 처리를 꼼꼼히 해준다.

이제 CRUD의 4가지 기본 기능이 완성됐습니다.

이 다음은 조금 더 재미있는(?) 추가 기능 구현 시간입니다!

2. 주제별 추가 기능과 쿼리 개선 🎯

2.1 블로그 API – 사용자별 글 목록 및 검색 기능

블로그 API에선 기본적인 CRUD 외에도, 사용자별 글 목록이나 검색 기능처럼 실전에서 많이 쓰는 기능을 추가해보면 실력이 쑥쑥 자랍니다.

• GET /users/{user_id}/posts – 특정 유저가 작성한 글만 필터링
• GET /posts?search=키워드 – 제목/내용에 포함된 키워드로 검색

쿼리 필터 예시

@router.get("/posts")
def list_posts(search: str = None, db: Session = Depends(get_db)):
    query = db.query(Post)
    if search:
        query = query.filter(Post.title.contains(search))
    return query.all()

2.2 Todo API – 완료 여부 필터링 및 정렬

Todo API에선 할 일의 완료 상태나 우선순위 정렬 기능을 추가하면 사용성이 훨씬 높아져요.

• GET /todos?completed=true – 완료된 항목만 필터링
• GET /todos?sort=priority – 우선순위 오름차순 정렬

정렬 필터 예시

@router.get("/todos")
def get_todos(completed: bool = None, sort: str = None, db: Session = Depends(get_db)):
    query = db.query(Todo)
    if completed is not None:
        query = query.filter(Todo.done == completed)
    if sort == "priority":
        query = query.order_by(Todo.priority.asc())
    return query.all()

2.3 마무리 팁 💡

이런 기능은 구현해보면 어렵지 않지만, 실제 API 사용 경험을 엄청나게 향상시켜줍니다.

쿼리 파라미터와 동적 필터링은 FastAPI와 SQLAlchemy를 익히는 데 정말 좋은 연습이 돼요!

꼭 필요한 핵심 기능 외에도 사용자가 편리하게 쓸 수 있는 부가 기능 몇 개만 추가해도, 프로젝트의 깊이가 확 달라진다는 거 잊지 마세요 😉

3. 코드 리팩토링과 공통 모듈 정리 📦

3.1 중복 로직 정리: get_object_or_404

FastAPI로 프로젝트를 하다 보면, 가장 자주 반복되는 패턴 중 하나가 바로 이거예요.

query.first()로 객체를 가져오고 없으면 HTTPException(404)을 던지는 코드!

매번 반복하지 말고, 다음과 같이 공통 헬퍼 함수로 만들어두면 가독성과 유지보수성이 확 올라갑니다.

def get_object_or_404(query, model_name: str = "Object"):
    obj = query.first()
    if not obj:
        raise HTTPException(status_code=404, detail=f"{model_name} not found")
    return obj

이제 이렇게 쓰면 됩니다:

post = get_object_or_404(db.query(Post).filter(Post.id == id), "Post")

3.2 인증/권한 검사 공통화

만약 로그인 인증 기능이 있다면, API마다 인증 정보를 검사하는 코드도 반복됩니다.

FastAPI는 Depends()를 이용해 공통 처리할 수 있어요.

def get_current_user(token: str = Depends(oauth2_scheme)):
    payload = decode_token(token)
    user = db.query(User).filter(User.id == payload["sub"]).first()
    if not user:
        raise HTTPException(status_code=401, detail="Invalid credentials")
    return user

라우터에서는 이렇게 간단히 호출하면 되죠:

@router.get("/me/posts")
def my_posts(current_user: User = Depends(get_current_user)):
    return current_user.posts

3.3 Swagger 문서화 향상

Swagger UI를 더 보기 좋게 꾸미고 싶다면, Pydantic 모델에 description 필드를 넣는 게 좋아요.

이게 곧 API 문서가 되거든요.

class PostCreate(BaseModel):
    title: str = Field(..., description="게시글 제목")
    content: str = Field(..., description="게시글 본문")

이렇게 하면 Swagger에서 각 필드 설명이 뜨고, 사용자나 동료 개발자에게도 친절한 API가 됩니다. 🧾

3.4 디버그 흔적 제거

그리고 가장 중요한 마무리 습관!

print 같은 디버깅 코드는 모두 제거해주세요.

콘솔에 찍히는 메시지는 실서비스에서 보안 위험이 될 수도 있고, 로그 관리도 어려워지니까요.

• print() 제거
• 테스트용 더미 코드 제거

깔끔한 코드는 실력의 증거입니다.

동료도, 미래의 나도 기뻐할 거예요. 😉

4. Swagger 기반 수동 테스트 🧪

4.1 Swagger UI에서 테스트 시나리오 따라가기

FastAPI의 강력한 무기 중 하나는 바로 자동 생성 API 문서, Swagger UI죠!

개발한 모든 엔드포인트를 웹 UI로 손쉽게 테스트할 수 있다는 점에서, 이건 정말 필수 기능이에요.

테스트를 시작할 땐, 가능한 실제 사용자 시나리오 기반으로 순서대로 실행해보는 게 좋아요.

예를 들어:

1. 1️⃣ 사용자 생성 (POST /users)
2. 2️⃣ 로그인 (만약 구현했다면)
3. 3️⃣ 글 or 할일 생성
4. 4️⃣ 목록 조회
5. 5️⃣ 글/할일 수정
6. 6️⃣ 삭제 요청
7. 7️⃣ 삭제 후 목록 재조회

4.2 예외 상황도 꼭 테스트해보자!

정상 흐름만 테스트하면 부족해요.

진짜 완성도 높은 API는 경계 상황까지 잘 처리하는 경우죠.

꼭 체크해야 할 케이스 리스트 ✔️

• 존재하지 않는 ID로 요청했을 때 → 404 Not Found 잘 반환되는가?
• 필수 값이 빠진 입력 → 422 Unprocessable Entity 나오는가?
• 중복된 값 입력 → 에러 메시지가 친절한가?

이런 테스트는 Swagger UI에서 직접 해볼 수도 있지만, Postman이나 curl 같은 도구로 해보는 것도 좋은 연습이에요.

다양한 환경에서 동일한 API가 잘 작동하는지 확인할 수 있거든요.

4.3 마무리하며

직접 테스트해보면서 API 동작을 확인하는 건, 말 그대로 ‘현장감 있는 검증’입니다.

직접 손으로 다뤄보는 만큼, 놓쳤던 버그도 쉽게 발견되죠.

이제 우리 프로젝트도 한 단계 성숙해졌네요.

다음은 자동화 테스트로 더 철저하게 완성도를 높이는 시간입니다! 😎

5. pytest를 활용한 자동화 테스트 🔍

5.1 pytest 기본 구조와 테스트 함수 작성

FastAPI 프로젝트에선 pytest를 사용해 자동화 테스트를 작성하는 게 표준입니다.

기능 하나하나를 수동으로 확인할 수는 없으니, 테스트 코드를 작성해두면 나중에 기능을 수정하거나 리팩토링해도 안정성을 체크할 수 있어요.

예시 테스트 코드

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_todo():
    response = client.post("/todos", json={
        "title": "테스트 할일",
        "description": "자동화 테스트용"
    })
    assert response.status_code == 200
    assert response.json()["title"] == "테스트 할일"

단순해 보이지만, POST 요청 → 응답 확인 → 예상 결과 비교까지 핵심 흐름이 모두 담겨 있어요.

5.2 테스트 커버리지 넓히기

단일 테스트로는 부족하죠.

아래 항목들을 테스트 목록에 꼭 포함시켜보세요:

• 목록 조회 (GET) 응답이 올바른지
• 수정/삭제 요청 시 상태코드 확인
• 없는 ID로 요청 시 404 테스트

5.3 테스트 실행 및 자동화 팁

터미널에서 다음 명령어를 입력하면 테스트가 실행됩니다.

pytest tests/

Tip: GitHub Actions 또는 GitLab CI와 연동하면 커밋할 때마다 자동으로 테스트가 돌아가요.

       이것만 잘해도 실무에선 ‘코드 퀄리티 보장’으로 인정받습니다.

5.4 테스트 작성 못했다면?

사실 시간이 부족하거나 학습이 익숙하지 않다면, 모든 자동화 테스트를 작성하는 건 쉽지 않아요.

그럴 땐 수동 테스트와 로그 확인으로 충분히 대체 가능합니다.

하지만 이번 프로젝트가 끝나고 나면 꼭 pytest + FastAPI 조합으로 테스트를 구성해보세요.

다음 프로젝트에서는 코드 품질의 자신감이 달라질 거예요!

6. 프로젝트 마무리 및 다음 단계 제안 🚀

6.1 FastAPI 프로젝트 완성 축하합니다! 🎉

정말 고생 많으셨어요!

지금까지 FastAPI + SQLAlchemy를 활용해서 REST API를 설계하고, 구현하고, 테스트하고, 마무리까지 해냈습니다.

처음엔 생소하고 어렵게 느껴졌던 코드들도 이제는 익숙하게 다뤘을 거예요. 👏👏👏

6.2 포트폴리오로 남기는 법 💼

• GitHub에 코드 업로드: 기능별 커밋 기록은 매우 큰 가산점!
• README.md 작성: 사용 방법, 기능 목록, 설치 방법 포함하면 👍
• 시연 영상 or 이미지 첨부: 블로그나 유튜브 링크도 함께!

6.3 다음에 도전해볼 것들 ✨

이제 진짜 FastAPI를 익힌 셈이니까요, 다음 단계로 이런 걸 시도해보면 좋습니다:

• JWT 인증과 OAuth2 로그인 적용 (보안 강화)
• Docker로 서비스 배포 준비
• 프론트엔드 연동 (React, Vue 등으로 UI 구현)

6.4 참고 자료 📚

학습을 계속 이어가고 싶다면, 아래 자료들을 추천합니다:

• FastAPI 공식 문서
• SQLAlchemy 문서
• Pydantic 문서
• Full Stack FastAPI 실전 예제

FastAPI는 앞으로도 계속 성장할 프레임워크입니다.

꾸준히 공식 문서를 체크하고, 오픈소스 프로젝트에 기여해보는 것도 추천드려요!

마무리 🎁

지금까지 우리는 FastAPI를 활용한 실전 프로젝트를 단계별로 구축해왔고, 그 마지막 단계인 기능 보완과 테스트, 리팩토링까지 성공적으로 마무리했습니다.

이 과정을 통해 FastAPI의 기본 구조뿐 아니라 RESTful API 설계, ORM 연동, 예외 처리, 테스트 자동화에 이르기까지 백엔드 개발에서 꼭 필요한 스킬들을 하나씩 익혔어요.

특히 이번 프로젝트는 단순히 작동만 되는 코드가 아닌, 실제 서비스에 가까운 형태로 구현했다는 점에서 큰 의미가 있습니다.

지금까지 작성한 코드들은 포트폴리오로 활용할 수 있을 만큼 구조적이고 완성도가 높아졌습니다.

여기까지 따라오셨다면 정말 큰 박수를 드리고 싶어요. 👏👏👏

앞으로는 이 기반 위에 인증, 배포, 프론트엔드 연동 등 더 넓은 분야로 확장해보세요.

그리고 중요한 건 꾸준히 연습하고, 실제 프로젝트에 응용해보는 겁니다.

이제 여러분도 자신 있게 말할 수 있어요.

"FastAPI로 백엔드 개발할 줄 압니다!" 💪

🎯 이 글의 핵심 요약

• ✅ CRUD 완성: Update/Delete 엔드포인트 구현
• ✅ 사용자 중심 필터링, 검색 등 추가 기능
• ✅ 공통 함수 및 인증 구조 리팩토링
• ✅ Swagger를 통한 수동 테스트
• ✅ pytest 기반 자동화 테스트 도입
• ✅ 실무형 프로젝트 구조와 문서화

여기서 끝나지 않아요.

지금까지 쌓은 지식을 바탕으로 더 멋진 API, 더 나은 백엔드 시스템을 계속 만들어가시길 바랍니다.

여러분의 여정을 응원합니다! 🚀

파이썬 FastAPI 실전 프로젝트 (1) – 블로그 API/Todo API 설계 및 구현 

단순한 예제만으로는 실력이 늘지 않아요.
진짜로 내가 만든 FastAPI 서비스,
지금부터 직접 설계하고 구현해보는 시간입니다!

안녕하세요 여러분 😊

드디어 지금까지 배운 FastAPI 내용을 바탕으로 직접 프로젝트를 시작할 차례입니다!

이제는 단순한 이론이나 짧은 실습이 아니라, 사용자 관리부터 게시글 또는 할일 등록까지 기능이 갖춰진 나만의 API 서비스를 만들게 될 거예요.

이번 실전 프로젝트는 두 가지 주제 중 하나를 선택해서 진행할 수 있어요:

1) 블로그 API 또는 2) Todo 관리 API.

둘 다 FastAPI + SQLAlchemy를 활용해 RESTful 백엔드 API를 직접 설계하고 구현하는 경험을 하게 됩니다.

각 기능별 CRUD 구현뿐 아니라, 모델 설계, 프로젝트 구조 구성, 예외 처리, 테스트까지 고려한 구조로 만들어볼 거예요.

지금부터 7일차 여정을 함께 출발해볼까요? 🚀

1. 최종 프로젝트 개요 및 설계 🧭

여러분, 여기까지 따라오시느라 정말 고생 많으셨어요. 😊

지금까지 FastAPI의 기본적인 사용법, SQLAlchemy 연동, 라우팅, Pydantic 모델링, 예외 처리 등을 하나씩 차근차근 배워오셨죠?

이제는 그 모든 퍼즐을 모아서 직접 하나의 프로젝트로 완성해볼 차례입니다.

1.1 프로젝트 주제와 목표 🎯

이번 프로젝트에서는 두 가지 주제 중 하나를 선택할 수 있어요:

• 블로그 API: 사용자 인증, 글 작성, 글 목록 조회, 상세 보기, 댓글 작성/삭제, 태그 기능 포함
• Todo API: 사용자 생성, 할일 CRUD, 우선순위 설정, 완료 상태 필터링 기능 제공

물론 두 프로젝트 모두 공통적으로 사용자 모델, 데이터베이스 연동, CRUD 기능이 핵심이 되며, 선택한 주제에 따라 약간의 기능 차이가 있을 뿐입니다.

1.2 이번 실습의 핵심 목표 🧩

1. FastAPI의 주요 기능을 실제 API에 적용
2. SQLAlchemy를 통한 모델 정의와 DB 연동 실습
3. Pydantic을 활용한 데이터 검증
4. 기본적인 예외 처리와 테스트 코드 작성
5. REST API의 CRUD 기능 전반 구현

즉, 이번 실습의 핵심은 단순히 동작하는 코드를 작성하는 것이 아니라, 정리된 구조와 유지보수 가능한 코드를 직접 설계하고 구현하는 것입니다.

실무에서 백엔드를 처음 시작할 때 어떤 흐름으로 개발을 진행해야 하는지, 그 뼈대를 이번 실습을 통해 직접 익히게 될 거예요.

이제 다음 단계로 넘어가서, 구체적인 데이터 모델을 어떻게 설계할지 알아보겠습니다.

2. 데이터 모델 설계 📐

서비스를 만들기 전, 가장 먼저 해야 할 일은 데이터 구조를 어떻게 설계할 것인가입니다.

바로 모델링이죠.

데이터베이스 구조가 깔끔하게 설계되어야 API도 명확하게 작동하고, 유지보수도 수월해집니다.

이번엔 선택한 프로젝트 유형에 따라 각기 다른 모델을 설계하게 됩니다.

2.1 블로그 API 모델 예시 ✍️

블로그 API를 선택한 경우, 보통 다음과 같은 세 가지 모델이 필요해요:

여기서 중요한 건 외래키 관계입니다.

Post와 Comment는 모두 User와 연결되고, Comment는 Post에도 연결되죠.

SQLAlchemy에서는 ForeignKey와 relationship으로 이를 구현할 수 있어요.

2.2 Todo API 모델 예시 ✅

Todo 프로젝트는 더 단순합니다. 모델은 아래 두 개만 필요하죠.

💡 모델 설계 팁

• 문자열 길이 제한을 String(length)으로 명확하게 지정하세요.
• nullable=False는 필수 필드에 반드시 지정해줘야 합니다.
• 고유성이 필요한 필드는 unique=True로 중복 방지!

이제 데이터 모델이 명확하게 정리되었으니,

다음 단계는 실제 프로젝트 디렉토리 구조를 만들고 빈 틀을 잡아보는 것입니다.

프로젝트가 커질수록 구조가 중요해지니까요.

계속해서 다음 단계에서 프로젝트 뼈대를 만들어볼게요!

3. 프로젝트 구조 뼈대 만들기 🧱

FastAPI 프로젝트를 시작할 때 가장 먼저 해야 할 일은 전체 폴더 구조를 체계적으로 잡는 것이에요.

한 파일 안에 모든 코드를 몰아넣는 방식은 소규모 예제에선 괜찮지만, 프로젝트가 커지면 유지보수가 거의 불가능하죠.

이번 프로젝트에서는 아래와 같은 구조를 기준으로 설계를 시작합니다.

3.1 기본 디렉토리 구조

myapi/
├── main.py               # FastAPI 앱 실행 진입점
├── models.py             # SQLAlchemy ORM 모델 정의
├── schemas.py            # Pydantic 데이터 모델 정의
├── database.py           # DB 설정 (engine, session, get_db)
├── routers/
│   ├── users.py          # 사용자 관련 라우터
│   └── posts.py          # 블로그 글 관련 라우터 (or todos.py)
└── __init__.py           # 패키지 초기화 파일 (선택 사항)

✅ 핵심 원칙은 다음과 같아요:

• 각 기능을 독립적인 모듈로 구성 → 관심사의 분리(SOC) 원칙 준수
• DB 관련 코드는 database.py에 모아서 일원화
• Pydantic 모델은 schemas.py에서 관리하여 API 스키마 명확화

🛠 main.py 기본 틀

from fastapi import FastAPI
from routers import users, posts  # 또는 todos

app = FastAPI()

app.include_router(users.router)
app.include_router(posts.router)

🔌 database.py 기본 구성

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./test.db"

engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

이처럼 프로젝트 초기 구조를 잘 설계하면, 나중에 기능을 추가할 때도 훨씬 덜 헤매고 유지보수가 쉬워집니다.

앞으로 posts.py, todos.py, comments.py 등을 기능별로 확장할 수 있도록 유연한 구조로 시작하세요!

이제 구조가 준비되었으니, 본격적으로 사용자 기능부터 구현해볼까요?

다음 섹션에서는 사용자 생성과 조회를 구현하면서 실전 코딩을 시작합니다!

4. 사용자 기능 구현 🔐

프로젝트에서 사용자(User)는 모든 기능의 출발점이에요.

할일이든 게시글이든 결국 ‘누가 작성했는지’가 중요하니까요.

이번 단계에서는 사용자 등록(POST)과 조회(GET) API를 구현합니다.

이 두 기능만 제대로 작동해도 프로젝트의 절반은 성공한 셈이에요!

4.1 Pydantic 스키마 만들기

우선 schemas.py에 사용자 관련 데이터 구조를 정의합니다:

from pydantic import BaseModel, EmailStr

class UserBase(BaseModel):
    username: str
    email: EmailStr

class UserCreate(UserBase):
    password: str

class User(UserBase):
    id: int

    class Config:
        orm_mode = True

4.2 SQLAlchemy 모델 정의

models.py에는 사용자 모델을 다음과 같이 정의해요:

from sqlalchemy import Column, Integer, String
from database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(30), unique=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    hashed_password = Column(String(128), nullable=False)

💡 비밀번호는 평문 저장 No!

여기선 해시 없이 저장하겠지만, 실무에서는 꼭 bcrypt 같은 해싱 알고리즘을 사용해야 해요.

4.3 사용자 생성 API

# routers/users.py
from fastapi import APIRouter, HTTPException, Depends
from sqlalchemy.orm import Session
from database import get_db
import models, schemas

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

@router.post("/", response_model=schemas.User)
def create_user(user: schemas.UserCreate, db: Session = Depends(get_db)):
    existing_user = db.query(models.User).filter(
        (models.User.username == user.username) | (models.User.email == user.email)
    ).first()
    if existing_user:
        raise HTTPException(status_code=400, detail="Username or email already exists")

    db_user = models.User(
        username=user.username,
        email=user.email,
        hashed_password=user.password  # 실무에서는 해싱 필수!
    )
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

4.4 사용자 조회 API

@router.get("/{user_id}", response_model=schemas.User)
def read_user(user_id: int, db: Session = Depends(get_db)):
    user = db.query(models.User).filter(models.User.id == user_id).first()
    if user is None:
        raise HTTPException(status_code=404, detail="User not found")
    return user

🧪 테스트 팁

• Swagger UI(/docs)에서 POST → 바로 GET으로 테스트 가능!
• uvicorn main:app --reload로 서버 실행하세요.

이제 사용자가 등록되고 조회되는 API가 완성되었습니다!

이 데이터를 기반으로 다음 단계에서는 본격적인 게시글(Post) 혹은 할일(Todo) 기능을 구현해보겠습니다.

5. 글쓰기 or 할일 등록 기능 구현 ✏️

이제 사용자 기능이 잘 작동하는 걸 확인했다면, 다음은 본 서비스의 중심 기능인 게시글(Post) 또는 할일(Todo)을 구현할 차례입니다.

블로그 API를 선택한 분은 글쓰기 기능을, Todo API를 선택한 분은 할일 등록 기능부터 차근차근 구현해보면 됩니다.

5.1 블로그 글쓰기 기능 (POST /posts/) 📝

# schemas.py
from datetime import datetime

class PostBase(BaseModel):
    title: str
    content: str

class PostCreate(PostBase):
    author_id: int

class Post(PostBase):
    id: int
    created_at: datetime
    author_id: int

    class Config:
        orm_mode = True

# models.py
from sqlalchemy import Column, Integer, String, ForeignKey, DateTime
from sqlalchemy.orm import relationship
from datetime import datetime

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(100), nullable=False)
    content = Column(String, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)
    author_id = Column(Integer, ForeignKey("users.id"), nullable=False)

    author = relationship("User", backref="posts")

# routers/posts.py
@router.post("/", response_model=schemas.Post)
def create_post(post: schemas.PostCreate, db: Session = Depends(get_db)):
    db_post = models.Post(
        title=post.title,
        content=post.content,
        author_id=post.author_id
    )
    db.add(db_post)
    db.commit()
    db.refresh(db_post)
    return db_post

5.2 글 목록 및 상세 조회 (GET /posts/, /posts/{id}) 📚

@router.get("/", response_model=List[schemas.Post])
def read_posts(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    posts = db.query(models.Post).offset(skip).limit(limit).all()
    return posts

@router.get("/{post_id}", response_model=schemas.Post)
def read_post(post_id: int, db: Session = Depends(get_db)):
    post = db.query(models.Post).filter(models.Post.id == post_id).first()
    if not post:
        raise HTTPException(status_code=404, detail="Post not found")
    return post

쿼리 파라미터로 skip과 limit을 받아 간단한 페이징 기능도 적용해봤어요.

물론 실제 서비스라면 페이지 번호, 정렬 기준 등 더 다양한 필터가 필요하겠지만, 지금은 핵심 흐름만 익히는 게 중요합니다.

5.3 할일 등록 기능 (POST /todos/) ✅

# schemas.py
class TodoBase(BaseModel):
    title: str
    description: str

class TodoCreate(TodoBase):
    user_id: int

class Todo(TodoBase):
    id: int
    completed: bool
    priority: int

    class Config:
        orm_mode = True

# models.py
class Todo(Base):
    __tablename__ = "todos"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(100), nullable=False)
    description = Column(String, nullable=False)
    completed = Column(Boolean, default=False)
    priority = Column(Integer, default=1)
    user_id = Column(Integer, ForeignKey("users.id"))

    user = relationship("User", backref="todos")

# routers/todos.py
@router.post("/", response_model=schemas.Todo)
def create_todo(todo: schemas.TodoCreate, db: Session = Depends(get_db)):
    db_todo = models.Todo(
        title=todo.title,
        description=todo.description,
        user_id=todo.user_id
    )
    db.add(db_todo)
    db.commit()
    db.refresh(db_todo)
    return db_todo

5.4 할일 목록 및 상세 조회 (GET /todos/, /todos/{id}) 📋

@router.get("/", response_model=List[schemas.Todo])
def read_todos(db: Session = Depends(get_db)):
    return db.query(models.Todo).all()

@router.get("/{todo_id}", response_model=schemas.Todo)
def read_todo(todo_id: int, db: Session = Depends(get_db)):
    todo = db.query(models.Todo).filter(models.Todo.id == todo_id).first()
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo

여기까지 완성되면 사용자 - 게시글, 또는 사용자 - 할일 구조의 기본 CRUD의 반 이상이 만들어진 셈입니다. 다음 단계에선 이 모든 기능들이 실제로 잘 작동하는지 테스트해보는 실습을 진행할 거예요!

6. 서버 실행 및 결과 테스트 ⚙️

이제 우리 프로젝트의 기본 기능은 모두 구현이 끝났습니다!

이제는 서버를 실행해보고, 실제 요청을 보내보며 테스트하는 단계입니다.

FastAPI의 가장 큰 장점 중 하나가 바로 Swagger UI를 통한 인터랙티브 테스트 환경이죠.

하나씩 점검하면서 내가 만든 API가 잘 작동하는지 직접 확인해봅시다.

6.1 서버 실행하기

uvicorn main:app --reload

이 명령어로 로컬 서버를 실행하면 http://127.0.0.1:8000/docs 에서 자동 생성된 Swagger 문서에 접속할 수 있습니다.

이제 각 API 기능을 직접 클릭해보며 테스트해볼 수 있어요.

6.2 주요 테스트 시나리오 🧪

• POST /users/ : 사용자 등록 요청 → 성공 시 200 반환 및 ID 확인
• GET /users/{id} : 등록한 사용자 조회 → 사용자 정보 반환
• POST /posts/ 또는 /todos/ : 글 또는 할일 등록
• GET /posts/ 또는 /todos/ : 전체 목록 확인
• GET /posts/{id} 또는 /todos/{id} : 상세 페이지 확인

🚨 자주 발생하는 오류

• IntegrityError: 이미 존재하는 username 또는 email → 400 예외 처리 필요
• AttributeError: 'dict' object has no attribute → Pydantic 모델에 orm_mode = True 빠짐

6.3 마무리 점검 리스트 ✅

축하합니다! 여기까지 완성했다면 여러분은 이제 FastAPI 기반의 실제 동작하는 백엔드 서비스를 손수 구현해본 경험을 쌓으신 거예요.

마무리 🎯

지금까지 FastAPI와 SQLAlchemy를 활용한 실전 API 프로젝트를 함께 구현해보았습니다.

단순한 Hello World 수준을 넘어, 사용자 생성부터 게시글/할일 등록, 조회 API까지 완성된 상태의 백엔드가 완성되었죠.

직접 설계한 데이터 모델, 모듈화된 프로젝트 구조, 그리고 인터랙티브한 Swagger UI 테스트까지. 이건 단순한 튜토리얼이 아니라, 실무 감각을 기를 수 있는 제대로 된 훈련이었어요.

이번 실습이 끝이 아니라는 점, 기억해주세요!

이후에는 글 수정 및 삭제 기능, 댓글 기능, JWT 인증 및 권한 관리, 에러 핸들링 구조화, pytest를 활용한 테스트 자동화 등 보다 확장된 기능을 다룰 예정입니다.

실제로 서비스를 만들고 싶다면 지금 만든 코드를 바탕으로 Docker, GitHub Actions, AWS EC2 배포까지 이어가볼 수 있겠죠? 이제 여러분 손에 달렸습니다.

지금 당장 터미널을 열고 새로운 아이디어로 코딩을 시작해보세요.

세상에 단 하나뿐인 여러분만의 API 서비스가 될 수도 있으니까요!

파이썬 FastAPI 예외 처리, 테스트 및 프로젝트 구조화

실무에서 진짜 중요한 FastAPI 프로젝트의 마무리 3대장!
예외 처리, 테스트, 구조화로 완성도를 끌어올려보세요.

안녕하세요, 여러분!

오늘은 FastAPI를 활용한 프로젝트에서 완성도와 유지보수성을 높이는 핵심 주제 3가지를 함께 살펴보려 합니다.

FastAPI는 정말 빠르고 유연한 웹 프레임워크지만, 규모가 커지면 예외 처리와 테스트, 그리고 깔끔한 프로젝트 구조가 필수죠.

초반엔 하나의 파일에 모든 걸 몰아넣는 게 편하게 느껴질 수 있지만, 진짜 문제는 그 이후부터입니다.

에러가 터지거나, 기능이 많아지고, 팀과 협업하는 상황이 오면 코드 관리가 점점 지옥이 되거든요. 😓

그래서 오늘은 그런 혼돈을 예방할 수 있는 3가지 실전 기술을 소개하려고 합니다.

하나씩 차근차근 설명드릴게요. 초보자도 충분히 따라올 수 있으니 걱정 마세요!

1. 효율적인 프로젝트 구조 설계하기 🏗️

1.1 모듈화의 필요성과 폴더 구조

FastAPI 프로젝트가 커지기 시작하면 코드가 한 파일에 몰려 있으면 유지보수가 매우 어려워져요.

기능이 많아질수록 파일을 나누고, 책임을 분리하고, 폴더 구조를 체계적으로 구성하는 것이 필수입니다.

FastAPI에서 추천하는 기본적인 디렉터리 구조는 다음과 같습니다:

app/
├── main.py          # FastAPI 앱 실행 진입점
├── models.py        # SQLAlchemy 모델 정의
├── schemas.py       # Pydantic 스키마 정의
├── database.py      # DB 설정, 연결 관리
├── routers/
│   ├── __init__.py
│   ├── users.py     # 사용자 관련 API
│   └── todos.py     # 할일 관련 API
└── core/
    └── config.py    # 환경 변수 및 설정 관리

각 파일과 폴더가 맡는 역할이 명확하죠?

특히 routers 폴더는 기능별 라우트를 나누기 좋고, core 폴더에는 설정 파일을 정리할 수 있어요.

1.2 APIRouter로 구조화하는 방법

FastAPI에서는 APIRouter를 활용해서 라우팅을 기능 단위로 나눌 수 있어요.

예를 들어 todos 관련 API는 routers/todos.py에

다음과 같이 구성합니다:

from fastapi import APIRouter, Depends, HTTPException
from .. import models, schemas
from ..database import get_db
from sqlalchemy.orm import Session

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

@router.get("/", response_model=List[schemas.TodoItem])
def list_todos(db: Session = Depends(get_db)):
    return db.query(models.Todo).all()

이제 main.py에서는 이렇게 간단히 router를 불러와 등록하면 돼요:

from fastapi import FastAPI
from .routers import users, todos

app = FastAPI()
app.include_router(users.router)
app.include_router(todos.router)

이런 식으로 각 기능은 독립적으로 관리되고, main에서는 전체 앱을 조립하는 역할만 하게 됩니다.

마치 블록처럼요!

1.3 모듈 간 의존성과 순환참조 방지

구조화할 때 주의할 점 중 하나는 순환 참조(Circular Import)입니다. 예를 들어 models.py가 schemas.py를 import하고, schemas.py가 다시 models.py를 참조하면 문제 발생! 😵‍💫

해결 방법은 의외로 간단해요.

보통 schemas.py는 오직 필드 선언에만 집중하고, models.py는 비즈니스 로직 중심으로 구성합니다.

서로 직접 참조하지 않게 하고, 실제 연결은 routers/*.py 파일에서 이루어지도록 조정하면 돼요.

추가로 환경 설정은 core/config.py에 넣고, .env 파일과 pydantic.BaseSettings를 함께 쓰면 환경별로 설정을 유연하게 다룰 수 있어요.

• 기능별로 파일을 나누었는가?
• 순환참조를 피했는가?
• APIRouter를 적절히 활용했는가?

2. APIRouter를 활용한 모듈화 📦

2.1 APIRouter란 무엇인가요?

FastAPI에서 APIRouter는 말 그대로 “라우터” 역할을 해요.

여러 개의 API 경로들을 하나로 묶어주는 객체인데, 마치 미니 FastAPI 인스턴스처럼 동작해요.

FastAPI의 구조화된 애플리케이션을 만들기 위해 필수적인 도구라고 볼 수 있죠.

main.py 하나에 모든 API 경로를 넣으면 작고 단순할 땐 괜찮지만, 규모가 커지면 지옥 같은 수정의 나락이 펼쳐집니다. 😱

그래서 각 기능별로 라우터를 나눠주는 것이 좋아요.

2.2 APIRouter 사용 예제

routers/todos.py 파일에서 할 일(Todo) 목록을 관리하는 API를 만든다고 가정해볼게요:

from fastapi import APIRouter, Depends, HTTPException
from typing import List
from .. import models, schemas
from ..database import get_db
from sqlalchemy.orm import Session

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

@router.get("/", response_model=List[schemas.TodoItem])
def list_todos(db: Session = Depends(get_db)):
    return db.query(models.Todo).all()

이제 main.py에 가서 해당 라우터를 연결하면 됩니다:

from fastapi import FastAPI
from .routers import todos

app = FastAPI()
app.include_router(todos.router)

prefix="/todos" 덕분에 /todos로 시작하는 모든 경로가 이 라우터에 포함됩니다.

tags는 자동 문서화(swagger UI)에서 그룹 이름처럼 사용되죠.

2.3 APIRouter의 이점 💡

• 기능별로 API를 독립적으로 관리 가능 → 유지보수 용이
• Swagger 문서에서 각 API 그룹을 구분해 보여줌 → 테스트 용이
• 다른 파일과 독립적으로 테스트 가능 → 유닛 테스트 구성에도 유리

프로젝트가 점점 커질수록 APIRouter를 쓰는 구조는 선택이 아니라 필수가 됩니다.

기획자나 다른 개발자가 함께 보는 문서화된 API를 만드는 데도 매우 유리하거든요.

3. FastAPI의 예외 처리 방법 알아보기 ⚠️

3.1 HTTPException의 기본 사용법

FastAPI에서 예외를 처리할 때 가장 기본이 되는 클래스가 바로 HTTPException이에요.

이걸 이용하면 코드에서 명시적으로 에러 응답을 보낼 수 있죠.

예를 들면 이렇습니다:

from fastapi import HTTPException

if not user:
    raise HTTPException(status_code=404, detail="User not found")

이 코드가 실행되면 FastAPI는 자동으로 {"detail": "User not found"} 같은 JSON 응답과 함께 404 상태 코드를 반환합니다.

3.2 자주 쓰는 예외 처리 시나리오

• 조회할 데이터가 없을 때 → raise HTTPException(status_code=404)
• 사용자 인증 실패 시 → status_code=401 또는 403
• 클라이언트의 잘못된 요청 → status_code=400과 적절한 메시지

detail에 넣는 메시지는 문자열이나 JSON 형태가 가능해서 에러 코드와 설명을 같이 담을 수도 있어요. 예:

raise HTTPException(
    status_code=400,
    detail={"error": "Invalid email", "code": 1001}
)

이렇게 하면 클라이언트에서 에러 코드를 받아서 처리하기 쉬워지죠.

3.3 FastAPI의 자동 유효성 검사

FastAPI는 입력 데이터의 유효성 검사를 자동으로 해줍니다.

예를 들어 Pydantic 모델에서 title: str로 지정해두면, 숫자나 null이 들어왔을 때 자동으로 422 Unprocessable Entity 오류를 반환해요.

다만, 값은 타입이 맞더라도 비즈니스 로직에 어긋나는 경우는 직접 HTTPException으로 처리해줘야 합니다.

예를 들어 제목이 빈 문자열이면 아래처럼 처리할 수 있어요:

if todo.title.strip() == "":
    raise HTTPException(status_code=400, detail="Title cannot be empty")

이처럼 자동 유효성 검사 + 비즈니스 검증을 조합하면, 훨씬 견고한 API를 만들 수 있어요.

• 모든 API 경로에서 404/400 등 에러 핸들링 했나요?
• 입력 데이터 유효성 검사에 Pydantic을 사용했나요?
• 필요한 경우 커스텀 detail 메시지를 포함했나요?

4. 전역 예외 핸들러 활용법 💥

4.1 커스텀 예외 핸들러란?

FastAPI는 예외 처리기를 전역으로 등록할 수 있어요.

즉, 특정 예외가 발생했을 때 공통된 형식의 응답을 보내고 싶다면 핸들러를 따로 정의해서 자동으로 처리되게 할 수 있다는 말이죠.

예를 들어 데이터베이스의 제약 조건 위반 같은 경우, 매번 처리하기보다는 한 번에 묶어서 처리하면 편하겠죠?

4.2 SQLAlchemy 예외 핸들링 예제

SQLAlchemy에서 가장 자주 만나는 예외 중 하나는 IntegrityError입니다.

중복된 키 삽입, not null 위반 등에서 발생하는 예외죠.

이걸 전역으로 처리해봅시다.

from fastapi.responses import JSONResponse
from sqlalchemy.exc import IntegrityError
from fastapi import Request, FastAPI

app = FastAPI()

@app.exception_handler(IntegrityError)
async def integrity_error_handler(request: Request, exc: IntegrityError):
    return JSONResponse(
        status_code=400,
        content={"detail": "데이터베이스 제약 조건 위반 (중복, null 등)"}
    )

이제 어떤 라우터에서든 IntegrityError가 발생하면 자동으로 이 핸들러가 실행되어 공통된 메시지를 보내게 됩니다. 무척 깔끔하죠? 👍

4.3 RequestValidationError 커스터마이징

FastAPI는 입력 검증에 실패하면 기본적으로 422 오류와 함께 RequestValidationError를 발생시켜요. 그런데 이 에러 메시지가 너무 상세하거나 개발자스러워서, 사용자 입장에서는 당황스러울 수 있어요.

그럴 땐 아래처럼 기본 예외 핸들러를 오버라이딩해서 에러 메시지를 심플하게 바꿔줄 수 있습니다:

from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.exception_handlers import request_validation_exception_handler

@app.exception_handler(RequestValidationError)
async def custom_validation_handler(request, exc):
    return JSONResponse(
        status_code=422,
        content={"detail": "입력 형식이 잘못되었습니다. 필수 값을 확인하세요."}
    )

물론 실제 서비스에서는 유형별 메시지 분기나 exc.errors()를 순회하여 더 정교하게 구성할 수도 있어요.

4.4 실무에서의 활용 포인트 💡

• 모든 라우터에서 반복되는 예외 처리 코드 제거
• 사용자에게 친절하고 일관된 오류 메시지 제공
• 로깅과 모니터링에 유리한 구조 구성 가능

전역 예외 핸들러는 단순히 “에러를 막는” 게 아니라 일관성 있고 신뢰감 있는 서비스를 만드는 첫걸음입니다.

5. TestClient를 사용한 테스트 자동화 🧪

5.1 FastAPI의 TestClient란?

FastAPI는 Starlette를 기반으로 만들어졌기 때문에 TestClient라는 테스트 도구를 제공합니다.

이 도구는 실제 서버를 실행하지 않고도 app 객체를 직접 호출하여 테스트를 할 수 있도록 해주는 매우 강력한 기능이에요.

보통 pytest와 함께 사용되며, REST API의 요청/응답 시나리오를 자동화하는 데 아주 적합합니다.

즉, 매번 브라우저나 Postman으로 테스트하지 않아도 된다는 거죠!

5.2 기본 테스트 코드 작성법

아래는 간단한 예시입니다.

test_main.py 파일을 만들고 다음과 같은 테스트 코드를 작성해볼 수 있어요:

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_todo():
    response = client.post("/todos", json={"title": "Test", "description": "Test Desc"})
    assert response.status_code == 201
    assert response.json()["title"] == "Test"

def test_read_todo_not_found():
    response = client.get("/todos/999")
    assert response.status_code == 404

위 테스트는 할일을 생성하고, 존재하지 않는 할일을 조회할 때 404를 반환하는지를 검증합니다.

.get, .post, .delete 등을 통해 실제 요청을 시뮬레이션할 수 있고, response.status_code나 response.json()으로 응답 값을 비교합니다.

5.3 테스트에서 자주 검증하는 항목들

• 상태 코드가 올바르게 반환되는가?
• 응답 데이터의 필드/값이 기대한 대로 구성되어 있는가?
• 에러 발생 시 에러 메시지가 정확히 반환되는가?

5.4 실무 팁 💡

• 테스트 함수는 반드시 test_로 시작해야 pytest에서 인식합니다.
• 반복되는 검증 로직은 함수로 분리해 재사용성을 높입니다.
• 정상 케이스뿐 아니라 에러 케이스도 테스트하세요!

테스트는 개발자의 실수를 사전에 방지해주는 방패입니다.

특히 협업하거나 유지보수가 필요한 프로젝트에서는 테스트 코드의 유무가 신뢰성과 품질의 기준이 되기도 해요.

6. 테스트 환경의 DB 처리 전략 🗄️

6.1 테스트에 실제 DB를 쓰면 안 되는 이유

실제 개발용 데이터베이스를 테스트에 사용하면 어떤 일이 벌어질까요?

예기치 않게 데이터를 삭제하거나 오염시킬 수 있습니다. 😱

특히 DELETE나 DROP 같은 쿼리를 테스트하는 경우에는 더더욱 위험하죠.

그래서 테스트 환경에서는 격리된 테스트 전용 DB를 사용하는 것이 원칙입니다.

6.2 메모리 SQLite DB 사용 예제

FastAPI에서 SQLite의 메모리 DB는 테스트 환경을 빠르게 구성할 수 있는 좋은 도구입니다.

아래는 예시 설정입니다:

# test_db.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from app.models import Base

SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"

engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

def override_get_db():
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.close()

그리고 main.py 또는 conftest.py에서 FastAPI의 의존성을 오버라이드 해줍니다:

from app.main import app
from app.test_db import override_get_db

app.dependency_overrides[get_db] = override_get_db

이렇게 하면 테스트에서 사용하는 get_db()가 실제 DB가 아닌 임시 메모리 DB로 교체됩니다.

테스트마다 새로운 환경에서 시작되니 데이터 충돌 걱정 없이 깔끔하게 실행 가능해요.

6.3 데이터 초기화 전략

테스트 전에 테이블을 생성하고 데이터를 초기화해주는 것도 중요합니다.

아래처럼 setup_function 혹은 pytest.fixture를 사용해 테스트 시작 전에 초기 세팅을 할 수 있어요.

import pytest
from app.test_db import engine, Base

@pytest.fixture(scope="function", autouse=True)
def setup_and_teardown():
    Base.metadata.create_all(bind=engine)
    yield
    Base.metadata.drop_all(bind=engine)

이렇게 하면 테스트마다 DB가 깨끗하게 리셋되기 때문에, 데이터 충돌로 인한 테스트 실패를 방지할 수 있어요.

6.4 실전 활용 팁 💡

• 테스트용 DB URL을 별도로 구성하고 설정 파일로 분리하세요.
• 테스트 중 발생하는 로그는 최소화하여 결과에 집중할 수 있도록 합니다.
• CI 환경에서는 --disable-warnings 옵션을 이용해 깔끔한 출력 유지

테스트의 핵심은 "예측 가능한 상태에서 테스트가 반복 가능해야 한다"는 것이에요.

이를 위해 테스트용 DB는 선택이 아닌 필수 전략입니다.

마무리하며 🌱

이번 글에서는 FastAPI 프로젝트의 후반부에서 반드시 챙겨야 할 예외 처리, 테스트, 구조화 전략에 대해 하나씩 짚어봤습니다.

단순히 기능을 구현하는 것을 넘어서, 확장성과 유지보수성을 고려한 설계가 왜 중요한지를 느끼셨을 거예요.

특히 예외 처리에서는 HTTPException과 전역 핸들러의 활용, 테스트에서는 TestClient와 SQLite 메모리 DB의 유용함, 그리고 APIRouter를 통한 구조화는 프로젝트의 ‘완성도’를 좌우합니다.

코드가 잘 돌아가는 것도 좋지만, 에러에 강하고 테스트가 보장된 프로젝트가 진짜 안정적인 프로젝트예요.

FastAPI를 쓰면 API를 정말 빠르게 만들 수 있지만, 그 위에 신뢰성과 관리 용이성이라는 무기를 더해보세요. 그게 바로 한 단계 높은 개발자의 길이니까요. 😉

이제 여러분의 FastAPI 프로젝트는 단순한 샘플이 아닌, 실제 서비스로 연결될 수 있는 기반이 갖춰졌습니다. 이제 자신 있게 확장하고 테스트하고, 에러를 두려워하지 마세요!

파이썬 FastAPI 고급 ORM – 관계 모델링과 다중 테이블 연동

여러분의 FastAPI 앱이 점점 커지고 있나요?
단일 테이블로는 한계가 있다 느낄 때,
지금이 바로 관계형 모델링을 배워야 할 타이밍입니다!

안녕하세요, 개발자 여러분 😊
오늘은 FastAPI와 SQLAlchemy ORM을 활용하여 "다중 테이블 관계 설정"과 Pydantic 스키마 연계까지 다뤄볼 거예요.

특히 User와 Todo 같은 실용적인 예제를 중심으로 일대다(1:N), 다대다(N:M) 관계를 어떻게 모델링하는지, 그리고 이를 CRUD API로 어떻게 연결하는지 구체적으로 살펴봅니다.

FastAPI를 사용하다 보면 단일 테이블로 구현한 간단한 예제는 금방 만들 수 있지만, 실제 애플리케이션에서는 테이블 간의 관계가 필수입니다. 오늘은 이걸 제대로 배워볼 거예요.

1. 테이블 간 관계 설정의 기초 🧩

FastAPI에서 데이터베이스를 제대로 다루기 위해선 SQLAlchemy ORM을 이용한 관계형 모델링이 거의 필수예요.

특히 다수의 테이블이 얽힌 구조에서는 일대다(One-to-Many), 다대다(Many-to-Many) 같은 관계 설정이 핵심이 됩니다.

예를 들어 한 명의 사용자가 여러 개의 Todo를 소유하거나, 여러 사용자가 여러 프로젝트에 동시에 참여할 수 있다면 관계형 설계가 반드시 필요하죠.

1.1 일대다 관계란 무엇인가요?

가장 흔한 관계가 바로 1:N 관계예요.

한 사람이 여러 개의 블로그 글을 작성하는 경우처럼요.

이를 SQLAlchemy에서는 다음과 같은 방식으로 표현합니다:

from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True, index=True)
    posts = relationship("Post", back_populates="author")

class Post(Base):
    __tablename__ = "posts"
    id = Column(Integer, primary_key=True)
    title = Column(String)
    content = Column(String)
    author_id = Column(Integer, ForeignKey("users.id"))
    author = relationship("User", back_populates="posts")

여기서 핵심은 ForeignKey와 relationship입니다.

Post.author_id는 User 테이블의 id를 참조하는 외래 키이고, 두 모델은 back_populates로 서로를 참조합니다.

이 설정 덕분에 user.posts로 해당 사용자의 모든 게시글을 가져올 수 있고, post.author로 작성자 정보를 조회할 수 있어요.

1.2 다대다 관계는 어떻게 구성할까요?

조금 더 복잡한 구조인 N:M 관계는 중간 테이블(association table)을 만들어야 합니다.

예를 들어 사용자와 프로젝트는 다음과 같이 설정할 수 있습니다.

association_table = Table(
    "user_project",
    Base.metadata,
    Column("user_id", ForeignKey("users.id"), primary_key=True),
    Column("project_id", ForeignKey("projects.id"), primary_key=True),
)

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String)
    projects = relationship("Project", secondary=association_table, back_populates="members")

class Project(Base):
    __tablename__ = "projects"
    id = Column(Integer, primary_key=True)
    title = Column(String)
    members = relationship("User", secondary=association_table, back_populates="projects")

이처럼 secondary 파라미터를 이용해 중간 테이블을 지정하고, 관계를 서로 연결하면 user.projects, project.members로 양방향 접근이 가능해요.

실제 현업에서도 협업 앱, 팀 관리 시스템 등에서 자주 쓰이는 구조입니다.

📋 일대다 vs 다대다 – 요약 비교

이제 관계 설정의 기초를 이해하셨다면, 다음 단계에서는 실제로 FastAPI에서 SQLAlchemy ORM 모델을 작성하고, 이 관계가 어떻게 작동하는지 하나씩 코드를 통해 살펴볼 거예요.

2. 관계를 표현하는 SQLAlchemy 모델 구조 🏗️

자, 이제 본격적으로 모델을 구성해볼 시간이에요.

FastAPI에서 SQLAlchemy ORM을 사용할 때는 클래스를 기반으로 테이블을 정의하고,

relationship()과 ForeignKey()를 통해 테이블 간의 관계를 표현합니다.

우리가 구현할 시나리오는 아주 현실적이에요:

사용자(User)가 여러 개의 할 일(Todo)을 가질 수 있는 일대다(1:N) 구조입니다.

2.1 사용자(User)와 할 일(Todo) 모델 정의

아래 코드는 SQLAlchemy ORM을 사용한 관계형 모델 정의 예시입니다.

중요한 건 각 모델이 서로를 어떻게 참조하고 있는지예요.

from sqlalchemy import Column, Integer, String, Boolean, ForeignKey
from sqlalchemy.orm import relationship
from database import Base  # Base는 SQLAlchemy의 declarative_base()로 정의

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    todos = relationship("Todo", back_populates="owner")

class Todo(Base):
    __tablename__ = "todos"
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, index=True)
    description = Column(String, nullable=True)
    done = Column(Boolean, default=False)
    owner_id = Column(Integer, ForeignKey("users.id"))
    owner = relationship("User", back_populates="todos")

이 구조에서 User.todos는 해당 사용자가 작성한 모든 Todo 항목을 리스트로 반환하며, Todo.owner는 해당 항목의 작성자(User 객체)를 가리킵니다.

이렇게 하면 ORM 객체 간 탐색이 매우 쉬워져요.

🧠 관계형 구조의 장점은?

• ORM 객체 간 탐색이 쉬워져 복잡한 쿼리를 단순화할 수 있습니다.
• Pydantic과 함께 사용할 때 직관적인 JSON 변환이 가능합니다.
• 모델 간의 의존성 설계가 명확해져 유지보수가 쉬워집니다.

2.2 모델 구조 정리 예시

이제 관계 설정이 완료된 ORM 모델 구조를 완성했어요!

다음 단계에서는 Pydantic 스키마를 통해 ORM 객체와 어떻게 연동하고 응답 데이터를 어떻게 구성하는지 다뤄볼게요.

이 부분이 바로 FastAPI의 강력함이 드러나는 순간입니다 💪

3. Pydantic 스키마와 ORM 연계하기 🔄

FastAPI의 가장 큰 장점 중 하나는 Pydantic을 활용한 데이터 유효성 검증과 직렬화예요.

특히 ORM 모델과 Pydantic BaseModel을 함께 사용하면, 우리가 만든 SQLAlchemy 객체를 JSON으로 변환하거나 사용자 입력을 유효성 있게 처리하는 게 정말 간단해집니다.

핵심은 orm_mode 설정을 통해 ORM 객체를 바로 변환할 수 있도록 만드는 거예요.

3.1 Todo 스키마 구성

먼저 Todo 항목을 표현할 Pydantic 스키마를 작성해보겠습니다.

아래처럼 기본 정보와 orm_mode 설정만 해주면 FastAPI에서 ORM 객체를 응답 모델로 사용할 수 있게 됩니다.

from pydantic import BaseModel
from typing import Optional

class TodoItem(BaseModel):
    id: int
    title: str
    description: Optional[str] = None
    done: bool

    class Config:
        orm_mode = True

이제 response_model=TodoItem으로 설정한 API에서 SQLAlchemy Todo 객체를 반환하면, FastAPI가 자동으로 이 객체를 JSON으로 변환해줍니다.

놀랍게도 따로 변환 로직을 만들 필요가 없어요.

3.2 User 입력/출력 스키마 분리

FastAPI에서는 API의 목적에 따라 입력용과 출력용 스키마를 분리해서 사용하는 게 일반적이에요.

예를 들어 사용자 등록 시엔 비밀번호를 받아야 하지만, 사용자 정보를 응답할 땐 비밀번호가 절대 노출되어선 안 되죠.

class UserCreate(BaseModel):
    username: str
    password: str  # 실제로는 해싱 필요

class User(BaseModel):
    id: int
    username: str

    class Config:
        orm_mode = True

이처럼 분리함으로써 보안은 물론 API 명세도 깔끔해지고 유지보수가 쉬워져요.

특히 비밀번호 필드는 출력을 철저히 막는 게 기본입니다.

실습에서는 해싱을 생략하지만, 실제 서비스에서는 절대 평문 저장하면 안 된다는 거, 꼭 기억해주세요!

3.3 관계 필드를 포함한 응답 스키마

관계를 활용한 응답을 구성할 때는 중첩 모델(Nested Model)을 사용할 수 있어요.

예를 들어 사용자 조회 시 해당 사용자의 Todo 목록을 함께 반환하고 싶다면 아래처럼 구성합니다.

from typing import List

class UserWithTodos(BaseModel):
    id: int
    username: str
    todos: List[TodoItem] = []

    class Config:
        orm_mode = True

주의할 점은 데이터량이 많아지면 응답 속도나 용량에 영향을 줄 수 있으므로 꼭 필요한 경우에만 중첩 구조를 사용하는 게 좋습니다.

예를 들어 Todo가 수천 개라면...? 페이지네이션이 필요하겠죠 😅

✅ 정리: ORM ↔ Pydantic 연동 요약

이제 ORM과 스키마 간의 연결 고리를 완성했습니다.

다음은 이걸 활용해서 실제 API를 만들고, 사용자와 Todo 항목을 어떻게 엮는지 실습으로 들어가볼게요.

4. 사용자 기반 Todo API 만들기 ⚙️

지금부터는 앞서 만든 User ↔ Todo 관계를 실제 API에서 어떻게 다룰 수 있는지 구체적으로 알아볼게요.

예제를 통해 사용자와 연동된 Todo 항목을 만들고, 조회하고, 연결 관계를 유지하면서 데이터를 다룰 수 있게 해볼 거예요.

4.1 사용자 등록 API

사용자 등록은 POST /users로 진행합니다.

중복 사용자명을 체크하고, 평문 비밀번호를 그대로 저장합니다(실습 단순화용).

@app.post("/users", response_model=User)
def create_user(user: UserCreate, db: Session = Depends(get_db)):
    existing_user = db.query(User).filter(User.username == user.username).first()
    if existing_user:
        raise HTTPException(status_code=400, detail="이미 존재하는 사용자명입니다.")
    new_user = User(username=user.username)
    db.add(new_user)
    db.commit()
    db.refresh(new_user)
    return new_user

여기선 비밀번호 해싱 없이 단순하게 처리하지만, 실제 서비스라면 반드시 bcrypt 등으로 암호화해야 한다는 점 잊지 마세요.

4.2 사용자 기반 Todo 생성

이제 Todo 항목을 만들면서 사용자와 연결해볼게요.

POST /users/{user_id}/todos로 요청 시 해당 사용자의 소유 Todo를 생성하는 방식입니다.

@app.post("/users/{user_id}/todos", response_model=TodoItem)
def create_todo_for_user(user_id: int, todo: TodoItemCreate, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="해당 사용자를 찾을 수 없습니다.")
    new_todo = Todo(**todo.dict(), owner_id=user_id)
    db.add(new_todo)
    db.commit()
    db.refresh(new_todo)
    return new_todo

이 API는 user_id를 URL로 받고, 실제로 존재하는 사용자인지 확인한 후 그 사용자에게 Todo 항목을 연결해요. 데이터 무결성을 유지하는 좋은 예입니다.

4.3 사용자 별 Todo 목록 조회

GET /users/{user_id}/todos 요청으로 해당 사용자의 할 일 목록을 조회할 수 있어요. List[TodoItem] 형태로 응답하므로 클라이언트 입장에서도 처리하기 쉽습니다.

@app.get("/users/{user_id}/todos", response_model=List[TodoItem])
def get_user_todos(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="사용자가 존재하지 않습니다.")
    return user.todos

🚀 라우팅 구조 요약

• POST /users → 사용자 생성
• POST /users/{user_id}/todos → Todo 생성 (소유자 연결)
• GET /users/{user_id}/todos → Todo 목록 조회

이러한 RESTful한 구조는 실무에서도 아주 자주 사용되는 패턴입니다.

리소스 기반 URL 설계와 HTTP 메서드 의미를 자연스럽게 활용할 수 있어 API의 일관성과 가독성을 높여줘요.

5. 관계 응답과 데이터 최적화 전략 📦

데이터베이스 관계를 설정하고 API를 만들다 보면, 관계 필드를 API 응답에 포함해야 할 때가 많아요.

예를 들어 사용자 정보를 조회할 때 해당 사용자가 등록한 모든 할 일 목록까지 함께 보내주고 싶은 경우가 있죠.

이럴 땐 orm_mode=True 설정과 함께 Nested Pydantic 모델을 사용하면 됩니다.

5.1 관계 필드 포함한 사용자 응답 예시

앞서 정의한 UserWithTodos 스키마를 활용하면 사용자와 해당 사용자의 할 일을 한꺼번에 응답할 수 있어요.

@app.get("/users/{user_id}", response_model=UserWithTodos)
def get_user_detail(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="사용자를 찾을 수 없습니다.")
    return user

이 API는 매우 직관적이고, 프론트엔드 입장에서도 한 번의 요청으로 사용자와 그에 따른 할 일을 모두 받아볼 수 있으니 편리하죠.

하지만 여기에는 중요한 함정이 있어요…

5.2 Lazy Loading의 한계

SQLAlchemy는 기본적으로 관계 데이터를 지연 로딩(Lazy Loading)합니다.

즉, 관계 필드를 실제로 접근하기 전까지는 쿼리를 실행하지 않죠.

이게 편리하긴 한데, 반복되는 쿼리 발생으로 N+1 문제가 생길 수 있어요.

예를 들어 1명의 사용자를 불러오고 todos를 포함해 응답하려면, user.todos 접근 시마다 새로운 SELECT 쿼리가 실행되기 때문에 비효율적입니다.

이런 상황에선 selectinload() 같은 Eager Loading 전략을 사용하면 좋아요.

from sqlalchemy.orm import selectinload

@app.get("/users/{user_id}", response_model=UserWithTodos)
def get_user_with_todos(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).options(selectinload(User.todos)).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="해당 사용자가 없습니다.")
    return user

selectinload()를 옵션에 포함시키면, 사용자와 할 일 목록을 단 두 번의 쿼리로 한번에 가져올 수 있어서 효율적이에요.

5.3 중첩 응답의 설계 전략

모든 관계 데이터를 항상 응답에 포함시키는 건 좋은 전략이 아닐 수 있어요.

데이터가 커질수록 성능에 악영향을 줄 수 있거든요.

그래서 보통은 아래와 같은 전략을 추천해요.

• 단순 응답: 기본적으로 ID, 이름 등 요약된 정보만 제공
• 선택적 확장: 필요할 때만 쿼리 파라미터(ex: ?include=todos)로 전체 정보 요청
• 페이지네이션 도입: 할 일 목록이 많다면 offset/limit 사용

🔍 이런 경우 주의하세요!

관계가 양방향(back_populates)으로 설정되어 있는 경우 순환 참조 문제가 생길 수 있어요.

예를 들어 User → Todo → User → Todo... 식으로 무한 루프가 발생할 수 있으니, 이런 경우엔 관계 필드를 Optional로 정의하거나 재귀 깊이를 제어하는 방법을 활용해야 합니다.

이처럼 관계 응답은 강력한 기능이지만 설계 전략이 명확해야 성능과 보안 모두 잡을 수 있어요.

다음 단계에서는 실제 서비스에서 모델 구조가 변경되었을 때 어떻게 대응하는지, 마이그레이션 도구 Alembic을 소개해볼게요!

6. (선택) Alembic으로 마이그레이션 관리하기 📜

여러분, ORM 모델을 작성하고 데이터베이스와 연동하는 단계까지는 성공했지만, 현실은 언제나 변화하죠. 테이블 구조가 바뀌면 어떻게 해야 할까요?

매번 수동으로 SQL ALTER TABLE 문을 쓰기엔 너무 번거롭고 위험하기까지 합니다.

그래서 등장한 게 바로 Alembic입니다!

6.1 Alembic이란 무엇인가요?

Alembic은 SQLAlchemy 프로젝트의 공식 마이그레이션 도구예요.

우리가 ORM 모델을 수정하면, 이를 자동 감지해 버전 기반 마이그레이션 파일로 만들어주고, 데이터베이스에 적용하거나 되돌리는 작업을 쉽게 해줍니다.

• 모델 → DB 테이블 생성
• 모델 수정 → 마이그레이션 스크립트 자동 생성
• 변경 사항 추적 및 롤백 가능

6.2 설치 및 초기 설정

pip install alembic
alembic init alembic

위 명령어를 입력하면 alembic 폴더와 설정 파일이 생성돼요.

그다음 env.py 파일에서 SQLAlchemy Base 모델과 데이터베이스 URL을 연결해줘야 해요.

6.3 자동 마이그레이션 생성

alembic revision --autogenerate -m "Add owner_id to Todo"
alembic upgrade head

이렇게 하면 모델 변경 사항을 기반으로 마이그레이션 파일이 생성되고, upgrade head 명령으로 DB에 실제 적용할 수 있어요.

테이블이 추가되거나 컬럼이 변경될 때도 자동으로 반영되니 정말 유용하죠.

💡 팁: 버전 관리 전략

• 모든 모델 변경 시 마이그레이션 생성 필수!
• downgrade로 이전 버전으로 복구 가능 (테스트 환경에서 유용)
• 버전 파일은 Git으로 함께 관리!

이번 글에서는 실습에 Alembic을 직접 적용하지는 않았지만, FastAPI + SQLAlchemy를 실제 서비스에 도입할 때는 반드시 필요한 도구입니다.

공식 문서를 꼭 참고해 보시고, 여러분의 프로젝트에 도입해보세요!

지금까지 FastAPI에서 SQLAlchemy를 활용한 고급 ORM 관계 모델링과 다중 테이블 연동에 대해 하나하나 살펴보았습니다.

단순한 CRUD를 넘어서 관계를 정의하고, Pydantic 모델과 연계하고, 사용자 기반의 RESTful API를 만드는 실전 흐름까지 따라오셨다면 정말 큰 도약을 하신 거예요!

처음에는 관계 설정이 어렵게 느껴질 수 있지만, 코드를 따라 치고, 하나씩 요청을 만들어보면 생각보다 명확해진답니다.

특히 ORM 객체와 Pydantic 스키마의 분리, Lazy vs Eager Loading 개념, API 응답 최적화 전략은 실무에서도 자주 마주하게 되니 이번 기회에 확실히 익혀두시길 추천드려요.

앞으로 여러분의 FastAPI 프로젝트에 더 복잡한 모델 구조나 비즈니스 로직을 추가하게 되면, 이 관계 모델링이 탄탄한 기반이 되어줄 거예요.

그리고 모델이 복잡해질수록 Alembic을 통한 마이그레이션 관리는 필수입니다. 꼭 연습해보세요!

다음 글에서는 사용자 인증(Authentication)과 권한 부여(Authorization), OAuth2 등 보안 요소를 어떻게 FastAPI에 적용하는지 다룰 예정이에요.

궁금하셨던 분들 많으시죠? 😉 

파이썬 FastAPI 데이터베이스 연동
: SQLAlchemy ORM 시작

여러분, 웹 API를 만들었는데 데이터를 저장할 방법이 없어서 매번 초기화된다고요?
그렇다면 지금이 바로 ORM을 배워야 할 순간입니다!

안녕하세요, 여러분! 😊

FastAPI로 REST API를 구현하면서 데이터를 메모리나 리스트에만 저장했다면, 이제 다음 단계로 나아갈 차례입니다.

바로 데이터베이스 연동이죠.

특히 실습 환경에서는 간편한 SQLite로, 실전 배포 단계에서는 PostgreSQL이나 MySQL을 사용하게 될 텐데요.

오늘은 그 첫걸음으로 SQLAlchemy ORM을 FastAPI에 통합하는 방법을 알아보겠습니다.

ORM이 뭐고, 왜 쓰는지부터 실제 코드 예제까지 차근차근 풀어볼게요.

초보자도 이해할 수 있도록! 그럼 바로 시작해볼까요? 😄

1. 관계형 데이터베이스와 ORM 기초 📘

1.1 관계형 데이터베이스란 무엇인가요?

웹 애플리케이션에서 가장 기본적이면서도 중요한 요소 중 하나는 데이터 저장입니다.

사용자의 정보, 게시글, 댓글 등은 휘발성 메모리보다 영구 저장이 가능한 데이터베이스에 보관해야 하죠.

그리고 그중에서도 가장 널리 쓰이는 건 관계형 데이터베이스(Relational Database)입니다.

관계형 데이터베이스는 데이터를 표(table)의 형태로 저장하고, 그 안에는 열(컬럼)과 행(레코드)이 존재합니다.

예를 들어 사용자의 정보를 저장할 때는 다음과 같은 테이블이 만들어집니다.

또한 외래 키(Foreign Key)라는 개념을 이용해서 테이블 간 관계를 설정할 수 있어요.

예를 들어

사용자 테이블과 게시글 테이블이 있다면, 게시글 테이블은 작성자의 ID를 외래 키로 저장함으로써 '누가 쓴 글인지'를 연결할 수 있는 겁니다.

1.2 ORM(Object Relational Mapping)이란?

그런데 여러분, SQL 쿼리 직접 작성해보셨나요?

INSERT INTO, SELECT, UPDATE 같은 명령어들 말이죠. 배우는 건 어렵지 않지만, 반복적으로 작성하다 보면 지치기 마련이에요. 😓

특히 Python처럼 객체 지향 언어에서는 SQL보다 객체를 다루는 게 더 자연스럽죠.

그래서 등장한 게 바로 ORM (Object-Relational Mapping)입니다.

ORM은 객체와 데이터베이스를 자동으로 매핑해주는 기술로, 클래스를 정의하고 객체를 조작하면 자동으로 SQL이 실행돼요.

즉, SQL을 거의 몰라도 DB를 다룰 수 있는 거죠.

• Python 코드로 SQL 없이 DB 조작 가능
• 모델 클래스 정의 → 자동으로 테이블 생성
• 쿼리 결과도 객체로 반환되어 사용이 간편함

ORM을 사용하면 생산성은 높이고, 오류는 줄이고 코드의 일관성까지 챙길 수 있어요.

물론 SQL을 완전히 모르고 개발하는 건 위험하지만, 기본 SQL을 익힌 후 ORM을 활용하면 정말 편리합니다. 😎

자, 이제 ORM의 세계를 본격적으로 들어가 볼 시간이에요.

다음 섹션에서는 FastAPI와 함께 사용할 ORM 라이브러리인 SQLAlchemy를 소개해볼게요!

2. SQLAlchemy ORM의 기본 구조 이해하기 🧩

2.1 SQLAlchemy란?

SQLAlchemy는 Python 생태계에서 가장 널리 쓰이는 ORM 도구 중 하나입니다.

단순히 ORM 기능뿐 아니라, SQL 생성기, DB 연결기, 트랜잭션 관리자까지 포괄적으로 포함된 종합 프레임워크죠.

SQLAlchemy는 크게 두 가지 레벨로 나뉘는데요.

하나는 Core (SQL 표현 언어), 다른 하나는 ORM (객체 관계 매핑)입니다.

저희는 이 중 ORM을 활용하여 FastAPI와 연결할 거예요.

2.2 SQLAlchemy ORM의 구조

ORM 방식으로 SQLAlchemy를 사용할 때는 다음과 같은 구성요소들을 기억해 두셔야 해요.

각각의 역할이 명확하게 나뉘어 있어서 한 번 구조를 이해해두면 이후 확장도 쉬워집니다.

위 구성요소들을 바탕으로 SQLAlchemy로 앱을 구축할 수 있어요.

FastAPI와 통합할 때는 이 구조를 기본으로 시작하게 됩니다.

2.3 SQLAlchemy ORM의 동작 흐름

1. Engine 생성: create_engine()로 데이터베이스 연결 설정
2. Session 생성: sessionmaker를 이용해 세션 팩토리 구성
3. Base 선언: declarative_base()로 모델의 부모 클래스 생성
4. 모델 정의: 클래스를 통해 테이블 구조와 컬럼 정의
5. CRUD 작업: 세션을 통해 데이터 생성/조회/수정/삭제 수행

이 흐름을 기억해두면, 이후 FastAPI에서 API 요청 → ORM 처리 → DB 반영 흐름을 구현할 때 큰 도움이 됩니다.

그럼 이제 실제로 FastAPI 프로젝트에 SQLAlchemy를 어떻게 통합하는지 본격적으로 코드를 통해 알아볼까요?

다음 섹션에서는 실습 위주로 하나씩 따라가며 설명드릴게요.

3. FastAPI 프로젝트에 SQLAlchemy 통합 🔗

3.1 SQLite로 로컬 개발 환경 구성하기

FastAPI와 SQLAlchemy를 연동할 때, 처음부터 복잡한 PostgreSQL 같은 DB를 연결하면 진입장벽이 높아질 수 있어요.

그래서 우리는 초보자에게 아주 친숙한 SQLite를 먼저 사용합니다. 설치할 필요도 없고, 파일 하나만 있으면 실행되니까요!

우선 SQLAlchemy 패키지를 설치해요. 터미널에서 아래 명령어를 실행합니다:

pip install sqlalchemy

그 다음, FastAPI 프로젝트 루트 디렉토리에 database.py라는 파일을 만들고

아래처럼 작성해 주세요:

# database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"  # 현재 디렉토리에 app.db 생성
engine = create_engine(
    SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}
)

SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

• create_engine: SQLite 파일로 연결되는 엔진 객체 생성
• sessionmaker: 세션 팩토리. 세션 객체를 생성하여 DB 작업에 사용
• declarative_base: 모든 모델이 상속받는 베이스 클래스 생성

3.2 DB 세션을 위한 의존성 주입 함수 만들기

FastAPI의 핵심 기능 중 하나인 의존성 주입을 활용해서 각 API 요청마다 자동으로 DB 세션을 열고 닫는 구조를 만들 수 있어요.

아래 코드를 database.py 파일 하단에 추가해보세요:

from sqlalchemy.orm import Session
from fastapi import Depends

def get_db():
    db: Session = SessionLocal()
    try:
        yield db
    finally:
        db.close()

이제 FastAPI 라우터 함수에서는 다음처럼 db: Session = Depends(get_db) 형태로 세션을 자동 주입받을 수 있습니다.

아주 편리하죠? 😄

3.3 구조 정리 – 폴더와 파일 구성은 이렇게

SQLAlchemy를 FastAPI 프로젝트에 통합할 때는 구조화가 중요합니다.

아래처럼 파일을 구성하면 확장성과 유지보수에 훨씬 유리해요.

📁 app/
├── main.py
├── database.py        # DB 연결 설정 및 세션 함수
├── models.py          # ORM 모델 클래스 정의
├── schemas.py         # Pydantic 스키마
└── crud.py            # DB CRUD 함수

이제 다음 단계에서는 실제로 모델을 정의하고 테이블을 생성하는 작업을 해볼 거예요.

드디어 DB와 코드가 연결되는 진짜 실습에 돌입합니다!

4. ORM 모델 정의와 테이블 생성 🏗️

4.1 모델 클래스 정의하기

ORM에서 가장 중요한 부분 중 하나는 모델 클래스 정의입니다.

여기서 "모델"은 데이터베이스의 테이블과 매핑되는 Python 클래스를 의미해요.

예를 들어 Todo 리스트를 저장하고 싶다면 Todo 모델을 만들어야겠죠?

이제 models.py 파일을 새로 만들어 아래와 같이 작성해봅시다:

# models.py
from sqlalchemy import Column, Integer, String, Boolean
from .database import Base

class Todo(Base):
    __tablename__ = "todos"
    
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, index=True)
    description = Column(String, nullable=True)
    done = Column(Boolean, default=False)

• __tablename__: 이 모델이 매핑될 실제 DB 테이블 이름
• id: 기본 키. 자동 증가 설정
• title, description: 문자열 컬럼, nullable=True로 NULL 허용
• done: 완료 여부를 나타내는 불리언(Boolean) 컬럼

4.2 테이블 생성 – 코드로 자동화하기

모델 클래스를 정의했으면, 다음은 실제 SQLite DB 파일에 테이블을 생성해야 합니다.

별도로 SQL을 작성하지 않고도 간단히 처리할 수 있어요.

FastAPI 앱의 진입점인 main.py에 아래 코드를 추가해 주세요:

# main.py
from fastapi import FastAPI
from . import models
from .database import engine

models.Base.metadata.create_all(bind=engine)

app = FastAPI()

create_all() 함수는 Base를 상속받은 모든 모델 클래스의 테이블을 데이터베이스에 자동으로 생성해줍니다.

이미 존재하는 테이블은 건너뛰기 때문에 안심하고 실행해도 돼요.

이제 서버를 실행하면, app.db 파일 안에 todos 테이블이 생기고, 우리가 정의한 컬럼들이 포함돼 있을 거예요. SQLite 브라우저를 통해 직접 확인해보는 것도 재미있겠죠? 😉

4.3 한눈에 보는 코드 구성 요약

이제 데이터베이스에 연결하고 테이블까지 만들었으니, 본격적으로 데이터를 넣고 꺼내는 CRUD 엔드포인트를 구현해 볼 차례예요.

다음 단계에서는 FastAPI 라우터와 SQLAlchemy 세션을 연결해 실제 데이터를 다뤄볼 거예요.

5. DB 세션 관리 및 CRUD 구현 🛠️

5.1 DB 세션 주입하기 (Dependency Injection)

FastAPI의 가장 멋진 기능 중 하나는 의존성 주입입니다.

각 API 요청에서 DB 세션을 쉽게 주입받을 수 있고, 요청이 끝나면 자동으로 세션을 닫아줘요. 🤩

앞서 만든 get_db() 함수를 기억하시죠? 이를 FastAPI 라우트 함수에 아래처럼 적용하면 됩니다:

from fastapi import Depends
from sqlalchemy.orm import Session
from .database import get_db

이제 API 핸들러에서 db: Session = Depends(get_db)를 인자로 추가하면 DB 연결이 자동으로 처리됩니다.

5.2 CRUD 기능 구현하기

이제 진짜 핵심인 CRUD 구현을 해볼게요!

예시로 Todo 항목을 데이터베이스에서 생성하고 불러오는 코드부터 시작합니다.

먼저 Pydantic 스키마부터 설정할게요:

# schemas.py
from pydantic import BaseModel

class TodoItemCreate(BaseModel):
    title: str
    description: str | None = None

class TodoItem(BaseModel):
    id: int
    title: str
    description: str | None = None
    done: bool

    class Config:
        orm_mode = True

이제 main.py 또는 router 파일에 API 핸들러를 작성해봅시다.

(1) Todo 생성

@app.post("/todos", response_model=schemas.TodoItem)
def create_todo(item: schemas.TodoItemCreate, db: Session = Depends(get_db)):
    db_todo = models.Todo(title=item.title, description=item.description)
    db.add(db_todo)
    db.commit()
    db.refresh(db_todo)
    return db_todo

(2) Todo 단일 조회

@app.get("/todos/{id}", response_model=schemas.TodoItem)
def read_todo(id: int, db: Session = Depends(get_db)):
    todo = db.query(models.Todo).filter(models.Todo.id == id).first()
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo

(3) Todo 전체 조회

@app.get("/todos", response_model=list[schemas.TodoItem])
def read_all_todos(db: Session = Depends(get_db)):
    return db.query(models.Todo).all()

(4) Todo 상태 업데이트

@app.put("/todos/{id}", response_model=schemas.TodoItem)
def update_done_status(id: int, done: bool, db: Session = Depends(get_db)):
    todo = db.query(models.Todo).filter(models.Todo.id == id).first()
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    todo.done = done
    db.commit()
    db.refresh(todo)
    return todo

(5) Todo 삭제

@app.delete("/todos/{id}", status_code=204)
def delete_todo(id: int, db: Session = Depends(get_db)):
    todo = db.query(models.Todo).filter(models.Todo.id == id).first()
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    db.delete(todo)
    db.commit()

5.3 정리: FastAPI + SQLAlchemy 조합의 강력함

• DB 연결과 세션 관리를 코드 몇 줄로 자동화
• ORM 모델과 Pydantic 스키마를 분리해 가독성과 유지보수 향상
• API와 DB가 자연스럽게 연결되어 생산성 UP

이제 API를 실행해보면 SQLite 파일에 데이터가 저장되고, 브라우저나 API 클라이언트에서 요청을 보내도 데이터가 유지되는 걸 확인할 수 있어요.

이건 정말 개발자에게 기쁨이죠! 🎉

6. 실습 과제: SQLite를 이용한 Todo API 완성 🧪

6.1 실습 목표 정리

이번 섹션에서는 지금까지 배운 내용을 바탕으로 하나의 완성된 Todo API 프로젝트를 직접 만들어보는 게 목표예요. 🚀

FastAPI, SQLAlchemy, SQLite를 연결하여 CRUD 엔드포인트를 직접 구현하고 테스트하는 과정을 통해 백엔드 개발의 핵심을 체감할 수 있습니다.

6.2 실습 내용 정리 – 구현할 기능 목록 ✅

• POST /todos → Todo 항목 생성
• GET /todos → 전체 Todo 목록 조회
• GET /todos/{id} → 특정 Todo 항목 조회
• PUT /todos/{id}?done=true → 완료 상태 업데이트
• DELETE /todos/{id} → Todo 항목 삭제

6.3 테스트 방법 및 점검 포인트 🔍

API는 Swagger UI를 통해 쉽게 테스트할 수 있어요.

http://127.0.0.1:8000/docs 주소를 브라우저에 입력하면, 자동 생성된 문서를 통해 각 요청을 테스트해볼 수 있습니다.

그리고 아래 항목들을 직접 확인해보세요:

• POST 요청 후 실제 app.db 파일에 데이터가 저장되는가?
• 서버를 재시작해도 데이터가 보존되는가?
• 상태코드 (200, 201, 204, 404 등) 가 올바르게 반환되는가?

6.4 실습 마무리 및 다음 단계 안내 🧭

이번 실습을 통해 FastAPI 애플리케이션에 SQLAlchemy를 통합하고, 데이터를 영구 저장하는 진짜 백엔드 앱을 만들 수 있게 되었습니다. 🎉

다음 단계에서는 이 API를 바탕으로 프론트엔드와 연결하거나, 배포 환경을 준비하거나,

다른 DB (예: PostgreSQL)로 전환하는 연습을 해보면 좋겠죠? 😉

마무리🚀

지금까지 우리는 FastAPI와 SQLAlchemy를 활용해 데이터베이스와 연동되는 Todo API를 구축해봤습니다.

단순한 in-memory 데이터 저장 방식에서 벗어나, 이제는 SQLite 파일을 통해 데이터를 영구 저장하고 관리할 수 있는 수준으로 발전했어요. 🧱

ORM을 도입하면서 코드의 구조가 훨씬 깔끔해지고, 유지보수도 쉬워졌다는 걸 직접 체험해보셨을 겁니다.

특히 FastAPI의 의존성 주입과 SQLAlchemy의 강력한 매핑 기능이 얼마나 잘 어우러지는지도 느껴지셨을 거예요.

이제 여러분은 다음 단계로 나아갈 준비가 되었습니다.

PostgreSQL 같은 다른 관계형 DB로 확장하거나, Alembic을 통한 마이그레이션 관리, 혹은 Docker 환경에서의 운영 환경 구축 등 다양한 실전 영역에 도전해보세요!

🎯 오늘 다룬 기술을 응용하면 여러분만의 Todo 웹앱, 게시판, 메모장 등 다양한 백엔드 서비스로 발전시킬 수 있어요.  다음 편에서는 FastAPI와 프론트엔드(예: Streamlit)를 연동하는 방법도 소개할 예정입니다!

파이썬 FastAPI Pydantic을 통한 데이터 모델링과 검증

FastAPI의 진짜 힘은 바로 Pydantic에 있다!
데이터를 자동으로 검증하고, 문서화까지 완벽하게 해주는
이 강력한 조합을 여러분은 알고 계셨나요?

안녕하세요, 여러분!

이번 글에서는 FastAPI에서 가장 자주 사용되는 기능 중 하나인 Pydantic 기반의 데이터 모델링과 검증에 대해 알아보려 합니다.

FastAPI를 처음 접할 땐 간단한 라우팅으로 시작하지만, 실제 프로젝트로 들어가면 사용자 입력 데이터의 유효성을 검증하고 그에 맞는 응답 모델을 처리하는 것이 핵심이 됩니다.

이 모든 과정을 도와주는 것이 바로 Pydantic이죠. 특히 초보 개발자들에게는 서버로 들어오는 요청이 어떤 구조인지, 그 구조가 올바른지 자동으로 확인해주는 기능은 정말 고마운 존재예요.

예외 처리, 직렬화, 문서 자동화까지 한 번에 해결할 수 있으니, 놓칠 수 없겠죠?

1. Pydantic BaseModel 소개와 특징 ✨

FastAPI의 진짜 매력은 어디에 있을까요? 바로 Pydantic을 활용한 자동 데이터 검증 기능에 있습니다.

Python에서 데이터 모델을 정의할 때 많은 분들이 dataclass를 사용해봤을 텐데요, Pydantic은 거기에 한 단계 더 나아가 유효성 검사, 직렬화/역직렬화, 문서화까지 제공해주는 놀라운 도구입니다.

📌 BaseModel이란?

Pydantic의 핵심은 BaseModel입니다.

BaseModel을 상속한 클래스는 구조화된 데이터 모델로서 동작하며, 입력값의 타입을 검증하고, 오류가 있으면 상세한 메시지를 반환합니다.

예를 들어, 사용자의 정보를 받는 모델을 아래처럼 정의할 수 있습니다.

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    is_active: bool = True

• id: 정수형으로 강제
• name: 문자열로 강제
• is_active: 기본값 True로 설정

이 모델에 잘못된 타입이 들어오면 어떻게 될까요?

예를 들어 User(id="abc", name=123, is_active="yes")처럼 잘못된 데이터를 전달하면,

FastAPI는 422 Unprocessable Entity 오류와 함께 자세한 오류 메시지를 응답합니다.

📈 Pydantic의 장점 요약

결론적으로,

Pydantic을 이용하면 데이터 구조 정의와 검증을 한 번에 처리할 수 있어 코드가 깔끔하고 안정적입니다.

초보자부터 숙련 개발자까지 모두에게 사랑받는 이유죠.

2. 데이터 유효성 검증과 오류 처리 🛡️

FastAPI에서 데이터 유효성 검증은 거의 자동으로 이뤄집니다.

Pydantic 모델을 엔드포인트 함수의 인자로 선언만 하면,

JSON 요청 바디를 파싱 → 타입 검증 → 오류 응답까지 단 한 줄의 추가 코드 없이 처리해주죠.

📥 요청 데이터 검증 흐름

1. 클라이언트가 JSON 데이터를 POST로 전송
2. FastAPI가 Pydantic 모델로 데이터 파싱 시도
3. 정의된 필드 타입과 다르면 422 오류 발생
4. 정상 파싱되면 뷰 함수에 모델 인스턴스를 넘겨줌

예를 들어, 사용자 이름을 문자열로 받아야 한다고 가정해봅시다.

그런데 클라이언트가 name: 1234처럼 숫자를 보내면?

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "str type expected",
      "type": "type_error.str"
    }
  ]
}

이처럼 RequestValidationError가 발생하고, FastAPI는 상세한 오류 메시지를 JSON으로 반환합니다.

개발자는 try-catch도 안 써도 되고, 클라이언트는 어떤 필드가 잘못됐는지 명확히 알 수 있죠.

⚙️ Field()를 통한 추가 제약 설정

Pydantic의 Field() 함수를 사용하면,

단순 타입 검증 외에도 문자 길이 제한, 정규표현식 검사, 기본값 설정, 예시 값 등을 지정할 수 있어요.

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, example="홍길동")
    email: str = Field(..., regex=r'^\S+@\S+\.\S+$', example="user@example.com")

• min_length, max_length: 문자열 길이 제약
• regex: 정규표현식으로 포맷 검증
• example: Swagger 문서에 예시로 표시

이렇게 Field를 적극 활용하면 API 입력 조건이 문서화와 동시에 자동 검증되어, 사용자와 개발자 모두에게 큰 도움이 됩니다.

✅ 요약: 검증이 자동이라 행복해요

• FastAPI + Pydantic은 요청을 자동으로 검증하고 오류를 처리한다.
• 별도의 try-except 없이도 잘못된 요청을 막을 수 있다.
• Field()로 더욱 정밀한 제약 조건을 줄 수 있다.

이제 우리는 Pydantic이 단순한 타입 검사 도구가 아니라 API의 품질과 신뢰도를 끌어올려주는 핵심 기술이라는 걸 확실히 알게 되었죠!

3. 요청 바디 모델링 방법 📦

FastAPI에서는 클라이언트로부터 JSON 형식의 데이터를 받을 때 Pydantic 모델을 직접 함수 매개변수에 선언하는 방식으로 간단하게 요청 바디를 처리할 수 있습니다.

이 방식은 특히 입력값이 여러 필드로 구성된 복합 구조일 때 더욱 유용하게 쓰이죠.

📝 모델 정의와 요청 처리 예제

예를 들어 할 일(Todo)을 등록하는 API를 만든다고 해봅시다.

title과 description을 갖는 요청 바디를 받아야 한다면 아래와 같이 모델을 정의할 수 있어요.

from pydantic import BaseModel

class TodoItemCreate(BaseModel):
    title: str
    description: str | None = None  # 선택적 필드

이제 위 모델을 FastAPI 라우터 함수에 인자로 넣으면 됩니다.

FastAPI는 클라이언트의 JSON 요청을 자동으로 파싱하고 item 객체로 만들어줍니다.

@app.post("/todos", status_code=201)
def create_todo(item: TodoItemCreate):
    todo = {"id": len(todos) + 1, "title": item.title, "desc": item.description}
    todos.append(todo)
    return todo

📌 요청 실패 시 자동 오류 처리

만약 클라이언트가 필수 필드인 title을 빠뜨리거나 문자열 대신 숫자를 보낸다면, 함수는 아예 실행되지 않고 FastAPI가 422 Unprocessable Entity 오류를 자동으로 반환합니다.

덕분에 우리는 로직에만 집중할 수 있고, 예외 처리 코드는 거의 필요 없습니다.

🧾 Swagger 문서 자동 반영

놀랍게도, 위처럼 Pydantic 모델을 선언하면 /docs 경로에서 자동 생성되는 Swagger UI 문서에도 입력 필드, 설명, 데이터 타입, 예시 값까지 모두 자동으로 표시됩니다.

즉, 코드를 짜는 것만으로 문서까지 완성되는 셈이죠.

🧠 요청 바디 처리 시 체크포인트

• BaseModel을 상속한 요청 모델을 선언하자
• 요청 본문으로 JSON 데이터가 들어오면 FastAPI가 자동으로 Pydantic 모델로 변환한다
• 모델에 정의된 조건을 만족하지 않으면 함수가 실행되지 않고 오류를 반환한다
• Field()를 이용해 제약조건과 문서 예시를 추가할 수 있다

이처럼 요청 바디에 Pydantic 모델을 사용하면 코드가 훨씬 직관적이고 안전합니다.

특히 프론트엔드와 협업할 때 Swagger 문서 덕분에 API 스펙 공유가 정말 쉬워집니다.

4. 응답 모델 지정과 데이터 직렬화 📤

FastAPI에서는 요청을 받을 때뿐만 아니라 응답을 보낼 때도 Pydantic 모델을 활용할 수 있습니다. response_model 파라미터를 사용하면 반환할 데이터의 구조를 명확히 지정할 수 있어요.

이를 통해 보안성, 신뢰성, 문서화까지 한 번에 해결됩니다.

📦 response_model의 기본 개념

API 엔드포인트에서 반환할 데이터가 어떤 구조여야 하는지를 response_model에 정의해두면,

FastAPI는 자동으로 해당 구조로 직렬화(serialization)하고 그 외의 필드는 제외합니다.

예를 들어,

다음과 같은 모델이 있다고 해볼게요.

class TodoItem(BaseModel):
    id: int
    title: str
    description: str | None = None

이제 GET 요청에 대해 이 모델을 응답 모델로 지정하면 다음과 같은 라우팅 코드를 작성할 수 있어요.

@app.get("/todos/{id}", response_model=TodoItem)
def read_todo(id: int):
    todo = get_todo_by_id(id)
    if not todo:
        raise HTTPException(status_code=404, detail="Todo not found")
    return todo

여기서 todo가 dict든 ORM 객체든 상관없이 FastAPI는 TodoItem 모델 형태로 자동 변환해 응답해줍니다.

내부적으로는 dict로 변환 후 JSON으로 직렬화됩니다.

🔒 보안성을 위한 필드 필터링

예를 들어 사용자 정보를 반환할 때 DB에는 hashed_password 같은 민감한 정보가 있을 수 있습니다.

이때 응답 모델에 해당 필드를 포함하지 않으면, FastAPI는 자동으로 해당 필드를 제거하고 안전한 응답만 반환합니다.

🧩 ORM 객체 대응을 위한 orm_mode

SQLAlchemy 같은 ORM을 사용할 경우, 모델 인스턴스를 바로 반환할 수 있는데요.

이때는 응답 모델 내부에 Config 클래스를 선언해 orm_mode = True로 설정해줘야 합니다.

class TodoItem(BaseModel):
    id: int
    title: str
    description: str | None = None

    class Config:
        orm_mode = True

이 설정을 해주면 FastAPI는 ORM 객체에서 필드를 자동으로 추출해서 응답 모델로 직렬화해줍니다.

🧾 response_model이 주는 이점 정리

결론적으로 response_model은 응답을 명시적으로 통제할 수 있는 강력한 기능입니다.

특히 API 문서 자동화와 보안 강화 측면에서 필수로 활용해야 할 요소죠!

5. 인메모리 Todo API 실습 예제 🧪

이제까지 배운 내용을 바탕으로 간단한 Todo API 예제를 만들어보며 실습해볼 시간이에요.

데이터베이스 없이 인메모리 리스트를 사용하여 CRUD 기능을 구현해볼 거예요.

이 과정을 통해 Pydantic 모델을 어떻게 활용하고, FastAPI의 기능과 어떻게 연결되는지 확실히 체감할 수 있습니다.

🔧 모델 정의

from pydantic import BaseModel
from typing import List, Optional

class TodoItemCreate(BaseModel):
    title: str
    description: Optional[str] = None

class TodoItem(TodoItemCreate):
    id: int
    done: bool = False

TodoItemCreate는 생성 요청용, TodoItem은 응답 및 조회용으로 사용됩니다.

생성 시에는 ID와 완료 여부가 없기 때문에 모델을 상속 구조로 나누어 중복을 줄였습니다.

🚀 엔드포인트 구현

from fastapi import FastAPI, HTTPException

app = FastAPI()
todos: List[TodoItem] = []
current_id = 0

@app.post("/todos", response_model=TodoItem, status_code=201)
def create_todo(item: TodoItemCreate):
    global current_id
    current_id += 1
    todo = TodoItem(id=current_id, **item.dict())
    todos.append(todo)
    return todo

@app.get("/todos", response_model=List[TodoItem])
def list_todos():
    return todos

@app.get("/todos/{id}", response_model=TodoItem)
def get_todo(id: int):
    for todo in todos:
        if todo.id == id:
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

@app.put("/todos/{id}", response_model=TodoItem)
def update_todo(id: int, done: bool):
    for todo in todos:
        if todo.id == id:
            todo.done = done
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

@app.delete("/todos/{id}", status_code=204)
def delete_todo(id: int):
    for idx, todo in enumerate(todos):
        if todo.id == id:
            todos.pop(idx)
            return
    raise HTTPException(status_code=404, detail="Todo not found")

📋 기능 요약

이처럼 Pydantic 모델을 중심으로 CRUD API를 설계하면 입력과 출력의 명세가 명확해지고,

자동 문서화 기능까지 덤으로 얻을 수 있습니다.

작은 실습이지만, API 설계의 기본을 익히기에 딱 좋은 구조입니다!

6. 실습을 통한 개념 정리 및 확장 방향 📚

지금까지 FastAPI에서 Pydantic을 활용한 데이터 모델링과 검증에 대해 배우고, 인메모리 Todo API 예제를 통해 실습까지 마쳤습니다.

단순히 동작하는 API를 만들었다는 것 이상의 의미가 있어요.

이번 학습을 통해 우리는 다음과 같은 핵심 역량을 갖추게 되었어요.

🎯 핵심 학습 내용 정리

• Pydantic의 BaseModel을 이용해 데이터 구조를 선언하고, 타입 검증과 기본값 설정까지 깔끔하게 처리하는 법을 익혔어요.
• 요청 바디에 Pydantic 모델을 활용해 JSON을 자동 파싱하고 오류를 422 상태 코드로 처리하는 구조를 경험했죠.
• response_model을 통해 응답 데이터를 명확히 통제하고, 민감 정보를 자동 제거하는 실전 팁도 확인했어요.
• Swagger 문서화에 입력/출력 모델이 자동 반영되는 과정을 통해 개발 생산성을 실감했습니다.

🔮 다음 단계: 확장 방향 제안

이제 실전 프로젝트나 포트폴리오 개발로 확장하고 싶다면, 아래 내용을 고려해보세요.

1. SQLite 또는 PostgreSQL 연동 – 실제 DB와 연동해 Todo를 저장하고 불러오는 구조로 확장하기
2. SQLAlchemy ORM 사용 – ORM 객체와 Pydantic 모델을 함께 사용하는 방법 학습하기
3. JWT 인증 추가 – 사용자 인증/인가 처리로 보안을 강화하기
4. 테스트 코드 작성 – pytest 등을 이용한 유닛 테스트 추가로 품질 보장

🌈 마무리하며

단순히 작동하는 코드보다 더 중요한 건, 데이터의 흐름을 안전하고 명확하게 만드는 것입니다.

Pydantic은 그 시작이자 가장 든든한 동반자예요.

앞으로 여러분의 FastAPI 프로젝트에 이 강력한 도구를 적극 활용해보세요.

마무리 ✍️

이번 글에서는 FastAPI에서 Pydantic을 활용한 데이터 모델링과 검증 방법을 처음부터 끝까지 실습 중심으로 정리해봤습니다.

처음 접할 땐 어렵게 느껴질 수 있지만, 막상 하나하나 따라 하다 보면 자동 유효성 검사, 직렬화, 문서화 등 정말 많은 일을 FastAPI가 알아서 해주는 걸 느끼게 될 거예요.

여기서 끝나지 않고, 이제는 진짜 서비스에 연결할 준비를 해보세요.

SQLite, PostgreSQL 같은 실제 데이터베이스 연동부터, JWT 인증 구현, SQLAlchemy ORM 적용, 서비스 배포 등 단계별로 확장할 수 있습니다.

중요한 건, 이 모든 기반에는 Pydantic 모델링이 있다는 점이에요.

혹시 오늘 처음 FastAPI를 써보신 분이라면, 분명 놀라셨을 거예요.

어떻게 이렇게 적은 코드로 API가 만들어지고, 검증까지 되는지.

앞으로는 더 다양한 프로젝트에서 Pydantic을 능숙하게 다루실 수 있을 겁니다. 👍

이제 여러분의 프로젝트에서 Pydantic을 자신 있게 활용해보세요.

복잡한 데이터 구조도 깔끔하게, 예외 처리도 자동으로, API 문서화까지 한 번에! 😎

파이썬 FastAPI 요청 처리 심화 – 경로와 쿼리 매개변수, 다양한 요청 방식

FastAPI에서의 요청 처리는 단순한 URL 호출을 넘어, 변수, 쿼리, 그리고 다양한 HTTP 메서드로 확장됩니다. 그 핵심을 이번 글에서 파헤쳐볼게요!

안녕하세요, 개발자 여러분 😊

이번 글에서는 FastAPI의 진짜 매력을 느낄 수 있는 "요청 처리 심화" 파트를 다뤄보려 해요.

단순히 /hello 경로만 호출해서 문자열 반환하는 것에 만족하셨다면, 이제 한 단계 더 나아가 보죠.

경로 변수와 쿼리 파라미터, 그리고 다양한 HTTP 메서드를 활용한 CRUD API 설계까지, 여러분이 실전에서 꼭 만나게 될 상황들을 중심으로 소개합니다.

개발자라면 누구나 REST API를 다루게 되는데, FastAPI만큼 직관적이고 깔끔하게 처리할 수 있는 프레임워크는 드물어요.

이 글을 끝까지 따라오시면, 여러분도 FastAPI로 유연하고 강력한 API를 만드는 데 자신감을 가지게 될 거예요!

1. 경로 변수(Path Parameters)의 개념과 활용

FastAPI를 사용하다 보면 경로(URL) 안에 직접 데이터를 넣어서 API 요청을 날리는 경우가 정말 많습니다.

예를 들어

사용자 정보를 조회할 때 /users/10 이런 식으로 요청을 보내곤 하죠.

여기서 10은 경로 변수입니다.

FastAPI에서는 /users/{user_id}와 같이 중괄호({})를 사용해서 경로 변수를 선언할 수 있고, 해당 값은 함수 인자에서 받아올 수 있어요.

여기에 타입 힌트까지 붙이면 더 강력해지죠.

다음 예제를 함께 살펴볼게요.

📌 실습 예제 – 사용자 ID로 조회하기

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

👉 예를 들어 http://127.0.0.1:8000/users/7에 요청하면, {"user_id": 7} 이 응답됩니다!

🎯 경로 변수의 특징 정리

• URL 경로 내에 값을 직접 삽입할 수 있다.
• user_id: int처럼 타입 지정 가능 → FastAPI가 자동으로 검증
• 잘못된 타입 요청 시 자동으로 422 오류 반환됨

📎 참고 팁

FastAPI는 Pydantic의 Path() 함수를 활용해 경로 변수에 대해 더 정교한 검증을 할 수 있도록 지원해요.

예를 들어,

최소값, 최대값을 설정하거나 설명을 추가할 수 있답니다.

이건 나중에 심화로 다룰 테니 일단 기본 개념만 확실히 익혀둬요!

✅ 요약 정리

1. {변수명}으로 경로에 변수 삽입 가능
2. 타입 힌트 사용 시 자동 변환 및 검증 처리
3. 잘못된 타입 전달 시 422 Unprocessable Entity 오류

2. 쿼리 파라미터(Query Parameters)의 처리와 기본값 설정

FastAPI에서는 경로 이외에도 쿼리 파라미터를 아주 쉽게 처리할 수 있어요.

우리가 웹사이트에서 흔히 보는 ?page=1&size=10 같은 주소 기억나시죠?

이런 식의 URL에서 page나 size 같은 값들을 FastAPI는 아주 자연스럽게 함수 인자로 넘겨줍니다.

FastAPI는 함수에 정의된 매개변수가 경로 변수와 일치하지 않으면 자동으로 쿼리 문자열로 간주해서 값을 찾아요.

즉, /items?skip=5&limit=20 요청은 아래 함수로 처리할 수 있습니다.

🔍 실습 예제 – 아이템 페이징 처리

@app.get("/items")
def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

🔗 http://127.0.0.1:8000/items?skip=5&limit=20로 접속해보세요!

결과는 {"skip": 5, "limit": 20}으로 출력될 거예요.

⚙️ 기본값과 선택적 파라미터

매개변수에 = 기본값을 지정하면, 그 값은 선택적 파라미터가 됩니다.

예를 들어

위의 skip: int = 0은 값을 주지 않아도 기본적으로 0으로 설정돼요.

그래서 /items만 호출해도 오류 없이 작동합니다.

🎯 쿼리 파라미터의 활용 예

• 게시글 목록 조회 시 페이징 처리 (page, size)
• 상품 검색 시 필터링 옵션 전달 (keyword, category 등)

📎 고급 활용 – Query 함수로 유효성 검증

FastAPI는 Query()라는 유틸리티를 제공해요.

이걸 쓰면 최소값, 최대값, 정규식 검증 등 다양한 제약 조건을 설정할 수 있어요.

예를 들어:

from fastapi import Query

@app.get("/search")
def search_items(q: str = Query(..., min_length=3, max_length=50)):
    return {"query": q}

▶️ 이처럼 Query를 활용하면 검색어가 최소 3자 이상, 50자 이하일 때만 유효하게 동작하게 만들 수 있어요!

✅ 요약 정리

1. 경로에 포함되지 않은 인자는 자동으로 쿼리 파라미터로 처리
2. 기본값을 지정해 선택적 파라미터 구현 가능
3. Query()를 통해 유효성 검사와 문서화 가능

3. 다양한 HTTP 메서드로 API 설계하기

웹 개발을 하다 보면 단순한 데이터 조회(GET) 외에도, 데이터를 생성, 수정, 삭제하는 다양한 작업이 필요하죠.

이럴 때 사용하는 것이 바로 HTTP 메서드입니다.

FastAPI는 @app.post(), @app.put(), @app.delete() 같은 데코레이터로 쉽게 메서드를 구분해 구현할 수 있어요.

보통 REST API에서 CRUD 작업은 다음과 같은 매핑으로 이루어져요:

• POST – 자원 생성(Create)
• GET – 자원 조회(Read)
• PUT / PATCH – 자원 수정(Update)
• DELETE – 자원 삭제(Delete)

🛠 실습 예제 – Todo 리스트 API

이제 간단한 Todo 리스트 API를 만들어볼게요.

아직 데이터베이스는 연결하지 않고, 메모리 안에 리스트로 관리할 거예요.

from typing import List

todos: List[str] = []

@app.post("/todos")
def create_todo(item: str):
    todos.append(item)
    return {"msg": "Todo created", "item": item}

@app.get("/todos")
def read_todos():
    return {"todos": todos}

@app.delete("/todos/{index}")
def delete_todo(index: int):
    if 0 <= index < len(todos):
        removed = todos.pop(index)
        return {"msg": "Todo deleted", "item": removed}
    else:
        return {"msg": "Index out of range", "index": index}

📌 포인트 정리

• POST 요청으로 할 일(item)을 생성할 수 있어요.
• GET 요청으로 현재 저장된 모든 할 일들을 조회할 수 있어요.
• DELETE 요청으로 특정 인덱스의 할 일을 삭제할 수 있어요.

✨ 추후에는 item을 문자열 대신 JSON 구조로 받고, 유효성 검사도 추가할 예정입니다.

      지금은 기본 동작 원리를 익히는 게 목표예요!

4. 간단한 Todo 리스트 API 실습

이번에는 앞서 배운 내용을 바탕으로 아주 간단한 Todo API를 하나씩 구현해볼 거예요.

복잡한 데이터베이스는 사용하지 않고, 우선 파이썬 리스트에 데이터를 저장하면서 개념과 흐름을 익히는 데 집중해봅시다.

📝 기능 목록

• POST – 새로운 Todo 항목 추가
• GET – 전체 Todo 항목 조회
• DELETE – 특정 항목 삭제

이 Todo API는 FastAPI의 기본 기능만으로도 손쉽게 만들 수 있어요.

아래는 전체 구현 코드입니다.

from typing import List
from fastapi import FastAPI

app = FastAPI()
todos: List[str] = []

@app.post("/todos")
def create_todo(item: str):
    todos.append(item)
    return {"msg": "Todo created", "item": item}

@app.get("/todos")
def read_todos():
    return {"todos": todos}

@app.delete("/todos/{index}")
def delete_todo(index: int):
    if 0 <= index < len(todos):
        removed = todos.pop(index)
        return {"msg": "Todo deleted", "item": removed}
    else:
        return {"msg": "Index out of range", "index": index}

💡 테스트 방법

1. 터미널에서 uvicorn main:app --reload로 실행
2. http://127.0.0.1:8000/docs로 접속
3. Swagger UI에서 API 직접 테스트

📎 실전 팁

현재는 문자열 하나만 다루고 있지만, 보통은 title, description, due_date 같은 구조화된 데이터를 다루게 돼요.

그래서 다음에는 Pydantic 모델을 이용한 JSON 구조 요청 처리도 이어서 다뤄볼 거예요.

🛠 지금은 구조보다 흐름과 메서드별 동작 방식을 이해하는 게 포인트입니다!

5. 응답 코드 설정과 HTTPException 사용법

API를 개발하다 보면 어떤 작업이 성공했는지, 실패했는지 클라이언트에게 명확한 상태 코드로 알려주는 게 매우 중요해요.

FastAPI에서는 status_code 파라미터나 HTTPException 클래스를 이용해서 간단하게 응답 상태를 설정할 수 있습니다.

🔢 status_code 파라미터

기본적으로 FastAPI는 정상 응답 시 200 OK 상태 코드를 반환하지만, POST 요청에서 자원이 성공적으로 생성됐다는 의미로는 201 Created를 사용하는 것이 더 적절해요.

from fastapi import FastAPI

app = FastAPI()

@app.post("/todos", status_code=201)
def create_todo(item: str):
    return {"msg": "Todo created", "item": item}

📍 위처럼 status_code=201을 명시하면 Swagger 문서(/docs)에서도 명확히 표현되고, 실제 응답 헤더에도 적용돼요.

🚨 HTTPException으로 에러 처리하기

클라이언트가 잘못된 요청을 보냈을 때, 그냥 텍스트로 알려주는 대신 HTTPException을 활용하면 더 표준적인 방식으로 에러를 응답할 수 있어요.

FastAPI는 이 기능을 아주 깔끔하게 지원합니다.

from fastapi import HTTPException

@app.delete("/todos/{index}")
def delete_todo(index: int):
    if 0 <= index < len(todos):
        removed = todos.pop(index)
        return {"msg": "Todo deleted", "item": removed}
    else:
        raise HTTPException(status_code=404, detail="Todo index out of range")

❗ 이렇게 하면 404 Not Found 상태 코드와 함께 에러 메시지가 JSON 형태로 전달됩니다.

🧾 예시 응답 구조

{
  "detail": "Todo index out of range"
}

✅ 요약 정리

1. status_code 파라미터로 성공 응답 상태 지정 가능 (예: 201)
2. 에러 상황에는 HTTPException을 활용해 상태 코드 + 상세 메시지 전달
3. Swagger 문서에 자동으로 반영되어 테스트가 쉬움

🧠 상태 코드와 예외 처리는 API 설계에서 신뢰도를 높이는 핵심 요소예요.

      놓치지 말고 꼭 적용해보세요!

6. 자동 문서화 /docs로 확인하는 API 인터페이스

FastAPI를 처음 접했을 때 가장 감탄했던 기능 중 하나가 자동 API 문서화였어요.

우리가 별도로 Swagger를 설정하지 않아도, FastAPI는 프로젝트를 실행하면 /docs 경로에 멋진 UI를 제공해줍니다.

이 문서화 기능은 Swagger UI를 기반으로 하고 있으며, OpenAPI 스펙을 따르기 때문에 API를 설계, 테스트, 설명하는 데 매우 유용합니다.

📘 /docs에서 확인할 수 있는 정보들

• 등록된 모든 API 경로 (GET, POST, DELETE 등)
• 각 API가 사용하는 요청 파라미터와 타입
• 응답 형식 및 예시 JSON
• 상태 코드 정보 및 설명

📌 테스트도 직접 가능!

Swagger UI의 진짜 매력은 단순 문서화가 아니라 인터랙티브한 테스트 기능입니다.

각 API 아래에 있는 "Try it out" 버튼을 누르면, 실제로 파라미터를 입력해보고 바로 응답 결과를 확인할 수 있어요.

🧪 서버를 켜둔 상태에서 http://127.0.0.1:8000/docs 로 접속하면 지금까지 만든 Todo API를 바로 테스트할 수 있습니다!

📄 응답과 상태 코드 자동 문서화

우리가 status_code나 HTTPException을 지정해 놓으면 그 정보 또한 Swagger UI에 자동으로 반영돼요.

예를 들어

Todo 삭제 API에서 404 에러가 발생할 수 있다고 하면, 이 상황도 문서 상에 함께 노출돼서 클라이언트 개발자도 명확히 이해할 수 있습니다.

✅ 요약 정리

1. FastAPI는 기본적으로 Swagger UI 기반의 문서 제공
2. 각 API의 경로, 메서드, 파라미터, 응답을 자동 문서화
3. /docs 페이지에서 직접 테스트 가능

🚀 자동 문서화 기능은 FastAPI의 가장 큰 장점 중 하나입니다.

      실무에서는 팀원들과 협업하거나 외부 개발자에게 API를 설명할 때 이 기능이 정말 유용하게 쓰이죠.

마무리

여기까지 따라오셨다면 FastAPI의 요청 처리 방식에 대해 꽤나 깊이 있게 이해하셨을 거예요.

단순한 라우팅을 넘어, 경로 변수와 쿼리 파라미터를 어떻게 활용할 수 있는지, 그리고 다양한 HTTP 메서드와 응답 코드 설정, 예외 처리, 자동 문서화까지…

이 모든 요소들이 잘 어우러져야 실용적이고 유지보수하기 쉬운 API를 만들 수 있습니다.

FastAPI는 배우기도 쉽고, 작성한 코드가 곧 문서가 되어주기 때문에 백엔드 API를 처음 만드는 분들에게도 정말 좋은 선택이에요.

다음 단계에서는 Pydantic 모델을 활용한 본문(JSON) 처리와 입력 검증에 대해 다룰 예정입니다.

점점 더 실무에 가까운 내용으로 나아가니, 기대해 주세요!

📌 오늘 배운 내용은 실제 웹 서비스,

      예를 들어 블로그 API나 게시판 API처럼 사용자와 데이터를 주고받는 시스템의 기본이 되는 부분입니다.

      꼭 복습하시고, 실습도 꼭 해보세요!

FastAPI로 배우는 REST API 개발 입문

REST API, 아직도 어렵게 느껴지시나요?
FastAPI를 이용하면 믿을 수 없을 만큼 쉽게 웹 API를 만들 수 있어요!

안녕하세요!

오늘부터 여러분과 함께 Python의 강력한 웹 프레임워크 FastAPI를 활용한 REST API 개발을 단계별로 배워보려고 합니다.

요즘 웹 개발에 있어서 REST API는 기본 중의 기본이죠.

다양한 시스템이 서로 데이터를 주고받기 위해 가장 많이 사용되는 방식입니다.

특히 FastAPI는 빠르고 간편하며, 자동 문서화 기능까지 갖춰져 있어 초보자도 쉽게 API를 개발할 수 있는 환상적인 도구예요.

이 블로그 시리즈에서는 REST API의 개념부터 시작해서, FastAPI 설치, Hello World 예제, 엔드포인트 추가 실습까지 하나하나 직접 구현해보며 개념과 실습을 모두 챙길 거예요.

준비되셨나요?

그럼 첫 번째 이야기, REST API와 FastAPI의 만남을 시작해볼게요! 🚀

1. REST API란 무엇인가요? 🌐

REST API는 웹에서 데이터를 주고받는 가장 표준적인 방법 중 하나입니다.

먼저 이름부터 풀어볼까요?

REST는 Representational State Transfer의 약자인데요, 말이 좀 어렵게 느껴질 수 있지만 핵심은 간단합니다.

"웹 자원을 고유한 주소(URI)로 표현하고, 그 자원에 대해 HTTP 메서드를 통해 동작을 지정한다"는 게 핵심이에요.

우리가 평소에 웹 브라우저에서 주소창에 https://example.com/users를 입력하면 "users"라는 자원(데이터 목록)에 접근하는 거잖아요?

이처럼 REST에서는 각각의 자원을 URL을 통해 표현합니다.

그리고 어떤 동작을 하고 싶은지에 따라 GET, POST, PUT, DELETE 같은 HTTP 메서드를 사용해 요청을 보냅니다.

📌 REST 아키텍처의 6가지 원칙

• 클라이언트-서버 구조 : UI와 데이터 처리를 분리해 독립적으로 발전 가능
• 무상태성 (Stateless) : 서버는 요청을 받을 때 클라이언트의 상태를 기억하지 않음
• 캐시 처리 가능 : 클라이언트는 서버 응답을 캐싱해 효율성 향상 가능
• 계층화된 시스템 : 중간 서버를 통해 보안, 로드 밸런싱 등 기능 분리
• 인터페이스 일관성 : URI 설계와 메서드 사용이 일관되게 유지되어야 함
• 코드 온 디맨드(Optional) : 서버에서 클라이언트로 스크립트 등을 전달 가능

🧩 RESTful API 설계의 예시

이러한 설계 방식 덕분에 RESTful API는 명확하고 예측 가능하며 유지보수가 쉬운 구조를 가질 수 있어요.

그래서 요즘 거의 모든 서비스가 REST API 기반으로 구성되고 있죠.

그리고 이걸 Python으로 정말 쉽게 만들 수 있도록 도와주는 도구가 바로 FastAPI입니다.

2. RESTful API의 구조와 특징 🔍

RESTful API는 단순히 REST 원칙을 따르는 API 이상을 의미해요.

클라이언트와 서버 간의 소통을 효율적이고 일관되게 만들어주는 아키텍처 스타일이자 규칙의 집합이죠.

흔히들 “REST스럽다”는 표현을 쓰는데, 이는 API가 REST의 원칙을 잘 따르고 있다는 의미예요.

✅ RESTful API의 구조적 특징

1. URI를 통한 자원 표현 – 모든 자원은 고유한 URI로 식별됩니다. 예: /users, /posts/1
2. HTTP 메서드의 의미 명확화 – CRUD 작업을 각각 GET, POST, PUT, DELETE로 매핑합니다.
3. 무상태성(Stateless) – 요청은 독립적으로 처리되며, 서버는 이전 요청 상태를 저장하지 않습니다.
4. 표현(Representation)의 활용 – 클라이언트는 자원의 ‘표현’을 받으며, 보통은 JSON이나 XML 형식을 사용합니다.
5. 표준 HTTP 상태 코드 사용 – 예: 200(성공), 201(생성됨), 404(없음), 500(서버 오류)

💡 RESTful API가 주는 이점

RESTful API를 설계하면 얻게 되는 이점도 많아요.

가장 큰 장점은 바로 일관성과 가독성입니다.

예를 들어,

다음처럼 URI를 설계한다면 처음 보는 사람도 어떤 기능인지 대충 감이 올 거예요.

• GET /articles – 전체 글 목록 불러오기
• POST /articles – 새 글 작성
• GET /articles/3 – ID가 3인 글 조회

이처럼 RESTful한 API는 예측 가능하고 규칙 기반이기 때문에 협업 시에도 소통이 쉬워지고, 문서화를 따로 하지 않아도 사용할 수 있을 만큼 직관적인 경우도 많습니다.

❗REST API vs RESTful API – 혼동하지 마세요

간혹 REST API와 RESTful API를 같은 개념으로 쓰기도 하지만, 기술적으로는 살짝 차이가 있어요.

REST API는 단지 REST 기반 구조를 사용하는 API를 의미하고, RESTful API는 REST의 원칙을 충실히 따르는 ‘REST다운’ API를 말합니다.

즉, RESTful API는 REST API보다 좀 더 엄격한 규칙을 따른다는 뜻이에요.

RESTful한 구조를 유지하기 위해서는 불필요한 동사 사용을 피하고, 자원 중심으로 URI를 설계하며, HTTP 상태 코드도 적절히 활용해야 해요.

이런 기준을 지켜야만 “RESTful하다”고 말할 수 있답니다!

이제 RESTful API의 기본 철학과 구조에 대해 어느 정도 감이 오셨죠? 😉

다음 섹션에서는 FastAPI라는 도구를 통해 이런 RESTful API를 실제로 구현하는 방법을 배워볼 거예요.

기대되시죠?

3. FastAPI 프레임워크 소개 🚀

FastAPI는 최근 Python 웹 개발자들 사이에서 가장 주목받고 있는 비동기 기반 웹 프레임워크입니다.

Flask나 Django처럼 웹 애플리케이션을 만들 수 있으면서도,

비동기 처리, 자동 문서화, 타입 기반 유효성 검사 같은 최신 기능들을 기본으로 제공합니다.

📌 FastAPI의 핵심 특징

• 빠른 성능 – Starlette(ASGI 서버) 기반으로 구성되어 Node.js나 Go와 맞먹는 수준의 퍼포먼스를 자랑합니다.
• 타입 기반 유효성 검사 – Python의 타입 힌트를 활용해 Pydantic이 자동으로 데이터 검증 및 스키마 생성을 해줍니다.
• 자동 문서화 – OpenAPI(Swagger)와 ReDoc 기반 문서가 자동 생성되어 /docs나 /redoc 경로에서 API 테스트도 가능합니다.
• 비동기 처리 지원 – async/await 문법으로 고성능 API 서버 구현도 손쉽게 가능합니다.

⚙️ 왜 FastAPI인가요?

처음에는 Flask로도 충분하지 않나? 하는 생각이 들 수도 있어요. 저도 그랬거든요.

하지만 FastAPI를 사용해보면 정말 많은 차이를 느낄 수 있습니다.

특히 Swagger 문서 자동 생성과 비동기 처리 성능은 다른 프레임워크들이 따라오기 어려울 정도예요.

여기에 Python의 타입 힌트를 적극적으로 활용해, 코드 작성과 동시에 문서화와 유효성 검사를 자동으로 처리해주는 점이 초보자들에게도 큰 장점으로 작용합니다.

결론적으로 FastAPI는 빠르게 프로토타입을 만들고, 동시에 안정성과 문서화까지 챙기고 싶은 개발자에게 최적의 선택이에요.

Python을 이미 알고 있다면, FastAPI는 자연스럽고 직관적으로 배울 수 있습니다.

다음 글에서는 실제로 FastAPI를 설치하고 기본 개발 환경을 세팅하는 과정을 차근차근 안내해드릴게요.

이제 실습을 통해 본격적으로 시작해볼까요? 🔧

4. 개발 환경 설정과 FastAPI 설치 ⚙️

지금부터는 본격적으로 FastAPI를 개발 환경에 설치해보는 시간입니다.

FastAPI는 Python 3.7 이상에서 사용할 수 있기 때문에, 우선 Python 버전 확인부터 해볼게요.

그리고 가상환경을 만들어서 프로젝트별 의존성을 관리하는 것이 좋습니다.

🔍 Python 및 가상환경 설정

1. Python 버전 확인: python --version
2. 가상환경 생성: python -m venv venv
3. 가상환경 활성화
   • Windows: venv\Scripts\activate
   • Mac/Linux: source venv/bin/activate

가상환경이 활성화되면 프롬프트 앞에 (venv)가 붙어요.

이제 여기서 필요한 라이브러리를 설치하면 됩니다.

📦 FastAPI와 Uvicorn 설치

FastAPI는 자체적으로 웹 서버를 포함하고 있지 않기 때문에 ASGI 서버가 필요해요.

대부분의 개발자들은 Uvicorn을 사용합니다.

pip install fastapi
pip install "uvicorn[standard]"

[standard] 옵션을 포함하면 HTTP/2, WebSocket 등 다양한 기능도 함께 설치돼요.

설치가 끝나면 FastAPI 애플리케이션을 실행할 준비가 완료된 셈입니다.

📝 프로젝트 구조와 첫 파일 만들기

간단한 FastAPI 프로젝트 구조는 다음과 같아요:

• main.py – 앱 실행 파일
• venv/ – 가상환경 폴더

main.py 파일을 열고 FastAPI 기본 코드를 작성할 준비를 합니다.

다음 단계에서는 “Hello, FastAPI”라는 응답을 반환하는 아주 간단한 예제를 통해 첫 API를 직접 만들어볼 거예요.

지금까지 잘 따라오셨나요? 🧑‍💻

환경 설정만 마쳐도 절반은 완성된 셈입니다!

이제 직접 서버를 띄워보며 FastAPI가 어떻게 동작하는지 살펴보겠습니다.

5. Hello FastAPI - 첫 API 만들기 👋

드디어 우리가 기다리던 순간!

이제 FastAPI를 직접 실행해 보며 첫 번째 API를 만들어볼 거예요.

처음 만드는 만큼 아주 단순한 "Hello, FastAPI" 메시지를 반환하는 예제부터 시작해 보겠습니다.

📄 main.py 코드 작성

이제 main.py 파일을 열고

아래와 같이 코드를 작성해 주세요:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
  return {"message": "Hello, FastAPI"}

이 코드에서 @app.get("/")는 루트 경로(/)에 GET 요청이 들어왔을 때 실행되는 함수입니다.

return 부분에서 반환하는 딕셔너리는 자동으로 JSON으로 변환돼서 응답으로 전송돼요.

🚀 서버 실행

이제 작성한 FastAPI 앱을 실행해볼게요.

터미널에 다음 명령어를 입력하세요:

uvicorn main:app --reload

main은 파일 이름, app은 FastAPI 객체입니다.

--reload 옵션을 붙이면 코드 변경 시 서버가 자동으로 재시작돼서 개발할 때 아주 편리하죠!

🔎 실행 결과 확인하기

• http://127.0.0.1:8000/ → {"message": "Hello, FastAPI"} 응답 확인
• http://127.0.0.1:8000/docs → Swagger 기반 API 문서 자동 생성
• http://127.0.0.1:8000/redoc → ReDoc 기반 문서 보기

정말 신기하지 않나요?

별도의 설정 없이도 이렇게 깔끔한 API 문서가 자동 생성됩니다. 🧙‍♂️

그리고 이게 FastAPI의 가장 큰 매력 중 하나예요. 작성한 API들을 테스트도 가능하니, 개발과 동시에 검증까지 가능하죠.

이제 FastAPI의 기본 구조와 실행 흐름을 이해하셨을 거예요.

다음 단계에서는 실제로 또 하나의 엔드포인트를 추가하면서 다양한 HTTP 메서드와 라우팅 개념도 함께 살펴보겠습니다.

6. 엔드포인트 추가 실습: 버전 정보 API 구현 🛠️

이전 단계에서 GET /으로 기본 응답을 반환하는 간단한 API를 만들어봤죠.

이번에는 FastAPI 앱에 새로운 엔드포인트를 하나 더 추가해보겠습니다.

예를 들어,

프로젝트의 버전 정보를 클라이언트에게 알려주는 API가 있다고 가정해볼게요.

📄 main.py에 엔드포인트 추가

@app.get("/version")
def get_version():
  return {"version": "0.1.0"}

이 함수는 /version 경로에 GET 요청이 들어왔을 때 버전 정보를 JSON 형식으로 반환합니다.

예를 들어,

클라이언트가 API의 버전 관리를 하고자 할 때 유용하게 사용할 수 있어요.

🔎 실행 후 테스트하기

• http://127.0.0.1:8000/version 에 접속하면 결과가 다음과 같이 나옵니다:
  {"version": "0.1.0"}
• Swagger UI 문서에서도 /version 경로가 자동으로 추가된 걸 확인할 수 있어요.

📌 엔드포인트를 추가하면서 익히는 FastAPI의 핵심

• 라우팅 – 경로(URL)마다 함수 하나씩 대응시켜 구조적으로 관리
• 함수 기반 뷰(View) – 각각의 엔드포인트는 Python 함수로 표현
• 자동 문서화 – 개발자가 문서를 별도로 작성하지 않아도 FastAPI가 Swagger 문서를 자동 생성

이번 실습을 통해 RESTful API의 핵심인 라우팅 설계를 직접 해보셨고, FastAPI가 얼마나 직관적이고 강력한지 직접 체험하셨을 거예요. 엔드포인트 추가는 이제 식은 죽 먹기죠?

점점 실전 API에 가까워지고 있죠? 😊

지금까지 우리는 REST API의 개념부터 FastAPI 설치, 기본 예제 구현까지 한 걸음씩 따라와 봤습니다.

처음에는 다소 낯설 수 있었던 REST 구조도, FastAPI의 직관적인 문법과 자동 문서화 덕분에 훨씬 더 쉽게 접근할 수 있었죠.

RESTful한 방식으로 API를 설계하면,

확장성과 유지보수성을 동시에 확보할 수 있다는 점에서 그 가치가 분명합니다.

FastAPI는 여기에 더해 빠른 속도, 간결한 코드, 뛰어난 생산성까지 갖추고 있어 Python 개발자라면 반드시 익혀야 할 도구예요.

다음 글에서는 POST 요청 처리와 입력 데이터 검증을 다룰 예정입니다.

본격적으로 사용자의 입력을 받아 처리하고, Pydantic을 활용한 스키마 기반 검증도 함께 배워볼 거예요.

기대되시죠? 😊

이 글이 도움이 되셨다면 댓글이나 공유도 환영합니다.

앞으로도 쉽고 실용적인 Python 백엔드 개발 이야기, 계속 함께해 주세요!