기획에서 출시까지! FastAPI로 실전 프로젝트 전 과정을 경험한다!

실무 흐름 그대로 따라가며 ‘약속 잡기 웹 서비스’ 만들어 보자.

서비스 개발은 단순한 코드 작성이 아니라, 기획부터 배포까지의 전 과정을 이해하고 경험하는 일이다. 이 책은 ‘약속 잡기 웹 서비스’를 직접 만들며 FastAPI를 활용한 실전 개발 흐름을 하나하나 따라간다. 서비스의 요구사항 정의부터 시작해, 테스트 주도 개발(TDD) 방식으로 백엔드를 구현하고, 미리 구현해둔 프런트엔드와의 연동, 구글 캘린더 같은 외부 서비스 통합도 다룬다. 개발한 서비스는 AWS와 깃허브 액션을 이용해 실제로 배포하고, 도메인 설정과 운영까지 경험할 수 있다. 단순히 FastAPI를 학습하는 것에 그치지 않고, 진짜 서비스를 만들며 배우는 실전형 개발 가이드로, 초보자를 위한 설명뿐만 아니라 실무 경험자에게 필요한 배포/운영까지 충실히 담았다.

[목 차]
  

1장 우리가 만들 프로젝트와 도구 이해

1.1 프로젝트를 만들고 운영해야 하는 이유 

__1.1.1 포트폴리오 목적으로 프로젝트 만들기 

__1.1.2 학습 목적으로 프로젝트 만들기 

__1.1.3 프로젝트 목표를 출시 후 운영하는 것에 두자! 

1.2 FastAPI를 사용하는 이유

__1.2.1 FastAPI란 

__1.2.2 FastAPI 특징

1.3 우리가 만들 프로젝트의 목표와 계획 

__1.3.1 목표 

__1.3.2 프로젝트 계획 

1.4 약속 잡기 프로젝트에 사용하는 도구 

__1.4.1 개발 도구 

__1.4.2 운영 도구

 

2장 셸 기본 기능 익히기

2.1 셸이란 

__2.1.1 셸 인터페이스의 종류

2.2 경로와 디렉터리 

__2.2.1 경로

__2.2.2 디렉터리  

2.3 파일 다루기

 

3장 실습 환경 준비

3.1 비주얼 스튜디오 코드 설치 

__3.1.1 비주얼 스튜디오 코드 내려받기 

__3.1.2 맥OS에 설치하기 

__3.1.3 윈도우에 설치하기 

3.2 비주얼 스튜디오 코드 화면 구성 

3.3 비주얼 스튜디오 코드 기본 사용법 

__3.3.1 작업 디렉터리 지정하기 

__3.3.2 명령어 팔레트 

__3.3.3 파일 탐색과 상태 표시 

3.4 비주얼 스튜디오 코드 확장 기능 

__3.4.1 확장 기능이란 

__3.4.2 외양 바꾸기 

__3.4.3 파이썬 확장 기능 설치하기 

__3.4.4 셸 사용해 보기

3.5 파이썬 가상 환경 

__3.5.1 파이썬 가상 환경이란 

__3.5.2 가상 환경 다루기 

3.6 FastAPI 설치하고 맛보기

__3.6.1 FastAPI 설치하기 

__3.6.2 패키지 관리자, Poetry 사용하기 

__3.6.3 웹 애플리케이션 서버: Starlette, Uvicorn 

__3.6.4 Hello World

 

4장 약속 잡기 서비스 기획

4.1 약속 잡기 서비스 기능 기획 

__4.1.1 서비스 개요 

4.2 주요 기능 

__4.2.1 캘린더 구현: 원하는 일자 선택하기 

__4.2.2 부킹 생성: 일정 등록하기

__4.2.3 사용자별 캘린더 구분해서 보기 

__4.2.4 구글 캘린더 연동하기 

__4.2.5  소셜 로그인 구현하기 

4.3 사용자 인터페이스 요소 기획 

__4.3.1 기본 화면 

__4.3.2 타임슬롯 영역 

__4.3.3 약속 잡을 정보를 입력하는 화면 

__4.3.4 약속 신청 완료 화면 

__4.3.5 약속 신청할 일자가 없는 경우 

4.4 데이터 설계 

__4.4.1 몇 가지 개념 알고 가기 

__4.4.2 사용자 개체 

__4.4.3 사용자 소셜 계정 개체 

