왜 파이썬이고, 왜 FastAPI인가 — 다른 언어·프레임워크와 비교해 보기 (FastAPI 입문 1편)

들어가며 — “그 API 주소가 뭐였죠?”

크게 보기

협업하다 보면 이런 대화가 매일 오간다.

• 프론트엔드 개발자: “할 일 목록 가져오는 API 주소가 뭐였죠? /todo인가요, /tasks인가요?”
• 백엔드 개발자: “/tasks요. 아, 우선순위 필드는 priority고 1~5 정수예요.”
• 기획자: “완료된 것만 보려면 어떻게 요청해요?”
• QA: “제목을 비워서 보내면 어떻게 되나요? 에러가 나야 하는데 저장돼 버려요.”

이 질문들에는 공통점이 있다. API가 어떻게 생겼는지 한곳에 정리돼 있지 않아서 생긴다는 점이다. FastAPI를 쓰는 팀에서는 대부분 이렇게 답하고 끝난다. “/docs 열어 보세요.”

이 시리즈는 FastAPI를 처음 접하거나, 팀 프로젝트에 투입됐지만 기본 사용법이 막막한 사람을 위해 썼다. 목표는 거창하지 않다. 라우팅과 /docs만 제대로 알아도 FastAPI 협업의 80%는 해결된다. 여기에 CRUD(만들기·읽기·수정·삭제)를 더하면 대부분의 사내 API를 읽고, 고치고, 새로 만들 수 있다.

첫 편인 이 글에서는 코드를 거의 쓰지 않는다. 대신 세 가지 질문에 답한다.

1. API란 무엇이고, 백엔드 프레임워크는 무슨 일을 대신해 주는가?
2. 왜 많은 팀이 백엔드 언어로 파이썬을 고르는가? 약점은 무엇인가?
3. 파이썬 안에서도, 그리고 다른 언어와 비교해서도 FastAPI를 고르는 이유는 무엇인가?

1. API와 백엔드 프레임워크 — 식당으로 이해하기

크게 보기

API(Application Programming Interface)는 프로그램끼리 대화하는 약속이다. 웹 API는 식당에 빗대면 쉽다.

• 클라이언트(손님): 웹 브라우저, 모바일 앱, 다른 서버. “할 일 목록 주세요”라고 요청(request) 한다.
• API(메뉴판과 웨이터): 어떤 주문을 어떤 형식으로 받는지 정해 둔 약속. 메뉴에 없는 걸 주문하면 “그런 메뉴는 없습니다(404)”라고 답한다.
• 서버(주방): 실제로 데이터를 찾고, 저장하고, 계산해서 응답(response) 을 돌려준다.

웹 API의 주문서는 대개 이렇게 생겼다.

백엔드 프레임워크는 이 주문을 받는 데 필요한 반복 작업을 대신 해 준다.

프레임워크마다 차이가 나는 곳은 ②와 ⑤다. ①·③·④는 어느 프레임워크든 해 준다. 그런데 협업에서 사고가 나는 곳은 대부분 ②(검증 누락)와 ⑤(문서 부재) 다. 앞의 QA 질문(“제목이 비어도 저장돼요”)은 ②의 문제고, 프론트엔드 질문(“주소가 뭐였죠?”)은 ⑤의 문제다. FastAPI는 바로 이 둘을 코드를 따로 쓰지 않아도 해 준다는 점에서 다른 프레임워크와 갈린다. 뒤에서 자세히 보자.

2. 왜 파이썬인가

2-1. 숫자로 본 파이썬

2-2. 팀이 파이썬을 고르는 네 가지 이유

2-3. 그래도 알아 둘 파이썬의 약점

파이썬이 모든 면에서 좋은 것은 아니다. 약점을 알고 고르는 것과 모르고 고르는 것은 다르다.

3. 파이썬 3대 웹 프레임워크 — Django, Flask, FastAPI

파이썬으로 웹 서버를 만든다고 하면 보통 세 후보가 나온다.

