FastAPI로 배우는 백엔드 프로그래밍 with 클린 아키텍처

한용재 지음

제이펍 2024년 12월 09일 출간 국내도서 : 2024년 10월 25일 출간

작품소개

책소개

파이썬 기반의 FastAPI는 플라스크보다 API 생성이 쉽고, 장고보다 가볍다. 이 책은 FastAPI를 활용해 백엔드 소프트웨어를 클린 아키텍처로 작성하는 법을 안내한다. 클린 아키텍처는 계층이 많아짐에 따라 코드의 양 또한 늘어나지만, 계층을 나누기 편한 FastAPI는 클린 아키텍처를 적용하기에 적합한 웹 프레임워크다. TIL 앱을 만들기 위해 먼저 FastAPI와 클린 아키텍처의 개념과 기능을 알아본 후 회원 가입, DI 도입, CRUD 기능, JWT, 환경변수 설정, 클린 아키텍처 계층 구현, 테스트 작성 등 한 단계씩 나아간다. 클린 아키텍처를 적용하는 과정을 통해 FastAPI라는 강력한 무기를 얻게 될 것이다.

목차

베타리더 후기 ix
시작하며 xii
이 책에 대하여 xiv

CHAPTER 1 FastAPI 개발 환경 구축 1
1.1 FastAPI 소개 1
1.2 포어트리를 이용한 가상 환경과 의존성 관리 5
1.3 Hello, FastAPI 10
1.4 API 문서화 14
1.5 데이터베이스 설정 19
1.6 책에서 만들 애플리케이션: TIL 22
1.7 마무리 23

CHAPTER 2 클린 아키텍처 25
2.1 아키텍처가 필요한 이유 25
2.2 분할 정복 29
2.3 클린 아키텍처의 주요 4계층 30
__2.3.1 도메인(엔티티) 계층 32
__2.3.2 애플리케이션(유스 케이스) 계층 33
__2.3.3 인터페이스(인터페이스 어댑터) 계층 34
__2.3.4 인프라스트럭처(프레임워크 및 드라이버) 계층 35
2.4 의존관계 역전 원칙 36
2.5 마무리 37

CHAPTER 3 회원 가입 39
3.1 User 도메인 39
3.2 회원 가입 유스 케이스 41
__3.2.1 ULID 41
__3.2.2 유저 저장 42
__3.2.3 중복 유저 검사 44
__3.2.4 패스워드 암호화 45
3.3 회원 가입 인터페이스 47
__3.3.1 API 라우터 47
__3.3.2 파이단틱을 이용한 유효성 검사 48
__3.3.3 유효성 검사 오류의 상태 코드를 400 Bad Request로 변경하기 50
__3.3.4 유저 생성 유스 케이스 호출 52
__3.3.5 클래스 기반 라우터 53
3.4 회원 정보 영속화 54
__3.4.1 SQLAlchemy ORM 적용 54
__3.4.2 Alembic으로 테이블 생성 및 리비전 관리 56
__3.4.3 UserRepository 구현 62
3.5 마무리 65

CHAPTER 4 의존성 주입 67
4.1 Depends 68
4.2 dependency-injector 69
4.3 마무리 74

CHAPTER 5 회원 리소스의 CRUD 기능 완성 75
5.1 유저 메모 속성 추가 75
5.2 유저 정보 업데이트 78
5.3 유저 목록 조회 82
__5.3.1 테스트용 유저 데이터 생성 82
__5.3.2 유저 목록 조회 82
__5.3.3 페이징 84
5.4 회원 탈퇴(유저 삭제) 88
5.5 파이단틱 유효성 검사 91
__5.5.1 요청 파라미터/본문 검사 91
__5.5.2 파이단틱 응답 모델 95
5.6 마무리 97

CHAPTER 6 비동기 프로그래밍 99
6.1 파이썬에서 동시성을 처리하는 방법 99
6.2 FastAPI의 비동기 처리 101
6.3 비동기 적용 기준 104
6.4 마무리 105

CHAPTER 7 로그인 107
7.1 JWT 107
__7.1.1 헤더 109
__7.1.2 페이로드 110
__7.1.3 시그니처 111
7.2 로그인 112
7.3 JWT 인증/인가 116
__7.3.1 토큰에 역할 추가 116
__7.3.2 일반 유저용 API 인증/인가 118
__7.3.3 어드민용 API 인증/인가 121
7.4 마무리 124