__4.4.4 사용자 캘린더 개체 

__4.4.5 타임슬롯 개체 

__4.4.6 부킹 개체 

__4.4.7 약속 잡기 서비스의 개체 관계 다이어그램으로 그려 보기

 

5장 데이터 모델링

5.1 파이썬에서 데이터베이스를 사용하는 방법: SQLModel 

__5.1.1 SQL과 ORM 

__5.1.2 SQLAlchemy 

__5.1.3 Pydantic 

__5.1.4 SQLModel 

5.2 모델링 

__5.2.1 사용자 개체: User 모델 

__5.2.2 사용자 소셜 계정 개체: OAuthAccount 모델  

__5.2.3 사용자 캘린더 개체: Calendar 모델  

__5.2.4 타임슬롯 개체: TimeSlot 모델 

__5.2.5 부킹 개체: Booking 모델  

5.3 데이터베이스 연결 설정 

__5.3.1 SQLite란 

__5.3.2 SQLAlchemy로 데이터베이스에 연결하는 방법 

__5.3.3 SQLAlchemy로 세션을 생성하는 방법 

__5.3.4 데이터베이스 연결 설정하기 

5.4 Alembic을 사용하여 데이터베이스 마이그레이션 

__5.4.1 Alembic 주요 개념 

__5.4.2 Alembic 설치하고 초기화하기 

__5.4.3 Alembic 설정하기 

__5.4.4 마이그레이션 스크립트 생성하기 

__5.4.5 자동 마이그레이션(autogenerate) 설정해 보기 

__5.4.6 마이그레이션 스크립트 템플릿 사용하기 

__5.4.7 마이그레이션 스크립트 작동 확인하기: 적용 및 되돌리기 

 

6장 코드 테스트

6.1 테스팅 개요 

__6.1.1 테스팅이란 

__6.1.2 테스팅 종류 

__6.1.3 테스트 더블 

__6.1.4 pytest를 사용하여 테스팅하기 

6.2 단위 테스트 실습 

__6.2.1 단위 테스트 실습 

__6.2.2 문서화 테스트 알아보기 

6.3 통합 테스트 실습 

__6.3.1 사용자 정보를 내려받는 API 구현하기 

__6.3.2 테스트 클라이언트로 API 테스트하기 

__6.3.3 데이터베이스에 사용자 생성하고 테스트하기 

6.4 pytest의 픽스처 기능을 사용한 테스팅 

__6.4.1 테스트 코드에 픽스처 사용하기 

__6.4.2 구현 코드에도 세션 의존성 주입하기 

__6.4.3 테스트 클라이언트도 픽스처로 일원화하기

 

7장 회원가입 및 사용자 인증 구현

7.1 회원가입 테스트 코드 작성 

__7.1.1 (1) 모든 입력 항목을 유효한 값으로 입력하면 계정이 생성된다 

__7.1.2 (2) 사용자명이 유효하지 않으면 유효하지 않다는 메시지를 담은 오류를 일으킨다 

__7.1.3 (3) 계정 ID(username)가 중복되면 중복 계정 ID 오류를 일으킨다 

__7.1.4 (4) 이메일 주소가 중복되면 중복 메시지를 담은 오류를 일으킨다 

__7.1.5 (5) 표시명을 입력하지 않으면 무작위 문자열 8글자로 대신한다

7.2 회원가입 API 구현 

__7.2.1 (1) Pydantic으로 Formdata 유효성 검증하기

__7.2.2 (2) signup API에 SignupPayload 스키마 적용하기 

__7.2.3 (3) 응답 결과에는 username, display_name, is_host만 출력하기 

7.3 로그인 구현 

__7.3.1 로그인 구현에 필요한 기술 

__7.3.2 로그인 API 구현하기 

7.4 자기 자신의 정보를 가져오는 API 구현 

__7.4.1 FastAPI의 의존성 주입이란 

__7.4.2 자신의 정보를 가져오는 API 시나리오 

__7.4.3 쿠키에서 인증 토큰을 가져와 인증 검사하기 

__7.4.4 실패하는 테스트 코드로 구현 검증하기 

7.5 FastAPI 캘린더, 계정 설정 페이지 구현 

__7.5.1 계정 정보 변경하기 

__7.5.2 로그아웃 구현하기 

__7.5.3 회원 탈퇴 구현하기

 

