FastAPI 처음 시작할 때 헷갈리는 개념, 여기서 대부분 막힌다

FastAPI를 처음 접하면 “빠르다”, “비동기다”, “문서가 자동 생성된다” 같은 설명부터 보게 된다. 그런데 막상 예제 코드를 실행해보면 왜 이렇게 되는지, 기존에 알던 Flask나 Django랑 뭐가 다른지 잘 감이 안 온다. FastAPI 처음 시작할 때 헷갈리는 개념은 실력이 부족해서라기보다, 개념이 한 번에 설명되지 않아서 생기는 경우가 많다. 처음에 가장 많이 헷갈리는 지점만 골라서 정리해본다.

---

 

📝 FastAPI 서버 실행 후 브라우저에서 자동 생성된 Swagger(API 문서) 화면이 열린 모습

---

FastAPI는 프레임워크일까, 라이브러리일까

처음에 가장 많이 헷갈리는 부분이다. FastAPI는 “웹 서버를 만들어주는 도구”이긴 하지만, Django처럼 모든 걸 다 포함한 프레임워크와는 결이 다르다. 라우팅, 요청 처리, 검증 같은 핵심만 깔끔하게 제공하고, 나머지는 필요한 만큼 조합해서 쓰는 구조다. 그래서 FastAPI를 쓰면 내가 뭘 직접 구성해야 하는지를 이해하는 게 중요하다.

---

왜 갑자기 비동기(async)가 나오는 걸까

async가 필수처럼 보이는 이유

FastAPI 예제를 보면 함수 앞에 async가 붙어 있는 경우가 많다. 이걸 보면 “비동기를 꼭 써야 하나?”라는 생각이 든다. 실제로는 그렇지 않다. 동기 함수도 그대로 쓸 수 있다. 다만 FastAPI는 비동기 처리를 잘 활용할 수 있도록 설계돼 있어서, 외부 API 호출이나 DB 접근이 많은 경우 성능상 이점이 커진다.

같은 환경에서 확인해보면, 단순한 API에서는 async 여부에 따른 차이를 체감하기 어렵다. 처음부터 모든 걸 비동기로 이해하려고 하기보다는, “필요할 때 쓰는 선택지” 정도로 받아들이는 게 낫다.

---

요청 파라미터는 왜 이렇게 자동으로 처리될까

FastAPI를 처음 쓰면 파라미터가 어디서 오는지 헷갈린다. URL 쿼리인지, 바디인지, 경로 변수인지 명시하지 않았는데도 잘 동작한다. 이건 FastAPI가 타입 힌트 기반으로 요청을 해석하기 때문이다. 함수 인자의 위치와 타입을 보고 자동으로 판단한다.

이 구조 덕분에 코드가 짧아지지만, 반대로 내부 동작을 모르면 “왜 이게 되는지” 감이 안 잡힌다. 이 부분이 FastAPI 처음 시작할 때 헷갈리는 개념 중 하나다.

---

Pydantic 모델은 왜 꼭 써야 할까

데이터 검증의 중심 역할

FastAPI에서 Pydantic 모델은 단순한 DTO가 아니다. 요청 데이터 검증, 타입 체크, 문서 자동 생성까지 한 번에 담당한다. 처음에는 귀찮아 보일 수 있지만, 실제로 적용해보면 예상치 못한 입력을 막아주는 역할이 꽤 크다.

직접 확인한 사례 기준으로 보면, Pydantic 모델을 쓰기 시작한 뒤부터 API 오류 원인을 찾는 시간이 눈에 띄게 줄어드는 경우도 많다.

---

서버를 실행하면 왜 문서 페이지가 바로 나올까

FastAPI의 가장 눈에 띄는 특징 중 하나다. 서버를 실행하면 /docs나 /redoc에서 바로 API 문서를 볼 수 있다. 이건 FastAPI가 코드에 정의된 타입 정보와 경로를 기반으로 문서를 자동 생성하기 때문이다. 따로 설정하지 않아도 되는 점이 편하지만, 처음엔 “이게 왜 자동으로 생긴 거지?”라는 생각이 들 수 있다.

---

 

📝 FastAPI 코드에서 라우터와 타입 힌트가 함께 정의된 간단한 API 예제 화면

---

처음 시작할 때 이렇게 생각하면 편하다

FastAPI는 “서버를 만드는 마법 도구”라기보다, API를 구조적으로 만들기 쉽게 정리해둔 틀에 가깝다. 처음부터 모든 기능을 이해하려고 하면 오히려 더 헷갈린다. 라우팅 → 요청 처리 → 응답 구조 이 세 가지만 잡고 시작해도 충분하다.

---

직접 써보고 느낀 점

FastAPI 처음 시작할 때 헷갈리는 개념은 대부분 “자동으로 되는 것들”에서 나온다. 실제로 적용해보면, 이 자동화 덕분에 반복 작업이 크게 줄어든다는 걸 체감하게 된다. 처음엔 낯설지만, 한두 개 API를 직접 만들어보면 구조가 자연스럽게 보이기 시작한다.

---

정리

FastAPI는 비동기, 타입 힌트, 자동 문서 같은 요소가 한꺼번에 등장해서 처음엔 어렵게 느껴진다. 하지만 핵심은 단순하다. 요청을 어떻게 받고, 데이터를 어떻게 검증하고, 응답을 어떻게 돌려주는지만 이해하면 된다. 나머지는 쓰다 보면 자연스럽게 따라온다. FastAPI는 처음보다, 조금 써본 뒤에 진가가 보이는 도구에 가깝다.