CHAPTER 8 환경변수 125
8.1 dotenv 126
8.2 config.py: 환경변수 관리 모듈 127
8.3 환경변수 적용 128
8.4 마무리 130

CHAPTER 9 TIL Note 131
9.1 도메인 계층 구현 132
9.2 애플리케이션 계층 구현 134
9.3 인터페이스 계층 구현 139
__9.3.1 노트 생성 140
__9.3.2 노트 목록 조회/노트 상세 조회 141
__9.3.3 노트 업데이트 143
__9.3.4 노트 삭제 144
__9.3.5 태그 이름으로 노트 검색 144
9.4 인프라 계층 구현 145
__9.4.1 Note, Tag 테이블 모델링 145
__9.4.2 테이블 마이그레이션 147
__9.4.3 노트 저장소: 노트 조회 150
__9.4.4 노트 저장소: 노트 생성 152
__9.4.5 노트 저장소: 노트 업데이트 153
__9.4.6 노트 저장소: 노트 삭제 154
__9.4.7 노트 저장소: 태그명으로 노트 조회 155
9.5 마무리 156

CHAPTER 10 백그라운드 작업: 환영 이메일 발송 157
10.1 BackgroundTasks 158
__10.1.1 BackgroundTasks란? 158
__10.1.2 BackgroundTasks로 이메일 전송 160
10.2 셀러리 166
__10.2.1 셀러리란? 166
__10.2.2 셀러리 환경 설정 169
__10.2.3 셀러리 태스크 수행 예시 171
__10.2.4 셀러리로 이메일 전송 176
10.3 마무리 178

CHAPTER 11 미들웨어 179
11.1 미들웨어 예시 181
11.2 콘텍스트 변수 183
11.3 유저 활동을 추적하는 로깅 186
__11.3.1 유저 정보를 콘텍스트 변수로 저장하는 미들웨어 186
__11.3.2 커스텀 로거 188
__11.3.3 유저 ID가 포함된 로그 출력 190
11.4 마무리 191

CHAPTER 12 테스팅 193
12.1 도메인 계층 테스트 194
12.2 애플리케이션 계층 테스트 196
__12.2.1 테스트 더블 197
__12.2.2 유저 생성 유스 케이스 테스트 198
12.3 인터페이스 계층 테스트 204
12.4 인프라 계층 테스트 206
12.5 마무리 209

찾아보기 212

책 속으로

API를 만들면 이를 사용할 다른 구성원에게 전달해야 한다. 조직이 작고 API 사용자가 같은 공간에 있으며 프레임워크의 코드를 이해하고 있다면 소스 코드를 공유해도 상관없다. 하지만 사용하는 언어와 기술 스택이 다른 프런트엔드 개발자가 API 사용자라면 어떻게 사용법을 설명해야 할까? 텍스트로 나름의 형식으로 기술할 수도 있고, 스프레드시트에 보기 좋게 정리할 수도 있다. 심지어 아직도 이런 방법을 많이 사용한다. 하지만 프로그램과 마찬가지로 문서도 레거시로 굳어지면 바꾸기 힘든 법이다. 문서를 배포하는 가장 좋은 방법은 소스 코드에서 API를 문서를 생성하는 것이고, FastAPI는 이를 별다른 설정 없이 지원한다. (15쪽)

클린 아키텍처의 의존성 규칙은 그 의존성의 방향이 안으로 향하는 데에 있다. 그림 2-1의 좌측에 바깥 계층에서 안쪽으로 향하는 화살표가 있다. 이 화살표가 의존성의 방향을 나타낸다. 데이터의 형식 역시 마찬가지다. 고수준의 데이터 형식은 저수준에서 자유롭게 사용할 수 있다. 하지만 고수준의 구성 요소가 저수준의 데이터 형식에 의존하면 안 된다. 이는 외부 변경으로부터 내부 요소를 격리해 보호하기 위함이다. 외부에서 제공되는 프레임워크나 라이브러리는 우리의 의지와 상관없이 업데이트될 수 있다. 이러한 변경이 발생했을 때 만약 그 라이브러리의 모듈에 직접 의존하고 있다면 내부의 요소를 함께 수정해야 한다. (36쪽)