8장 사용자별 캘린더 및 예약 관리 구현

8.1 호스트별 캘린더 가져오기 

__8.1.1 사용자 시나리오 

__8.1.2 호스트인 사용자의 username으로 캘린더 정보 가져오기 

__8.1.3 존재하지 않는 사용자의 username으로 캘린더 정보를 가져오려고 하면 404 응답 반환하기 

__8.1.4 호스트가 아닌 사용자의 username으로 캘린더 정보를 가져오려고 하면 404 응답 반환하기 

__8.1.5 host_calendar_detail( )을 API로 테스트하기

8.2 호스트의 캘린더를 생성하고 변경 

__8.2.1  호스트 사용자는 유효한 캘린더 정보를 제출하여 캘린더를 생성할 수 있다 

__8.2.2 캘린더가 있는 상황에서 추가 생성하려고 하면 422 응답 반환하기 

__8.2.3 게스트 사용자가 캘린더를 생성하려고 하면 403 응답 반환하기

__8.2.4 사용자가 변경하는 항목만 변경되고 나머지는 기존 값 유지하기 

8.3 타임슬롯 관리 

__8.3.1 호스트 사용자는 유효한 타임슬롯 정보를 제출하여 타임슬롯을 생성할 수 있다 

__8.3.2 유효하지 않은 타임슬롯 정보로 생성하려고 하면 HTTP 422 응답하기 

__8.3.3 겹치는 시간대가 있다면 HTTP 422 응답하기 

8.4 예약 

__8.4.1 유효한 예약 신청 내용으로 예약 생성을 요청하면 예약 내용을 담아 HTTP 201 응답하기 

__8.4.2 호스트가 아닌 사용자에게 예약을 생성하면 HTTP 404 응답하기 

__8.4.3 없는 시간대에 예약을 생성하면 HTTP 404 응답하기 

8.5 캘린더 예약 가져오기 

__8.5.1 호스트가 자신이 예약받은 내역을 받아 보는 API 구현하기 

__8.5.2 게스트는 호스트의 캘린더 예약 내역을 월 단위로 받는다 

__8.5.3 게스트는 자신의 캘린더 예약 내역을 페이지 단위로 받는다 

__8.5.4 사용자는 특정 예약 내역 데이터를 받는다 

8.6 FastAPI 캘린더, 예약 관리 

__8.6.1 호스트는 자신에게 신청한 부킹에 대해 일자, 타임슬롯을 변경할 수 있다 

__8.6.2 게스트와 호스트는 다른 호스트의 타임슬롯으로 변경할 수 없다 

__8.6.3 게스트는 자신의 부킹에 대해 주제, 설명, 일자, 타임슬롯을 변경할 수 있다 

__8.6.4 여러분을 위한 작은 제안 

8.7 부킹에 참석 상태 정보 다루기 

__8.7.1 부킹 모델에 참석 상태 필드 추가, Enum 자료형 

__8.7.2 데이터베이스 마이그레이션 

__8.7.3 호스트는 자신에게 신청한 부킹의 참석 상태를 변경할 수 있다

8.8 파일 업로드 

__8.8.1 HTTP 파일 업로드하기 

__8.8.2 FastAPI에서 파일 업로드를 처리하는 방식 

__8.8.3 게스트는 자신이 신청한 부킹에 파일을 업로드할 수 있다: 연습하기 

__8.8.4 fastapi-storages 사용하기 

__8.8.5 게스트는 자신이 신청한 부킹에 파일을 업로드할 수 있다: 실제 해 보기 

__8.8.6 업로드 관련 마이그레이션 스크립트 생성하기 

__8.8.7 SQLAlchemy의 Result 객체를 다룰 때 unique( ) 메서드 사용하기

 

9장 운영자 페이지에서 데이터 관리

9.1 운영자 페이지와 SQLAdmin 

__9.1.1 운영자 페이지 

__9.1.2 SQLAdmin이란 

__9.1.3 SQLAdmin 설치와 설정 

9.2 SQLAdmin 기본 활용법 

__9.2.1 메타데이터 

__9.2.2 목록 페이지

__9.2.3 상세 페이지 

__9.2.4 페이지네이션 옵션 

__9.2.5 일반 옵션 

__9.2.6 양식(form) 옵션 

__9.2.7 내보내기 옵션 

__9.2.8 모델 개별 개체 표시 조정하기 