FastAPI는 가장 늦게 나왔지만 GitHub 스타 수로는 셋 중 가장 많다. 이유는 시대 변화에 있다. 2010년대 중반 이후 웹의 구조가 “서버가 HTML을 만들어 보내는 방식”에서 “React·Vue·모바일 앱이 화면을 그리고, 서버는 JSON API만 제공하는 방식”으로 바뀌었다. 서버의 역할이 API로 좁혀지자, API에 필요한 것(검증·문서·비동기)을 기본으로 주는 프레임워크가 유리해졌다. 여기에 AI 모델을 API로 감싸야 하는 수요가 2023년 이후 폭발했다.

4. 다른 언어와 비교 — 같은 API를 여섯 가지로

말로 비교하는 것보다 코드를 보는 편이 빠르다. 아래 위젯은 똑같은 API — GET /users/{id}: id가 정수인지 확인하고 JSON을 돌려준다 — 를 여섯 프레임워크로 짠 코드다. 탭을 눌러 코드와 ‘기본으로 해 주는 일’을 비교해 보자.

위젯에서 눈여겨볼 점은 코드 길이가 아니라 “id가 정수가 아니면?”을 누가 처리하느냐다.

• Express·Gin: 개발자가 직접 Number(...)나 strconv.Atoi(...)로 바꾸고, 실패하면 에러 응답 모양까지 직접 정한다. 팀원 다섯 명이 API 다섯 개를 만들면 에러 모양이 다섯 가지가 되기 쉽다.
• Spring Boot: 타입 변환은 해 주지만, 파일 구조·빌드 설정·어노테이션을 먼저 이해해야 한다. 대규모 조직에서는 이 형식이 오히려 장점이다.
• FastAPI: user_id: int 한 줄로 변환·검증·문서화가 끝난다. 잘못된 값이 오면 항상 같은 모양의 422 응답이 나간다. 팀 규칙을 코드가 강제하는 셈이다.

언어별 특징을 표로 정리하면 이렇다.

5. FastAPI를 만드는 세 기둥

FastAPI는 바닥부터 새로 만든 프레임워크가 아니다. 검증된 두 라이브러리 위에 “파이썬 타입 힌트”라는 접착제를 바른 구조다.

핵심은 한 번 적은 타입 정보가 세 곳에서 재사용된다는 점이다.

@app.get("/users/{user_id}")
def read_user(user_id: int):          # ← 이 int 하나가
    return {"id": user_id, "name": "홍길동"}

• 검증: /users/abc로 요청하면 함수를 실행하기 전에 422 에러를 돌려준다.
• 변환: 주소에서 온 문자열 "42"를 정수 42로 바꿔서 함수에 넘긴다.
• 문서: /docs 화면에 “user_id: integer, 필수”라고 자동으로 표시한다.

다른 프레임워크에서는 이 세 가지를 각각 따로 쓰고, 셋이 서로 어긋나지 않게 사람이 관리해야 한다. 코드는 바뀌었는데 문서는 안 바뀌는 사고가 여기서 난다. FastAPI에서는 코드가 곧 문서라서 어긋날 수가 없다. 협업하는 팀이 FastAPI를 좋아하는 가장 큰 이유다.

6. FastAPI를 고르지 말아야 할 때

좋은 도구 소개는 “언제 쓰지 말라”도 알려 줘야 한다.

7. 어떤 파이썬 버전으로 돌릴까

“파이썬 깔려 있는데 그냥 쓰면 되지 않나요?”라는 질문이 가장 많다. 결론부터 말하면 새 프로젝트는 Python 3.13을 기본으로 하고, 팀 전원이 같은 버전을 쓰도록 고정하는 것을 권한다. 이유를 차례로 보자.

7-1. 파이썬 버전은 5년 동안 지원된다