유저 리소스에서 유저가 자신의 정보를 업데이트할 수 있는 속성은 name과 password다. 일반적으로 이름을 갱신하는 것은 이상한 일이지만, TIL에서는 이름을 닉네임처럼 쓸 것이기 때문에 문제가 되지 않는다. email은 유저가 로그인할 때 사용하는 값이기 때문에 유일한 값으로 변경할 수 없다고 가정하자. / 다시 도메인 계층부터 차례로 구현해보자. 먼저 IUserRepository에 유저 ID로 유저를 검색하는 함수와 유저 리소스를 업데이트하는 함수를 선언한다. 유저 검색 함수가 필요한 이유는 업데이트할 대상을 찾기 위해서다. 만약 데이터베이스에 해당 유저가 존재하지 않을 경우 에러를 일으킨다. (78쪽)

시스템을 운영하다 보면 로그인한 유저에 대해 여러 가지 역할role을 부여해야 하는 경우가 있다. 역할에 따라 어떤 리소스에 대해 접근이 가능한지 권한을 제한하고, 역할을 그룹으로 묶어 계층적으로 관리하기도 한다. / 앞서 나열한 API 중, 유저는 자신이 가진 권한으로 실행할 수 있는 API만 호출할 수 있어야 한다. 유저는 회원 탈퇴를 뜻하는 유저 삭제 API와 자신의 정보를 갱신하는 유저 정보 업데이트 API만 가능하다. 유저는 함부로 다른 사람의 정보를 조회하면 안 되므로, 유저 목록 조회는 어드민(애플리케이션 관리자)만 가능해야 한다고 하자. 따라서 권한을 검사하는 인가 기능이 필요하다. 인가 시스템을 제대로 갖추는 작업은 이 책의 범위를 벗어난다. 이 책에서는 단순히 역할을 뜻하는 role이라는 페이로드를 토큰에 추가하고, 그 값이 USER인지 ADMIN인지 구분해 권한을 검사한다. (117쪽)

BackgroundTasks는 FastAPI에서 제공하는 도우미 클래스다. 이 클래스를 사용하면 클라이언트로부터 요청을 받은 후 작업을 백그라운드에서 수행할 수 있다. 앞의 예에서 보았듯이 HTTP 요청을 처리할 때 작업이 오래 걸리거나 비동기적으로 처리해야 하는 경우 클라이언트에게 즉시 응답을 보내고 작업을 백그라운드에서 처리하고 싶을 수 있다. 이렇게 처리하면 클라이언트의 사용성이 나아진다. 즉, 요청이 완료되기를 기다리지 않고 다른 작업을 이어서 할 수 있다. / BackgroundTasks 클래스를 사용하면 FastAPI 앱에서 이러한 작업을 손쉽게 처리할 수 있다. 다음 예에서 보겠지만, 엔드포인트 함수의 매개변수로 주입받아 사용하고 FastAPI가 나머지를 처리하도록 할 수 있다. 마치 Request 객체를 직접 주입받아 사용할 때와 마찬가지다. (158쪽)

셀러리(Celery)는 유닉스 시스템 기반의 분산 작업 큐(distributed task queue)로서, 비동기 작업을 처리하고 관리하는 데 사용된다. 주로 백그라운드 작업을 처리하거나 스케줄링하고 분산 환경에서 작업을 실행한다. 파이썬 기반의 메시징 시스템은 셀러리 외에도 레디스 큐(Redis queue, RQ), 드라마틱(Dramatiq), 휴이(huey), AIOHTTP와 같은 것을 고려해볼 만하다. 그 외 최근에는 대규모 시스템에서도 높은 성능을 자랑하는 카프카(Kafka)가 인기를 끌고 있다. (166~167쪽)

출판사 서평

FastAPI와 클린 아키텍처로 스파게티 코드 없애기