__9.2.9 모델들에 대응하는 어드민 페이지 정의하기 

9.3 메서드 오버라이딩을 활용하여 기능 확장 및 변경 

__9.3.1  on_model_change(self, data: dict, model: Any, is_created: bool, request: Request) 

__9.3.2 insert_model(self, request: Request, data: dict)

__9.3.3 update_model(self, request: Request, pk: str, data: dict) 

__9.3.4  after_model_change(self, data: dict, model: Any, is_created: bool, request: Request) 

__9.3.5 User 모델에 status 모델 필드 추가하기 

__9.3.6 on_model_delete(self, model: Any, request: Request)

__9.3.7  after_model_delete(self, model: Any, request: Request) 

__9.3.8 delete_model(self, request: Request, pk: Any) 

__9.3.9 scaffold_form( ) 

__9.3.10 list_query(self, request: Request)

__9.3.11 hybrid_property와 expression

__9.3.12 search_query(self, stmt: Select, term: str) 

9.4 SQLAdmin 사용자 인증 체계 

__9.4.1 인증 백엔드 구현하기 

__9.4.2 인증 백엔드 적용하기

 

10장 약속 잡기 프로젝트에 프런트엔드 연동

10.1 정적 파일 

__10.1.1 웹 서버와 웹 애플리케이션 서버 

__10.1.2 FastAPI에서 정적 파일 처리 

10.2 구현된 결과물을 파이썬 웹 서버로 구동 

10.3 CORS 처리 

10.4 호스트 목록 API 

10.5 인증 토큰이 없는 경우에 대한 명확한 응답

__10.5.1 인증 토큰이 없는 경우 대응하기 

__10.5.2 SQLAdmin에도 명확한 인증 예외 오류 처리하기

10.6 캘린더 흐름 

__10.6.1 호스트 목록 

__10.6.2 캘린더 표시 

__10.6.3 부킹 생성 

__10.6.4 게스트의 부킹 내역 

__10.6.5 부킹 상세 보기 

10.7 웹 프런트엔드 개발 명세 

__10.7.1 사용하는 기술 스택 

__10.7.2 디렉터리 구조 

__10.7.3 개발 환경 구성

 

11장 SQLAlchemy 지연 로딩 전략

11.1 지연 로딩이란

11.2 지연 로딩의 종류 

__11.2.1 즉시 로딩 

__11.2.2 지연 로딩 

__11.2.3 지연 로딩 안 함(no load)

__11.2.4 차이점 

__11.2.5 유의점 

11.3 SQLAlchemy 지연 로딩 적용 

__11.3.1 (1) User 모델에 지연 로딩 적용하기 

__11.3.2 (2) OAuthAccount 모델에 지연 로딩 적용하기

__11.3.3 (3) Calendar 모델에 지연 로딩 적용하기 

__11.3.4 (4) TimeSlot 모델에 지연 로딩 적용하기  

__11.3.5 (5) Booking 모델에 지연 로딩 적용하기 

__11.3.6 (6) BookingFile 모델에 지연 로딩 적용하기

 

12장 구글 캘린더 연동

12.1 구글 클라우드 API 

__12.1.1 구글 클라우드 API란 

__12.1.2 구글 클라우드 API의 주요 요소와 개념 

__12.1.3 구글 클라우드 콘솔 준비

__12.1.4 캘린더 공유 및 권한 부여하기 

12.2 구글 캘린더에 이벤트 생성 

__12.2.1 구글 클라우드 API 파이썬 클라이언트 설치하기 

__12.2.2 구글 캘린더 서비스 정의 

__12.2.3 일정(이벤트) 생성하기 

__12.2.4 테스트 구현하기

__12.2.5 스키마 정의하기 

12.3 구글 캘린더의 이벤트 관리 

__12.3.1 테스트 픽스처 정의하기 

__12.3.2 일정 삭제하기 

__12.3.3 특정 일정 가져오기 

__12.3.4 일정 수정하기 

__12.3.5 일정 목록 가져오기 

12.4 약속 잡기 구현체에 구글 캘린더 연동 적용 

__12.4.1 구글 캘린더 서비스 의존성 정의하기

__12.4.2 부킹을 생성할 때 구글 캘린더에 등록하기 

__12.4.3 부킹을 변경할 때 구글 캘린더에 반영하기

