[Python] FastAPI 비동기 처리(1) 비동기 엔드포인트 만들기

안녕하세요.

이전 글에서는 FastAPI를 사용해서 api서버를 만들고 의존성 주입을 활용하는 방법에 대해 알아보았습니다.

2025.05.01 - [Python] - [Python] FastAPI 프레임워크로 api서버 만들기

[Python] FastAPI 프레임워크로 api서버 만들기

2025.05.08 - [Python] - [Python]FastAPI의 의존성 주입(Dependency Injection) 활용하기

[Python]FastAPI의 의존성 주입(Dependency Injection) 활용하기

 

FastAPI는 파이썬의 최신 비동기 기능을 쉽고 강력하게 활용할 수 있는 웹 프레임워크입니다.

이 글에서는 FastAPI에서 비동기 엔드포인트를 만드는 방법과 비동기의 장점 및 주의사항에 대해 알아보겠습니다.

1. 비동기(Asynchronous)란?

비동기란, 프로그램이 어떤 작업을 처리하는 동안 다른 작업도 동시에 진행할 수 있도록 하는 방식입니다.

• 동기(Synchronous):
  한 작업이 끝날 때까지 다음 작업을 시작하지 않음
• 비동기(Asynchronous):
  대기 시간이 발생하는 작업(I/O 등) 중에도
  다른 작업을 병렬로 처리 가능

비동기 처리는 주로 네트워크 요청, 파일 입출력, 데이터베이스 쿼리 등 외부 자원과의 통신에서 효율성을 극대화할 수 있습니다.

 

2. FastAPI에서 비동기 엔드포인트 만들기

FastAPI에서는 엔드포인트 함수를 async def로 선언하면 비동기 처리가 가능합니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
async def hello():
    return {"message": "비동기 엔드포인트 예시입니다."}

• 함수 앞에 async를 붙이면 비동기 함수가 됩니다.
• FastAPI는 내부적으로 비동기 처리를 지원하는 서버(Uvicorn 등)와 함께 동작합니다.

3. 동기 함수와의 차이

동기 함수는 일반적으로 def로 선언합니다.

@app.get("/sync-hello")
def sync_hello():
    return {"message": "동기 엔드포인트 예시입니다."}

 

비동기 함수와 동기 함수 모두 FastAPI에서 동작하지만, I/O 작업이 많은 경우 비동기 함수가 더 많은 요청을 효율적으로 처리할 수 있습니다.

 

4. 비동기 엔드포인트의 실전 예시

아래는 비동기 함수에서 실제로 대기 작업을 처리하는 예시입니다.

import asyncio
from fastapi import FastAPI

app = FastAPI()

@app.get("/wait")
async def wait_example():
    await asyncio.sleep(3)  # 3초 대기 (비동기)
    return {"message": "3초 후 응답"}

• await asyncio.sleep(3)은 3초 동안 대기하지만, 서버는 이 시간 동안에도 다른 요청을 동시에 처리할 수 있습니다.

import time

@app.get("/sync-wait")
def sync_wait_example():
    time.sleep(3)  # 3초 동안 대기
    return {"message": "3초 후 응답 (동기)"}

• 동기 함수에서는 time.sleep(3)을 사용하지만, 이 경우 서버 전체가 3초 동안 멈춰서 다른 요청을 처리할 수 없습니다.
  
  

5. 언제 비동기를 사용해야 하는가?

• 외부 API 호출, 데이터베이스 쿼리, 파일 입출력 등
  대기 시간이 발생하는 작업이 있을 때 비동기 처리가 효과적입니다.
• 계산량이 많은 작업(CPU 바운드)은 비동기보다는 멀티프로세싱 등
  다른 방식이 더 적합할 수 있습니다.

5. 비동기 엔드포인트 사용 시 주의사항

• 외부 API 호출, 데이터베이스 쿼리, 파일 입출력 등 대기 시간이 발생하는 작업이 있을 때 비동기 처리가 효과적입니다.
• CPU 바운드 작업(예: 복잡한 계산)은 비동기보다 별도의 워커나 멀티프로세싱이 더 적합합니다.
• 엔드포인트 함수 내에서 동기 라이브러리(예: requests, sqlite3 등)를 사용하면 비동기의 장점이 사라질 수 있습니다.
  → 비동기 라이브러리(예: httpx, asyncpg 등) 사용 권장