[FastAPI] FastAPI 개발하기 1- 환경 셋팅 및 실행명령어

최근 프로젝트를 진행하면서 검색 로직을 FastAPI 기반 API 서버로 구현하고, 이를 Docker 이미지로 만들어 서버에 띄우는 과정까지 경험하게 되었다.

단순한 튜토리얼 수준이 아니라, 실제 서비스 환경을 고려한 구조 설계와 실행 방식을 기준으로 정리해두면 이후 유사한 API를 만들 때 큰 도움이 될 것이라 판단하여 이 글을 작성한다

 

FastAPI는 Django처럼 정해진 프로젝트 구조를 강제하지 않는다.

자유도가 대신, 프로젝트 규모가 커질수록 개발자가 직접 구조를 설계해야 한다.

 

그래서 개발자들마다 스타일이 작업 구조가 다양하지만 나는 코드가 그리 길지 않았고, 서비스마다 각각의 컨테이너를 띄우고 하나의 yml로 관리를 하는 방향이라 오히려 너무 폴더를 나누면 코드가 불필요하게 분산되는 느낌이 들었다.

 

그래서 이 글에서는

• 과도하게 복잡하지 않으면서
• 서비스 코드로 사용하기에 충분한 FastAPI 프로젝트 구조와 실행 흐름을 중심으로 설명한다.

---

1. FastAPI란 무엇인가

FastAPI는 파이썬 기반의 고성능 웹 API 프레임워크이다.

ASGI(Asynchronous Server Gateway Interface)를 기반으로 하여 비동기 처리를 지원한다.

공식문서 : https://fastapi.tiangolo.com/ko/

FastAPI

 

FastAPI의 주요 특징은 다음과 같다.

• Python type hint 기반 API 정의
• Pydantic을 이용한 자동 데이터 검증
• Swagger(OpenAPI) 문서 자동 생성
• uvicorn과 같은 ASGI 서버와 함께 사용
• 높은 성능과 간결한 코드 구조

즉, “빠르고, 타입이 안전하며, 문서가 자동으로 만들어지는 API 프레임워크”이다.

---

2. FastAPI 개발 환경 세팅 및 필수 패키지 설치

2-1. 가상 환경 활성화

FastAPI는 일반적으로 가상 환경에서 설치하여 사용한다.
가상 환경은 프로젝트별 라이브러리 충돌을 방지하기 위해 필수적이다.

python -m venv venv
source venv/bin/activate   # Linux / macOS

 

2-2. 필수 패키지 설치

FastAPI 애플리케이션을 실행하기 위해서는 최소 두 가지 패키지가 필요하다.

 

2-1. FastAPI 설치

pip install fastapi

• API 라우팅
• Request / Response 처리
• Swagger 문서 자동 생성

을 담당하는 핵심 프레임워크이다.

 

2-2. Uvicorn 설치

pip install uvicorn

• Uvicorn은 ASGI 서버로 비동기 호출을 지원하며 FastAPI의 기본 실행 서버로 사용
• FastAPI 애플리케이션을 실제로 실행시키는 역할

FastAPI는 서버가 아니며,
FastAPI (애플리케이션) + Uvicorn (서버) 조합으로 실제 웹 서버가 구성된다.

 

---

3. FastAPI 디렉토리 구조 

이번 검색 API 프로젝트는 다음과 같은 구조를 가진다.

search_app/
├── main.py          # FastAPI 애플리케이션 진입점 (라우터 정의 위치)
├── schemas.py       # Request / Response 스키마 (Pydantic 모델)
└── services/        # 비지니스 로직 + DB접근계층 등 실제 검색 로직
    └── search.py
├── requirements.txt # 패키지 의존성 관리
└── search_api.log   # 애플리케이션 로그 파일

---

3-1. main.py – API 엔트리포인트

main.py는 HTTP 요청을 받는 역할만 담당한다.

• FastAPI 앱 생성
• 미들웨어(CORS) 설정
• API 라우터 정의
• 요청 → 서비스 계층 호출 → 응답 반환
• 로깅 초기화

3-2. schemas.py – API 계약 정의

schemas.py는 Pydantic 기반의 Request / Response 모델을 정의한다.

• 요청 JSON 구조 고정
• 응답 JSON 구조 고정
• 자동 validation
• Swagger 문서 자동 생성

즉, 프론트엔드와 백엔드가 협업할 때,  이 파일은 사실상 API 계약서 역할을 한다.

 

3-3. services/search.py – 비즈니스 로직

services 폴더에는 실제 검색 로직이 들어간다.

이 계층의 중요한 특징은 다음과 같다.

• FastAPI에 대한 의존성이 없음
• HTTP 개념(Request, Response)을 모름
• 다른 환경(CLI, 배치, 테스트 코드)에서도 재사용 가능

즉,“API 서버가 바뀌어도 그대로 쓸 수 있는 코드”로 설계하는 것이 목표이다.

---

4. FastAPI  동작 원리 및 실행

4-1. 기본구조 및 동작원리

FastAPI 애플리케이션의 기본 구조는 다음과 같다.

from fastapi import FastAPI

app = FastAPI(
    title="직원 검색 서비스",
    version="1.0.0",
    description="직원 정보 키워드 검색 API",
)

@app.get("/")
async def root():
    """루트 엔드포인트 (헬스 체크)"""
    return {
        "service": "직원 검색 서비스",
        "version": "1.0.0",
        "status": "running"
    }

 

• FastAPI() : 애플리케이션 객체 생성
• @app.get() : HTTP GET 라우팅
• async def : 비동기 엔드포인트 함수

 

---

 

FastAPI는 다음 순서로 요청을 처리한다.

1. HTTP 요청 수신
2. Request Body를 Pydantic 모델로 파싱
3. 타입 및 제약 조건 검증
4. 엔드포인트 함수 실행
5. 반환 객체를 Response 모델로 직렬화
6. JSON 응답 반환

---

4-2. 서버 실행 명령어

FastAPI 서버는 다음 명령어로 실행한다.

uvicorn main:app --host 0.0.0.0 --port 8003

• main : main.py
• app : FastAPI 인스턴스 이름
• 0.0.0.0 : 외부 접근 허용
• 8003 : 서비스 포트

실제 서버 환경에서는 --reload 옵션을 제거하고 실행한다.

---

5. Swagger 자동 문서

FastAPI는 다음 URL에서 Swagger UI를 자동 제공한다.

http://서버주소:포트번호/docs

Swagger UI에서는 다음이 가능하다.

• 전체 API 목록 확인
• Request Body 자동 입력
• 실시간 API 테스트
• Response 스키마 확인

별도의 문서 작업 없이도 API 명세가 자동으로 관리 된다는 점이 가장 큰 장점이다!!!

---

마무리

FastAPI는 작은 API부터 서비스 규모의 서버까지 모두 커버 가능한 프레임워크이다.
중요한 것은 프레임워크보다 구조 설계이다.

• API는 얇게
• 로직은 독립적으로
• 검증과 문서는 자동화

이 원칙만 지켜도 FastAPI는 매우 강력한 도구가 된다.

이 글이 FastAPI로 실제 서비스를 구성하려는 개발자에게 하나의 현실적인 기준점이 되기를 바란다.