FastAPI

파이썬으로 웹 API를 짜는 길은 여럿이다. 그중 요즘 가장 많이 불리는 이름이 FastAPI다. 타입 힌트만 제대로 달아두면, 들어오는 요청을 알아서 검사하고 API 문서까지 자동으로 그려주는 파이썬 웹 프레임워크다. 빠르게 짜는데 타입까지 안전하다는 게 인기의 이유다. 코드를 많이 안 늘리고도 "이 API는 이런 요청을 받는다"가 문서로 딱 떨어진다.

Spring 하던 사람 기준 다리

낯선 세계 같지만 자리는 똑같다. 백엔드 프레임워크라는 역할이 겹치니, 이미 아는 것에 대응시키면 금방 붙는다.

Spring에서 요청 본문을 DTO로 받고 @Valid로 검사하던 그 흐름이, FastAPI에선 pydantic 모델 하나로 합쳐진다. 함수 인자에 모델 타입만 적어두면 검증·파싱·문서화가 한 번에 딸려온다.

pydantic 모델은 입국 심사대다

FastAPI를 이해하는 핵심은 pydantic이다. 비유하면 공항 입국 심사대다. 아무 요청이나 서버 안으로 들여보내지 않는다. 타입이 안 맞거나(숫자 자리에 글자가 오거나), 필수 항목이 비어 있으면 문 앞에서 반려한다. 심사를 통과한 요청만, 잘 정리된 객체 형태로 안으로 들어온다.

그래서 함수 몸통 안에서는 "이 값이 있을까, 형식이 맞을까"를 다시 걱정할 필요가 없다. 이미 심사대에서 걸러졌으니까. Spring에서 @Valid가 튕겨내던 걸, 여기선 모델 정의 자체가 심사관 역할을 한다.

공짜로 딸려오는 두 가지

FastAPI가 "빠른 개발"로 불리는 건 이 둘 덕이 크다.

하나는 자동 문서다. 모델을 정의하는 순간, /docs 주소에 눌러볼 수 있는 API 문서가 생긴다. 요청 스키마와 응답 형식이 코드와 항상 같이 움직여서, 문서가 낡을 일이 없다. Spring에서 springdoc을 따로 붙이던 걸 기본으로 준다고 보면 된다.

다른 하나는 async 네이티브다. 함수 앞에 async를 붙이면, DB나 외부 API를 기다리는 동안 서버가 멈추지 않고 다른 요청을 처리한다. 기다림이 많은 일에 적은 자원으로 버티는 방식인데 — 이 저글링이 낯설다면 Node.js플레이북Node.js자바스크립트를 서버까지 짜게 만든 실행 환경. 노트의 이벤트 루프 이야기가 그대로 겹친다.

우리 프로젝트에선

새김 AI개인 제품새김 AI프레임워크 없이 직접 구현한 개인 데이터 AI OS.의 백엔드가 FastAPI로 돈다. 요청 스키마를 pydantic 모델로 정의해두니, 잘못된 요청은 심사대에서 걸리고 API 문서는 알아서 따라왔다.

새김 Eval개인 제품새김 Eval정답지 없이 채점하고 심판까지 검증하는 엔진.도 파이썬으로 짰는데, 여기선 pydantic을 살짝 다르게 쓴다. LLM이 뱉는 답을 정해진 구조(점수·근거 같은 필드)로만 받도록 강제하는 틀로. 요청을 검사하던 그 심사대를, 이번엔 모델의 출력을 검사하는 데 세운 셈이다.

더 읽기

비유가 아직 흐릿하면, 손으로 한 번 만들어보는 글이 제일 빠르다.

• FastAPI 공식 한국어 문서 — 튜토리얼이 친절하다. 타입 힌트 하나로 검증·문서가 붙는 걸 직접 확인
• FastAPI + Pydantic으로 API 문서와 데이터 검증까지 한 번에 — 버즈니 — pydantic이 문서와 검증을 어떻게 동시에 해주는지
• Python FastAPI 입문 시리즈 — 안영준 — 왜 FastAPI인지부터 차근차근