FastAPI 입문 — 파이썬으로 빠른 API 서버 만들기

파이썬 문법을 어느 정도 익히면 다음 질문이 따라온다 — "이걸로 서버는 어떻게 만들지?" 프론트엔드 화면이 데이터를 받아오는 그 API, 모바일 앱 뒤에서 도는 그 서버를 파이썬으로 짤 때 요즘 가장 먼저 손이 가는 도구가 FastAPI 다.

JetBrains 의 파이썬 개발자 설문에서 FastAPI 사용률은 2021년 14% 에서 2023년 29% 로 두 배가 됐고, 신규 프로젝트에서는 이미 Flask 를 넘어선 조사도 있다. 입문 1편은 코드를 깊게 파기 전에 좌표부터 잡는다 — FastAPI 가 정확히 뭐고, 왜 이렇게 빨리 퍼졌고, Flask·Django 와 뭐가 다른지. 그리고 마지막에 진짜 서버 하나를 띄워 본다.

1. FastAPI 는 "파이썬 웹 프레임워크" — 단, 타입을 읽는다

한 줄 정리 — FastAPI = Starlette(웹 처리) + Pydantic(데이터 검증) + 파이썬 타입힌트. 웹 요청을 받고 응답을 돌려주는 뼈대는 Starlette 가 맡고, 들어온 데이터가 올바른지 따지는 일은 Pydantic 이 맡는다. FastAPI 는 이 둘을 타입힌트 하나로 묶는 접착제다.

여기서 "프레임워크" 가 막연하면 이렇게 보면 된다. 그냥 파이썬으로 웹 서버를 짜려면 요청 파싱, URL 분기, JSON 변환, 에러 처리를 전부 직접 해야 한다. 프레임워크는 그 반복 작업을 미리 만들어 두고, 우리는 "이 주소로 오면 이 함수를 실행해" 라는 핵심만 적게 해 준다.

2. 왜 이렇게 빨리 퍼졌나 — 타입힌트라는 한 수

FastAPI 가 등장한 2018년, 파이썬 백엔드는 Flask 와 Django 가 양분하고 있었다. 그 사이를 비집고 들어온 무기가 파이썬 3.6 의 타입힌트 였다. 다른 프레임워크들이 타입힌트를 "있으면 좋은 주석" 정도로 봤다면, FastAPI 는 그걸 실제로 동작하는 명세로 끌어올렸다.

무슨 말이냐 — 함수 매개변수에 price: float 라고 한 줄 적으면, FastAPI 가 그 정보로 세 가지를 자동으로 해 준다. 요청에서 값을 꺼내고, 숫자가 맞는지 검증하고, 틀리면 친절한 에러 메시지를 돌려준다. 거기다 그 타입 정보로 API 문서까지 자동 생성한다. 한 번 적은 타입이 네 가지 일을 한다.

이게 왜 큰가. 기존 방식은 "이 필드는 정수" 라는 규칙을 검증 코드·문서·테스트 세 군데에 베껴 썼다. 한 곳만 고치고 나머지를 까먹으면 곧장 버그다. FastAPI 는 그 중복을 타입힌트 한 줄로 합쳤다.

3. Flask·Django 와 무엇이 다른가

"파이썬 웹은 Django 아니에요?" 라고 묻는 사람에게 가장 쉬운 비교 표.

핵심 차이를 한 문장으로 — Django 는 "다 들어 있다", Flask 는 "네가 다 골라라", FastAPI 는 "API 만들 거면 이게 제일 덜 적는다". 화면(HTML)을 잔뜩 그리는 전통적 웹사이트라면 Django 가 여전히 강하다. 하지만 프론트는 React·앱이 따로 있고 백엔드는 JSON 만 주고받는 요즘 구조에서는 FastAPI 가 가장 군더더기 없다.

4. 왜 쓰나 — 네 가지 무기

① 자동 문서 — 코드가 곧 명세

서버를 띄우면 /docs 주소에 Swagger UI 가 저절로 생긴다. 모든 엔드포인트, 필요한 입력, 응답 형태가 표로 정리되고, 브라우저에서 버튼으로 직접 테스트까지 된다. 프론트엔드 개발자에게 "문서 보내드릴게요" 대신 "이 주소 보세요" 한 마디면 끝난다.

② 자동 검증 — 잘못된 요청은 함수 앞에서 걸린다

나이 자리에 글자가 들어오면, 함수 본문이 실행되기도 전에 FastAPI 가 422 에러와 "여기가 틀렸다" 는 메시지를 돌려준다. 검증 코드를 함수마다 쓰던 일이 사라진다.

③ 빠른 성능 — 비동기가 기본

FastAPI 는 ASGI 와 async 를 처음부터 끌어안았다. DB·외부 API 응답을 기다리는 동안 다른 요청을 처리해서, I/O 가 많은 서비스에서 동기식 Flask 보다 처리량이 크게 앞선다. Netflix·Uber·Microsoft 가 내부 서비스에 FastAPI 를 쓴다고 공개했다.

④ ML·AI 서빙의 사실상 표준

학습한 머신러닝 모델을 API 로 감싸 서비스할 때 FastAPI 가 1순위다. 파이썬으로 모델을 짰으니 같은 언어로 서빙하고, 입력 검증·문서가 공짜로 붙는다. 요즘 LLM 래퍼 서버도 대부분 FastAPI 위에 올라간다.

5. 설치하고 첫 서버 띄우기

이론은 여기까지. 진짜 서버를 하나 띄워 본다. 파이썬 3.8 이상이 깔려 있다고 보고(2편에서 가상환경부터 제대로 다룬다), 설치는 한 줄이다.

[standard] 를 붙이면 개발에 필요한 서버(uvicorn)와 부가 도구가 함께 깔린다. 이제 main.py 파일을 만들고 딱 다섯 줄을 적는다.

한 줄씩 보면 — app = FastAPI() 로 앱을 만들고, @app.get("/") 는 "누가 첫 페이지(/)를 GET 으로 요청하면" 이라는 뜻이며, 바로 아래 함수가 그때 실행된다. 돌려준 파이썬 딕셔너리는 FastAPI 가 알아서 JSON 으로 바꿔 보낸다. 실행은 이렇게.

브라우저에서 http://127.0.0.1:8000 을 열면 {"message":"안녕, FastAPI!"} 가 보인다. 그리고 진짜 마법은 http://127.0.0.1:8000/docs — 방금 만든 엔드포인트가 대화형 문서로 이미 정리돼 있다. 우리는 문서를 한 글자도 안 적었다.

요약 — FastAPI 좌표

핵심을 한 번 더. FastAPI 는 Starlette 와 Pydantic 을 타입힌트로 묶은 파이썬 API 프레임워크다. 타입힌트 한 줄이 값 추출·검증·문서·에러 처리를 동시에 해결하고, 비동기가 기본이라 빠르며, ML 서빙의 표준이 됐다. JSON 을 주고받는 API 서버라면 가장 적게 적고 가장 빨리 만든다. 2편에서는 가상환경을 만들고 경로·쿼리 매개변수로 입력을 받는 API 를 짠다.