Python FastAPI - 0 [준비]

LshDevLog·2026년 4월 26일

python

목록 보기

14/16

FastAPI는 Python으로 REST API 및 웹 백엔드를 만들기 위한 프레임워크
Flask처럼 간결하게 API를 만들 수 있음
비동기 처리 기반으로 높은 처리량을 기대할 수 있음
타입 힌트 기반 자동 검증/자동 문서화로 인한 높은 생산성
FastAPI로 웹 서버를 개발해보면서 FastAPI와 이에 필요한 기술들을 함께 공부해보려함

세팅

python -m venv .venv

venv 가상환경에서 진행하려함

pip install fastapi uvicorn

FastAPI 자체는 프레임워크이고 서버를 실행하려면 ASGI 서버가 필요함
- ASGI (Asynchronous Server Gateway Interface)
  - Python 웹 서버와 Python 웹 애플리케이션이 통신하기 위한 약속
  - FastAPI는 직접 인터넷 요청을 받지 않음
  - 앞에서 ASGI 서버가 요청을 받고 Python 앱에 전달하는 방식
  - 클라이언트와 직접 통신 -> ASGI 서버(uvicorn)
  - 요청을 처리하는 코드 -> Python 앱(FastAPI)
  - 기능
    - 비동기 지원
    - HTTP 지원
    - WebSocket 지원
    - Lifespan 이벤트 지원
      - Lifespan은 ASGI 앱의 시작(startup)과 끝(shutdown)을 관리하는 시스템
  - 수행 순서
    - 클라이언트 요청을 받음
    - HTTP 요청을 ASGI 형식으로 변환
    - FastAPI 같은 앱에게 전달
    - 앱이 만든 응답을 받음
    - 클라이언트에게 HTTP 응답으로 돌려줌
대표적인 ASGI 서버인 uvicorn을 함께 설치

uvicorn main:app --reload

uvicorn 서버를 실행하는 명령어
- main: main.py 파일
- app: FastAPI() 객체 이름
- --reload: 코드 변경 시 서버 자동 재시작 (개발용)

# 서버 실행 실패

$ uvicorn main:app --reload
INFO:     Will watch for changes in these directories: ['C:\\PythonProject']
ERROR:    [WinError 10013] 액세스 권한에 의해 숨겨진 소켓에 액세스를 시도했습니다

# 서버 실행 성공

$ uvicorn main:app --reload --port 8080
INFO:     Will watch for changes in these directories: ['C:\\PythonProject']
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
INFO:     Started reloader process [21844] using StatReload
INFO:     Started server process [19404]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

WinError 10013
- uvicorn이 서버 포트를 열려고 했지만 Windows가 해당 소켓 접근을 막아서 생기는 에러
- uvicorn의 기본 포트는 8000
- 포트 변경으로 해결

기본 구조

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return "Hello World!"

FastAPI()
- FastAPI 애플리케이션 객체
- 서버 앱 생성, 라우팅 등록, 요청 처리 등을 담당
@app.get("/")
- 라우팅 등록하는 데코레이터
def home()
- 요청이 들어왔을때 실행될 함수
  - 컨트롤러 함수 or 핸들러 함수 or 엔드포인트 함수라고도 부름
return "Hello World!"
- 문자열을 반환하면 FastAPI가 JSON 문자열 응답으로 변환
- FastAPI가 자동으로 HTTP Response로 바꿔줌
  - 실제 응답
    - 200 OK
      Content-Type: application/json
      "Hello World!"

자동 API 문서

FastAPI는 라우팅 정보, 타입 힌트, Pydantic 모델을 기반으로 OpenAPI 명세(JSON)을 자동 생성하고 이를 Swagger UI / ReDoc 화면으로 보여줌
- OpenAPI
  - REST API의 엔드포인트, 요청값, 응답값, 인증 방식 등을 표준 형식(JSON/YAML)으로 기술하는 국제 표준 명세
기본적으로 /docs, /redoc 두 가지 문서 페이지 제공

docs

http://127.0.0.1:8080/docs

URL 맨 뒤에 /docs 입력
Swagger UI 사용함
- 개발 중 테스트와 디버깅에 많이 사용
- 직접 API 호출 가능
- Try it out 버튼 있음
  - Try it out 버튼을 누르면 브라우저에서 직접 API 요청을 보내 테스트할 수 있음
- 개발자가 많이 씀

ReDoc

http://127.0.0.1:8080/redoc

URL 맨 뒤에 /redoc 입력
ReDoc
- 읽기 좋은 문서형 UI
- 디자인 깔끔
- API 설명서 배포용으로 좋음
- 고객/협업용 문서 느낌

설정

app = FastAPI(docs_url="/swagger",
              redoc_url="/api-docs")

/swagger
/api-docs

URL 변경 가능

app = FastAPI(docs_url=None,
              redoc_url=None)

끌 수 있음
운영 환경에서는 내부 API 구조 노출을 방지하기 위해 비활성화하기도 함

프로젝트 구조 잡기

작은 프로젝트

project/
│
├── main.py
└── requirements.txt

단일 Python 파일 구조

조금 커진 프로젝트

project/
│
├── app/
│   ├── main.py
│   ├── routers/
│   │   └── user_router.py
│   ├── schemas/
│   │   └── user_schema.py
│   ├── services/
│   │   └── user_service.py
│   └── models/
│       └── user_model.py
│
└── requirements.txt