FastAPI 시리즈 9화 - Background Tasks: 비동기 작업을 우아하게 처리하는 방법

B컷개발자 2025. 5. 12. 16:30

728x90

FastAPI의 BackgroundTasks 기능을 활용해 비동기 후처리 작업을 효율적으로 구현하는 방법을 실습 중심으로 정리합니다. 이메일 발송, 로그 기록, 알림 전송 등 다양한 실전 예제를 포함합니다.

왜 Background Tasks가 필요한가?

실제 API 서비스에서는 다음과 같은 상황이 매우 흔하게 발생합니다.

사용자 요청 처리 후 추가로 이메일 발송
데이터베이스 기록 후 로그 파일 기록
요청과 동시에 푸시 알림 전송

이때 API 요청 응답이 느려지면 사용자 경험이 나빠집니다.
FastAPI의 BackgroundTasks는 이 문제를 간단하고 안전하게 해결합니다.
요청 처리가 끝난 후 별도의 스레드에서 비동기 작업을 실행합니다.

1. 기본 사용법

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", mode="a") as log_file:
        log_file.write(f"{message}\n")

@app.post("/send-message/")
def send_message(background_tasks: BackgroundTasks, message: str):
    background_tasks.add_task(write_log, f"Message sent: {message}")
    return {"status": "Message received"}

add_task()로 작업 등록
API 응답 후 별도의 작업 스레드에서 write_log() 실행
사용자 입장에서는 요청이 즉시 완료되므로 UX 개선

2. 다양한 함수와 매개변수 전달

def notify_user(email: str, message: str):
    print(f"Send email to {email}: {message}")

@app.post("/notify/")
def notify(background_tasks: BackgroundTasks, email: str, message: str):
    background_tasks.add_task(notify_user, email, message)
    return {"status": f"Notification queued for {email}"}

add_task()는 함수와 파라미터를 자유롭게 조합 가능
이메일 발송, SMS 전송, 슬랙 알림 등 다양한 후처리 작업에 활용

3. BackgroundTasks + Depends 결합 예시

from fastapi import Depends

def get_logger(background_tasks: BackgroundTasks):
    def log_action(action: str):
        background_tasks.add_task(write_log, f"Action: {action}")
    return log_action

@app.get("/items/{item_id}")
def read_item(item_id: int, log_action=Depends(get_logger)):
    log_action(f"Read item {item_id}")
    return {"item_id": item_id}

Depends()를 활용해 의존성 주입 + 비동기 작업을 동시에 처리
코드 재사용성과 테스트 유연성 모두 확보

4. 실전 활용 패턴

✅ 추천 시나리오

활용 사례 설명

이메일 발송	회원가입, 주문 완료 등
슬랙/푸시 알림	실시간 알림 처리
외부 API 호출	사용자 응답과 별개로 비동기 요청
로깅	상세 트랜잭션 기록

❗ 주의 사항

BackgroundTasks는 서버 프로세스 내에서 실행
서버 재시작, 장애 발생 시 작업 유실 가능
장기 작업, 중요 작업은 Celery 등 외부 작업 큐를 권장

5. BackgroundTasks와 Celery의 차이

기능 BackgroundTasks Celery

실행 위치	FastAPI 내부 스레드	외부 워커 서버
신뢰성	낮음 (재시작 시 손실)	높음 (persistent queue)
설정 복잡도	매우 간단	다소 복잡
적합한 작업	짧고 가벼운 작업	장시간, 중요 작업

FastAPI 자체만으로도 가벼운 후처리 작업은 충분히 처리 가능합니다.

정리 – 실무 API UX를 혁신하는 비동기 후처리

FastAPI의 BackgroundTasks는 다음과 같은 장점이 있습니다:

API 응답 속도를 늦추지 않고 부가 작업 처리
선언형 코드로 간편하게 구현
로깅, 알림, 외부 요청 등 실무 활용도가 매우 높음
Depends()와 결합해 아키텍처화 가능

이러한 특성 덕분에 FastAPI가 현대적 API 프레임워크로 평가받는 핵심 이유 중 하나입니다.

다음 글 예고

FastAPI 시리즈 10화 - 파일 업로드 및 다운로드 기능 구현하기
에서는 REST API에서 자주 요구되는 기능인
파일 업로드, 멀티 파일 처리, 파일 다운로드를 FastAPI로 쉽게 구현하는 방법을 다룹니다.

728x90