2024년 스택 오버플로에서 실시한 '웹 프레임워크 및 기술' 항목에서 FastAPI가 14위에 올랐다. 파이썬 웹 프레임워크 중에서는 플라스크, 장고의 뒤를 이어 3위를 기록하며, 2018년 첫 등장 이후 플라스크와 장고의 뒤를 빠르게 추격하고 있다. 또한 아직 버전 1이 정식 출시되지 않았음에도 뛰어난 성능과 직관적인 사용법 등 수많은 장점을 가지고 있어 넷플릭스, 우버, 시스코 시스템즈 등 많은 기업에서 채택하고 있다.

FastAPI는 공식 문서가 이미 매우 잘 정리되어 있어, 이 책은 FastAPI를 활용한 소프트웨어 구조 설계와 이를 통해 유지보수성과 확장성을 극대화하는 클린 아키텍처에 중점을 둔다. 오늘날 백엔드 개발에서 가장 중요한 요소 중 하나는 효율적이고 확장 가능한 아키텍처다. ‘제대로 된’ 아키텍처가 없는 시스템은 스파게티 코드와 큰 진흙덩어리와 다를 바 없다. 12장으로 구성된 이 책은 FastAPI의 강력한 기능을 바탕으로 클린 아키텍처를 적용해 유지보수가 용이하고 안정적인 시스템을 만드는 방법을 제시한다.

1장에서는 FastAPI의 특징과 포어트리를 통한 개발 환경의 구축 방법, 책에서 만들 TIL 앱 구조를 간단히 살펴본다. 2장에서는 도메인, 애플리케이션, 인터페이스, 인프라 계층으로 나누어 클린 아키텍처를 알아본다. 3장에서는 TIL 앱 서비스의 핵심 기능 중 하나인 회원 가입을 FastAPI로 구현하면서 클린 아키텍처를 적용한다.

4장에서는 3장에서 구현한 회원 가입 기능에 의존성 주입을 도입하고, 5장에서는 파이단틱을 활용해 유저 정보를 조회, 수정 삭제하는 API를 완성한다. 6장에서는 FastAPI에서 동시성을 처리하기 위한 방법의 하나인 비동기 처리를 수행하는 예를 살펴본다. 7장에서는 TIL 서비스에 가입한 유저가 로그인하는 기능을 만들어보면서, 인증/인가에 가장 많이 사용되는 JWT에 대해 알아보고 적용한다.

8장에서는 코드 내에 하드 코딩돼 있는 값들을 환경변수로 관리하는 작업을, 9장에서는 TIL 서비스의 기능을 확장해 유저가 작성한 게시물(노트) 리소스를 다루는 예를 알아본다. 10장에서는 FastAPI로 서버를 개발할 때 적용할 수 있는 백그라운드 작업 방식을, 11장에서는 미들웨어 활용 방법을 다룬다. 마지막으로 12장에서는 반복적인 테스트를 쉽게 할 수 있고, 안전한 시스템을 구축할 수 있도록 작성한 코드에 대해 테스트 코드를 작성한다.

이 책은 FastAPI와 클린 아키텍처를 통해 단순한 기능 구현을 넘어, 더 나은 소프트웨어 설계 방법을 고민하는 개발자들에게 유용한 가이드다. 특히 빠르게 변화하는 웹 개발 환경에서 안정적이고 확장 가능한 백엔드 시스템을 구축하고자 하는 개발자들에게 실질적인 도움을 줄 것이다.

주요 내용
● FastAPI와 클린 아키텍처의 개념과 기능
● 파이단틱을 이용한 유효성 검사
● DI 방식과 적용 방법
● 인증/인가를 위한 JWT 활용
● 셀러리를 이용한 비동기 처리
● HTTP 요청과 응답이 쉬워지는 미들웨어 사용법
● 계층별로 단위 테스트 적용하는 법

작가정보

저자(글) 한용재

LG전자 MC사업부에서 휴대폰에 탑재되는 소프트웨어를 오랜 기간 만들었고, 토스인컴과 모두싸인에서 백엔드 엔지니어로 활동하다가 현재는 비긴트의 대표를 맡고 있다. 모토는 일신우일신(日新又日新)이고, 영화와 교양 과학 서적을 좋아한다. 《NestJS로 배우는 백엔드 프로그래밍》(2022, 제이펍)을 집필했고, 《처음 시작하는 FastAPI》(한빛미디어, 2024), 《이펙티브 소프트웨어 테스팅》(2023, 제이펍)을 번역했다.