[FastAPI] Spring Boot 개발자가 이해하는 FastAPI 구조와 용어 매핑

 

너넨 이거다 싶어서 지었겠지만 난 안 와닿았다.

---

아오 대체 왜 이름을 이렇게 지어서 감이 안오게 하냐 이놈들아...

 

FastAPI가 뭘까. 

api는 약속, 네가 이렇게 요청하면 내가 이렇게 주지~

그니까 남이 해놓은걸 쉽게 쓸수 있는건데 거기다 '빠르다' 뭐 그런 이름이 아닐까

지금 생각해보니 그러네;;

 

앱을 빠르게 다른 애가 만든거 가져다 만든다

일단 그렇게 이해하고 시작해보자

 

뜬금없지만 저번주에 차장님께서 톰캣을 만들어보라 하셨는데

헐 혹시 app = FastAPI는 서버 만드는.. 리스닝 하는 놈 인건가 하는 생각이 빠르게 뇌리를 스쳐갔다.

 

하지만 땡! 

 

결론부터 말하면 제미나이 왈

app = FastAPI()는 톰캣 그 자체가 아니라, 톰캣 위에 올라가는 '서블릿(Servlet)'이나 'Srping 애플리케이션'에 가깝다.

서블릿..

예전에 뉴렉처 선생님 강의에서 들었던 그 개념이 떠올랐다 기능구현 하는 작은 단위 컨트롤러?

---

1. 일단은 한번 사용하고 이해해보자고!

: 자네 이미 아는 내용이고 지루하다면 이건 제껴.

 

 FastAPI를 설치하는 과정은 아주 간단하다.

하지만 단순히 라이브러리만 설치하는 게 아니라, 서버를 실행할 ASGI 서버(Uvicorn)와 프로젝트 환경을 깨끗하게 유지할 가상 환경을 함께 세팅하는 것이 정석이다.

---

1.1. 가상 환경 만들기 (권장)

 

 다른 프로젝트들과 라이브러리 버전이 꼬이는 것을 방지하기 위해 가상 환경을 먼저 만드는 것이 좋다.

터미널(또는 CMD)에서 프로젝트 폴더로 이동 후 아래 명령어를 입력한다.

 

- Windows :

python -m venv venv
venv\Scripts\activate

 

- Mac/Linux :

python3 -m venv venv
source venv/bin/activate

---

1.2. FastAPI 및 Uvicorn 설치

 

 FastAPI는 웹 프레임워크이고, 이를 실제로 구동하려면 Uvicorn이라는 서버 소프트웨어가 필요하다.

한 번에 설치하려면 아래 명령어를 사용하면 된다.

pip install "fastapi[standard]"

 

참고: [standard]를 붙이면 Uvicorn을 포함해 개발에 필요한 표준 의존성 파일들이 한꺼번에 설치된다.

만약 최소한의 패키지만 원한다면 pip install fastapi uvicorn으로 각각 설치하면 된다.

---

1.3. 설치 확인 및 코드 테스트

 

 설치가 잘 되었는지 확인하기 위해 main.py 파일을 만들고 아래 코드를 복사해 넣는다.

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

 

그 후 터미널에서 다음 명령어로 서버를 실행하면

fastapi dev main.py

---

1.4. 결과 확인

1. 브라우저를 열고 http://127.0.0.1:8000에 접속했을 때 {"Hello": "World"}가 보이면 성공이다. 축하해~
2. http://127.0.0.1:8000/docs에 접속해봐라. FastAPI가 자동으로 생성해 준 Swagger UI(대화형 API 문서)를 바로 확인할 수 있다.

혹시 설치 중에 빨간색 에러 메시지가 뜨거나 파이썬 경로 문제로 고생하고 있는가?

미안 그건 내 소관이 아닌 것 같아...

---

2. FastAPI vs Tomcat: 이 중에 누가 진짜 서버인가?

Java 진영과 비교해보면 역할 분담이 명확하게 보일지도...?

역할	Java/Spring 환경	Python/FastAPI 환경
애플리케이션(로직)	Spring Boot / Servlet	app = FastAPI()
서버(엔진)	Apache Tomcat	Uvicorn (또는 Gunicorn)

 

- app = FastAPI() : 이 코드는 "어떤 URL로 들어오면 어떤 함수를 실행할지" 정의하는 설계도(애플리케이션)을 만드는 것이다.

- Uvicorn : 아까 터미널에서 실행한 fastapi dev나 uvicorn main:app 명령어가 실제 톰캣의 역할을 수행한다. 이 친구가 네트워크 포트를 열고(Listening), 클라이언트의 요청을 기다렸다가 FastAPI 앱에 전달해준다.