파이썬은 매년 10월에 새 버전(3.x)이 나온다. 각 버전은 처음 약 2년 동안 버그 수정을 받고(bugfix), 그다음 3년은 보안 수정만 받다가(security), 출시 5년 뒤 지원이 끝난다(end-of-life, EOL). 지원이 끝난 버전은 보안 구멍이 발견돼도 고쳐지지 않고, 라이브러리들도 하나둘 설치를 막는다.

2026년 9월 27일 기준 상태와, 이 시리즈의 예제(7편의 테스트 8개 + 6편의 PATCH 검증)를 버전마다 직접 돌려 본 결과다.

남은 지원 기간을 막대로 보면 차이가 더 분명하다(2026년 9월 기준, 한 버전의 전체 지원 기간 60개월을 100%로).

7-2. 왜 3.13인가 — 가장 새것이 아니라 “가장 무난한 것”

• 버그 수정 단계다. 보안 수정만 받는 3.11·3.12와 달리 일반 버그도 아직 고쳐진다.
• 나온 지 2년 가까이 됐다. PyTorch·pandas·NumPy 같은 AI·데이터 라이브러리가 모두 미리 빌드된 설치 파일(wheel)을 제공한다. 3.14도 지원은 넓어졌지만, 오래된 사내 라이브러리나 C 확장이 있으면 3.13 쪽이 사고가 적다.
• 2029년 10월까지 지원된다. 지금 시작한 프로젝트가 한동안 버전 걱정 없이 간다.

모든 의존성이 3.14를 지원한다는 게 확인되면 3.14를 써도 좋다. 이 시리즈의 예제는 3.14에서도 모두 통과했다. 반대로 3.10을 쓰고 있다면 다음 달(2026년 10월)에 지원이 끝나니 올릴 계획을 세우자.

7-3. 오래된 버전의 함정 — 에러 없이 옛 FastAPI가 깔린다

3.9에서 pip install "fastapi[standard]"를 실행하면 에러가 나지 않는다. pip이 3.9를 지원하는 마지막 FastAPI(0.128.8)를 조용히 골라 설치하기 때문이다. 문제는 그다음이다. 이 시리즈의 코드를 실행하면 이렇게 멈춘다(실제 출력).

TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

str | None 같은 타입 표기는 3.10부터 생긴 문법이기 때문이다. 튜토리얼 코드가 안 돌 때 가장 먼저 python --version을 확인해야 하는 이유다.

7-4. 버전별로 FastAPI 코드에 영향을 주는 변화

7-5. 팀 전원이 같은 버전을 쓰게 고정하기

“내 컴퓨터에서는 되는데요”의 절반은 파이썬 버전 차이다. 버전을 파일로 고정해 커밋하자. uv를 쓰면 두 줄이면 된다.

uv init --python 3.13 todo-api     # 프로젝트 생성 + 버전 지정
cd todo-api
uv python pin 3.13                 # 나중에 바꿀 때 (.python-version 갱신)

그러면 두 파일이 생긴다. 둘 다 Git에 커밋한다.

uv는 파이썬 자체도 설치·관리해 주므로, 팀원 컴퓨터에 어떤 파이썬이 깔려 있든 uv sync 한 번이면 같은 버전·같은 패키지 환경이 만들어진다. 프로젝트 파일 구성은 7편에서 자세히 다룬다.

8. 다음 편을 위한 준비물

2편부터는 직접 코드를 돌린다. 미리 준비해 두면 좋다.

설치 명령은 이것 하나면 된다(2편에서 단계별로 다시 설명한다).

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install "fastapi[standard]"

[standard]를 붙이면 개발 서버(fastapi dev 명령과 uvicorn), 테스트용 HTTP 클라이언트 등 입문에 필요한 도구가 함께 설치된다.

정리

다음 편에서는 첫 FastAPI 앱을 띄우고, 이 시리즈의 가장 중요한 개념인 라우팅 — 주소를 함수에 잇는 법, 경로 매개변수와 쿼리 매개변수 — 을 다룬다.