__12.4.4 호스트 부킹 목록에서 구글 캘린더 일정 반영하기 

12.5 FastAPI 백그라운드 작업 

__12.5.1 BackgroundTasks 

__12.5.2 StreamResponse

 

13장 오류 기록과 관찰, 관리

13.1 오류 로그 체계 

13.2 Sentry란 

13.3 계정과 프로젝트 생성 

13.4 약속 잡기 프로젝트에 Sentry 반영 

__13.4.1 초기화 인자 

__13.4.2 통합(integration) 도구 인자

13.5 오류 로그 테스트 

13.6 수동으로 로그 남기기

 

14장 아마존 웹 서비스에 배포하기

14.1 의존 패키지 관리 

__14.1.1 패키지 관리자 

__14.1.2 의존 패키지 동결 

__14.1.3 uv로 더 빠르게 설치하기 

14.2 AWS Lightsail(라이트세일)로 서버 구성 

__14.2.1 AWS Lightsail이란 

__14.2.2 Lightsail 서비스 

__14.2.3 Lightsail에 서버 구성하기

14.3 인스턴스 서버에 환경 구성 

__14.3.1 SSH와 SSH 인증키 

__14.3.2 apt 패키지 관리자 

__14.3.3 빌드 도구 설치하기 

__14.3.4 Nginx 

__14.3.5 파이썬 가상 환경 구성하기 

__14.3.6 Hello World용 FastAPI 앱 작성하기 

__14.3.7 웹 애플리케이션 구동 스크립트 작성하기 

__14.3.8 Systemd로 서비스 관리하기 

__14.3.9 Nginx에 프록시로 연결하기 

__14.3.10 Nginx로 정적 파일 서빙하기

14.4 깃허브 액션을 사용하여 배포 자동화 

__14.4.1 깃허브 액션이란

__14.4.2 기본 개념 이해하기

__14.4.3 깃허브 워크플로 작성하기

[본 문]
  

이 책은 여러분이 웹 애플리케이션 서버를 구현하고 배포하여 출시하도록 돕습니다. 개발한 프로젝트를 출시한 경험이 없는 상태에서는 작게라도 출시하는 경험을 하는 것이 무엇보다 중요합니다. 여기서 ‘작게라도’라는 말은 프로젝트 규모를 가리키기도 하지만, 프로젝트에 들이는 내 의지력을 가리키기도 합니다. 예를 들어 프로젝트를 만드는 데 사용하는 도구가 너무 어렵거나 복잡하면 출시에 이르지 못할 가능성이 매우 높습니다. 그런 점에서 FastAPI는 학습 곡선이 가파르지 않아 ‘작게라도’에 부합합니다.

즉, 이 책은 FastAPI를 설명하지만, 프로젝트를 개발해서 출시하고 운영하는 데 적합한 실무 도구이자 학습 교보재로 FastAPI를 다룹니다. 이 책에 담거나 이 책에서 다루는 내용은 FastAPI가 아닌 도구에서도 활용되는 지식이자 기술이지만, FastAPI로 보다 쉽고 직관적으로 경험하고 학습합니다.

 

제 예상에는 다음 독자분들이 이 책을 기다리셨을 것 같습니다.

● 파이썬을 주요하게 사용한 적은 없지만, 웹 애플리케이션 서버를 빠르게 개발하고자 하는 다른 언어 경험자

● 장고(Django)나 플라스크(Flask)를 사용해 보았고, FastAPI를 실무적으로 학습하고자 하

는 개발자

● 파이썬을 사용하며, 웹 애플리케이션 서버를 제대로 개발하고 배포해 보고자 하는 데이터 사이언티스트나 데이터 엔지니어 또는 AI 엔지니어

 

또한, 이 책은 테스트 주도 개발이나 애자일 방법론을 주제로 삼은 책이 아닙니다. 하지만 테스트 주도 개발이나 애자일 방법론에서 수행하는 일부 요소를 효과적인 학습과 프로젝트 수행에 필요한 활동으로 활용합니다. 따라서 실무적인 테스트 코드를 설계하거나 계획 또는 작성하는 경험을 하거나 기획이나 요구 사항을 개발 작업으로 전환하는 경험을 이 책에서 얻을 수 있습니다. 현업에서 실무에 이런 개발 방법론을 어떻게 적용할지 막막하다면 유익한 실습 경험을 할 것입니다.

 

-본문 중에서-