---

2. "리스닝(Listening)"은 누가 할까?

 엄밀히 말하면 Uvicorn(ASGI 서버)이 리스닝을 담당한다.

1. Uvicorn이 8000번 포트를 열고 대기한다.

2. 사용자가 접속하면 Uvicorn이 그 신호를 잡는다.

3. Uvicorn은 받은 데이터를 app(FastAPI 인스턴스)에 넘겨준다.

4. app이 로직을 처리해서 결과를 돌려주면, 다시 Uvicorn이 사용자에게 전달한다.

---

3. 왜 이렇게 나누어져 있는걸까?

* 참고용 : 이해를 돕기 위한 코드

// 1. 회원가입 서블릿
@WebServlet("/join")
public class JoinServlet extends HttpServlet {
    protected void doPost(HttpServletRequest request, HttpServletResponse response) {
        // [공통 로직: 지옥의 시작]
        // 1. 한글 인코딩 설정 (매번 해야 함)
        // 2. 파라미터 꺼내서 타입 변환 (String -> Int 등)
        // 3. 에러 발생 시 공통 에러 페이지 처리
        
        // [진짜 내 로직]
        // 회원가입 DB 저장...
    }
}

// 2. 로그인 서블릿
@WebServlet("/login")
public class LoginServlet extends HttpServlet {
    protected void doPost(HttpServletRequest request, HttpServletResponse response) {
        // [공통 로직: 또 써야 함]
        // 인코딩 설정, 파라미터 파싱, 세션 체크... (복사 붙여넣기)
        
        // [진짜 내 로직]
        // 로그인 확인...
    }
}

 

 과거에는 서버와 로직이 하나로 뭉쳐있기도 했지만, 지금은 역할을 분리하는 것이 표준이다.

덕분에 우리는 서버의 복잡한 네트워크 처리는 Uvicorn에게 맡기고, FastAPI로는 깔끔하게 비즈니스 로직(API 설계)에만 집중할수 있다.

 

참고: Spring Boot를 쓰실 때 톰캣이 내장되어 있어 하나처럼 느껴지는 것과 비슷하게, 최근 FastAPI도 fastapi dev 명령어를 통해 서버(Uvicorn)를 내장해서 실행해주기 때문에 더 헷갈릴 수 있다.

---

4. Spring vs FastAPI 개념 매칭

여기까지 제미나이의 설명을 읽다보니 드는 생각이

 

FastAPI() 그럼 이거 그냥 컨트롤러라는 말인가?라는 생각이 들었다.

 

자바 진영(Spring)의 개념으로 보면 FastAPI() 인스턴스는 전체 컨트롤러들을 관리하는 'DispatcherServlet'이자 Application context라고 보면 된다.

Spring (Java)	FastAPI (Python)	설명
@SpringBootApplication	app = FastAPI()	전체 앱의 설정과 진입점을 담당한다.
@RestController	router = APIRouter()	기능을 모듈화할 때 쓰는 단위이다.
@GetMapping("/path")	@app.get("/path")	특정 경로와 메서드를 매핑하는 데코레이터이다.

---

5. 왜 그냥 "컨트롤러"라고 느껴질까?

 FastAPI는 코드가 굉장히 간결해서, app = FastAPI() 선언 직후에 바로 @app.get("/") 같은 식으로 라우팅을 작성하곤 합니다.

그래서 마치 클래스 하나에 메서드 몇 개 있는 컨트롤러 객체처럼 보일 수 있다.

하지만 프로젝트 규모가 커지면 다음과 같이 분리하게 된다.

1. main.py: app = FastAPI()를 생성 (중앙 통제실)
2. items.py: router = APIRouter()를 생성 (Spring의 ItemController)
3. 연결: app.include_router(items.router) (중앙 통제실에 컨트롤러 등록)

---

6. 결론

지금 보고 있는 app 객체는 이 웹 서비스는 이런 API들을 가지고 있어라고 정의하는 전체 명세서이자 라우팅 시스템의 본체이다.

• 진짜 서버(리스닝 담당): Uvicorn
• 전체 앱 제어/라우팅: app = FastAPI()
• 세부 비즈니스 로직: def로 정의된 함수들

Spring의 DispatcherServlet이 요청을 받아서 적절한 @Controller로 넘겨주는 것처럼, app 객체가 그 역할을 내부적으로 수행한다고 이해하면 인생이 좀 편해질 것이다.