FastAPI 완전 정리

1. FastAPI란?

FastAPI : Python으로 작성된 웹 프레임워크

• 이름 그대로 빠르고(Fast), 자동화가 잘 되어 있으며, 타입 안정성이 강한 것이 특징
• Python의 async/await 비동기 처리를 기반으로 설계되어 고성능 API 서버를 쉽게 만들 수 있음

특징 요약

특징	설명
빠른 속도	Node.js나 Go 수준의 처리 속도를 목표로 설계
자동 문서화	Swagger(UI)와 ReDoc 문서를 자동 생성
타입 힌트 기반	Python의 typing을 이용해 데이터 검증 자동화
데이터 검증	pydantic을 이용해 입력 데이터 타입을 자동 검증
표준 규격	OpenAPI, JSON Schema 표준을 따름
비동기 지원	async/await을 완벽히 지원

---

2. FastAPI의 역할

FastAPI는 API 서버를 만들기 위한 도구
즉, 클라이언트(웹, 앱 등)의 요청을 받아서 데이터를 가공하고 응답하는 역할

예시 구조

[React / Android 앱] → HTTP 요청 → [FastAPI 서버] → DB 또는 AI 연동 → 응답(JSON)

FastAPI는 이러한 백엔드 API 서버의 역할을 수행

---

3. 설치 방법

1) 기본 설치

pip install fastapi uvicorn

2) 권장 (Poetry로 관리)

poetry add fastapi uvicorn

uvicorn은 FastAPI 앱을 실행시키는 서버 역할
(예: Spring Boot의 Tomcat 같은 역할)

---

4. 기본 구조

프로젝트 기본 구조 예시

myproject/
├── src/
│   ├── main.py          # FastAPI 실행 진입점
│   ├── api/
│   │   └── routes.py    # 엔드포인트 정의
│   └── config/
│       └── settings.py  # 환경 변수 관리
├── .env
├── pyproject.toml
└── Dockerfile

---

5. 기본 코드 예시

src/main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "FastAPI 서버가 실행 중입니다."}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "name": "홍길동"}

@app.post("/register")
def register_user(user: dict):
    return {"message": "사용자 등록 완료", "data": user}

실행

uvicorn src.main:app --reload

• src.main:app → main.py 안의 app 객체를 실행
• --reload → 코드 변경 시 자동 재시작

실행 후 접속:

• API: http://127.0.0.1:8000
• 문서: http://127.0.0.1:8000/docs

---

6. 요청과 응답 처리

GET 요청 예시

@app.get("/items/")
def read_item(q: str | None = None):
    return {"query": q}

요청:
GET /items/?q=apple
응답:
{"query": "apple"}

---

POST 요청 예시 (데이터 전송)

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return {"name": item.name, "price": item.price}

요청(JSON):

{
  "name": "keyboard",
  "price": 39.99
}

응답:

{
  "name": "keyboard",
  "price": 39.99
}

---

7. 데이터 검증 (Pydantic)

FastAPI는 pydantic을 이용해 입력 데이터를 자동 검증

예시:

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(..., min_length=2)
    age: int = Field(..., ge=0, le=120)

요청 시 age가 음수면 자동으로 422 Unprocessable Entity 에러를 반환

---

8. 환경 변수 관리 (settings.py)

Spring Boot의 application.properties와 동일한 역할을 합니다.

src/config/settings.py

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    DB_HOST: str | None = None
    DB_PORT: int | None = 5432
    DB_NAME: str | None = None
    DB_USERNAME: str | None = None
    DB_PASSWORD: str | None = None

    class Config:
        env_file = ".env"

settings = Settings()

main.py에서 사용

from src.config.settings import settings

@app.get("/db-info")
def get_db_info():
    return {"host": settings.DB_HOST, "name": settings.DB_NAME}

---

9. 데이터베이스 연동 (SQLAlchemy 예시)

from sqlalchemy import create_engine
from src.config.settings import settings

DATABASE_URL = f"postgresql://{settings.DB_USERNAME}:{settings.DB_PASSWORD}@{settings.DB_HOST}:{settings.DB_PORT}/{settings.DB_NAME}"
engine = create_engine(DATABASE_URL)

@app.get("/db-check")
def db_check():
    try:
        with engine.connect() as conn:
            return {"status": "connected"}
    except Exception as e:
        return {"status": "error", "detail": str(e)}

---

10. 실행 및 배포

로컬 실행

uvicorn src.main:app --reload

Docker 빌드 및 실행

docker build -t my-fastapi-app .
docker run -d -p 8000:8000 my-fastapi-app

EC2에서 실행

1. 포트 8000 오픈
2. GitHub Actions로 자동 배포
3. Nginx Reverse Proxy로 도메인 연결 (ai.winnerteam.store → 127.0.0.1:8000)

---

11. 문서 자동화

FastAPI는 Swagger와 ReDoc 문서를 자동 제공합니다.

문서 종류	경로
Swagger UI	/docs
ReDoc	/redoc

Swagger에서는 API 테스트까지 가능하기 때문에 Postman 없이도 확인가능

---

12. 비동기 처리 예시

FastAPI는 async/await를 지원

import asyncio

@app.get("/delay")
async def delayed_response():
    await asyncio.sleep(3)
    return {"message": "3초 후 응답 완료"}

---

13. FastAPI가 적합한 경우

상황	이유
AI / LLM API 서버	비동기 처리와 JSON 응답 구조에 최적화
데이터 분석 서비스	Python 라이브러리 직접 사용 가능
프로토타입 / MVP	빠른 개발 속도
Microservice 구성	경량화된 서버 구조로 확장 용이

---

14. 정리

항목	FastAPI 역할
서버 실행	uvicorn src.main:app
라우팅	@app.get, @app.post
데이터 검증	pydantic.BaseModel
설정 관리	.env + settings.py
문서 자동화	Swagger (/docs)
배포	Docker + GitHub Actions + EC2
도메인 연결	Nginx Reverse Proxy

---