Python FastAPI 백그라운드 작업: 글로벌 애플리케이션을 위한 비동기 작업 실행 마스터하기

오늘날의 상호 연결된 디지털 환경에서 많은 양의 요청을 효율적으로 처리할 수 있는 애플리케이션을 구축하는 것이 가장 중요합니다. 글로벌 애플리케이션, 특히 다양한 사용자 기반과 지리적으로 분산된 운영을 처리하는 애플리케이션의 경우 성능과 응답성은 바람직할 뿐만 아니라 필수적입니다. 빠른 속도와 개발자 생산성으로 유명한 Python의 FastAPI 프레임워크는 기본 요청-응답 주기를 차단해서는 안 되는 작업을 관리하기 위한 강력한 솔루션을 제공합니다. 바로 백그라운드 작업입니다.

이 종합 가이드는 FastAPI의 백그라운드 작업을 자세히 살펴보고 작동 방식, 비동기 작업 실행에 중요한 이유, 효과적으로 구현하는 방법을 설명합니다. 다양한 시나리오를 다루고, 인기 있는 작업 큐 라이브러리와의 통합을 살펴보고, 확장 가능하고 고성능 글로벌 웹 서비스를 구축하기 위한 실행 가능한 통찰력을 제공합니다.

백그라운드 작업의 필요성 이해

애플리케이션에서 사용자가 시간이 오래 걸리는 작업을 시작한다고 상상해 보세요. 이는 서로 다른 대륙에 걸쳐 수천 명의 구독자에게 대량 이메일 보내기, 대용량 이미지 업로드 처리, 복잡한 보고서 생성 또는 다른 시간대의 원격 서비스와 데이터 동기화 등 모든 것이 될 수 있습니다. 이러한 작업이 요청 처리기 내에서 동기적으로 수행되면 전체 작업이 완료될 때까지 사용자의 요청이 보류됩니다. 이로 인해 다음과 같은 문제가 발생할 수 있습니다.

• 저조한 사용자 경험: 사용자가 장시간 기다리게 되어 불만을 느끼고 잠재적으로 애플리케이션을 포기하게 됩니다.
• 중단된 이벤트 루프: FastAPI(asyncio 사용)와 같은 비동기 프레임워크에서 차단 작업은 전체 이벤트 루프를 중단시켜 다른 요청이 처리되지 않도록 할 수 있습니다. 이는 확장성과 처리량에 심각한 영향을 미칩니다.
• 증가된 서버 로드: 장기 실행 요청은 서버 리소스를 묶어 애플리케이션이 효과적으로 서비스할 수 있는 동시 사용자 수를 줄입니다.
• 잠재적 시간 초과: 네트워크 중개자 또는 클라이언트는 응답을 기다리는 동안 시간이 초과되어 불완전한 작업과 오류가 발생할 수 있습니다.

백그라운드 작업은 이러한 장기 실행의 중요하지 않은 작업을 기본 요청 처리 프로세스와 분리하여 우아한 솔루션을 제공합니다. 이를 통해 API는 작업이 시작되었음을 확인하면서 사용자에게 신속하게 응답할 수 있으며 실제 작업은 백그라운드에서 비동기적으로 수행됩니다.

FastAPI의 내장 백그라운드 작업

FastAPI는 간단한 사용 사례를 위해 외부 종속성 없이 백그라운드에서 작업을 실행할 수 있는 간단한 메커니즘을 제공합니다. `BackgroundTasks` 클래스는 이러한 용도로 설계되었습니다.

`BackgroundTasks` 작동 방식

요청이 FastAPI 애플리케이션에 들어오면 `BackgroundTasks`의 인스턴스를 경로 작업 함수에 주입할 수 있습니다. 이 객체는 응답이 클라이언트로 전송된 후 실행되어야 하는 함수를 보관하는 컨테이너 역할을 합니다.

다음은 기본 구조입니다.

            from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email_background(email: str, message: str):
    # Simulate sending an email
    print(f"Simulating sending email to {email} with message: {message}")
    # In a real application, this would involve SMTP or an email service API.
    # For global applications, consider time zone aware sending and retry mechanisms.

@app.post("/send-notification/{email}")
async def send_notification(email: str, message: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email_background, email, message)
    return {"message": "Notification sent in background"}

            

              
                Copy
              
            
          

이 예제에서는 다음과 같습니다.

• 작업에 대한 로직을 포함하는 `send_email_background` 함수를 정의합니다.
• `BackgroundTasks`를 경로 작업 함수 `send_notification`에 매개 변수로 주입합니다.
• `background_tasks.add_task()`를 사용하여 `send_email_background`가 실행되도록 예약합니다. 작업 함수에 대한 인수는 `add_task`에 대한 후속 인수로 전달됩니다.
• API는 클라이언트에 즉시 성공 메시지를 반환하고 이메일 전송 프로세스는 백그라운드에서 계속됩니다.

`BackgroundTasks`에 대한 주요 고려 사항

• 프로세스 수명 주기: `BackgroundTasks`를 통해 추가된 작업은 FastAPI 애플리케이션과 동일한 Python 프로세스 내에서 실행됩니다. 애플리케이션 프로세스가 다시 시작되거나 충돌하면 보류 중인 백그라운드 작업이 손실됩니다.
• 지속성 없음: 서버가 다운될 경우 실패한 작업을 다시 시도하거나 유지하기 위한 기본 제공 메커니즘이 없습니다.
• 복잡한 워크플로에 대한 제한 사항: 간단하고 즉시 실행되는 작업에는 훌륭하지만 분산 시스템, 상태 관리 또는 보장된 실행과 관련된 복잡한 워크플로에는 `BackgroundTasks`가 충분하지 않을 수 있습니다.
• 오류 처리: 백그라운드 작업 내의 오류는 기본적으로 기록되지만 클라이언트로 다시 전파되거나 초기 응답에 영향을 주지 않습니다. 작업 함수 내에서 명시적인 오류 처리가 필요합니다.

이러한 제한 사항에도 불구하고 FastAPI의 기본 `BackgroundTasks`는 특히 즉각적인 작업 완료가 중요하지 않은 애플리케이션에서 많은 일반적인 시나리오에서 응답성을 개선하기 위한 강력한 도구입니다.

외부 작업 큐를 사용해야 하는 경우

특히 까다로운 글로벌 환경에서 보다 강력하고 확장 가능하며 복원력이 뛰어난 백그라운드 작업 처리를 위해서는 전용 작업 큐 시스템과 통합하는 것이 좋습니다. 이러한 시스템은 다음과 같은 기능을 제공합니다.

• 분리: 작업은 웹 서버와 완전히 독립적인 별도의 작업자 프로세스에서 처리됩니다.
• 지속성: 서버 다시 시작 또는 실패 시에도 작업을 유지할 수 있도록 데이터베이스 또는 메시지 브로커에 작업을 저장할 수 있습니다.
• 재시도 및 오류 처리: 실패한 작업을 자동으로 재시도하고 오류를 처리하기 위한 정교한 메커니즘.
• 확장성: 작업 로드 증가를 처리하기 위해 웹 서버와 독립적으로 작업자 프로세스 수를 확장할 수 있습니다.
• 모니터링 및 관리: 작업 큐를 모니터링하고, 작업 상태를 검사하고, 작업자를 관리하는 도구.
• 분산 시스템: 작업이 다른 서비스에서 또는 다른 시스템에서 처리되어야 하는 마이크로서비스 아키텍처에 필수적입니다.

몇 가지 인기 있는 작업 큐 라이브러리가 Python 및 FastAPI와 원활하게 통합됩니다.

1. Celery

Celery는 Python에서 가장 인기 있고 강력한 분산 작업 큐 시스템 중 하나입니다. 매우 유연하며 RabbitMQ, Redis 또는 Amazon SQS와 같은 다양한 메시지 브로커와 함께 사용할 수 있습니다.

FastAPI로 Celery 설정

필수 조건:

• Celery 및 메시지 브로커(예: Redis)를 설치합니다.

            pip install celery[redis] 

            

              
                Copy
              
            
          

1. Celery 애플리케이션 파일(예: `celery_worker.py`)을 만듭니다.

            from celery import Celery

# Configure Celery
# Use a broker URL, e.g., Redis running on localhost
celery_app = Celery(
    'tasks',
    broker='redis://localhost:6379/0',
    backend='redis://localhost:6379/0'
)

# Optional: Define tasks here or import them from other modules
@celery_app.task
def process_data(data: dict):
    # Simulate a long-running data processing task.
    # In a global app, consider multi-language support, internationalization (i18n),
    # and localization (l10n) for any text processing.
    print(f"Processing data: {data}")
    # For internationalization, ensure data formats (dates, numbers) are handled correctly.
    return f"Processed: {data}"

            

              
                Copy
              
            
          

2. FastAPI 애플리케이션과 통합합니다(`main.py`):

            from fastapi import FastAPI
from celery_worker import celery_app  # Import your Celery app

app = FastAPI()

@app.post("/process-data/")
async def start_data_processing(data: dict):
    # Send the task to Celery
    task = celery_app.send_task('tasks.process_data', args=[data])
    return {"message": "Data processing started", "task_id": task.id}

# Endpoint to check task status (optional but recommended)
@app.get("/task-status/{task_id}")
async def get_task_status(task_id: str):
    task_result = celery_app.AsyncResult(task_id)
    return {
        "task_id": task_id,
        "status": str(task_result.status),
        "result": task_result.result if task_result.ready() else None
    }

            

              
                Copy
              
            
          

3. Celery 작업자를 실행합니다.

별도의 터미널에서 프로젝트 디렉터리로 이동하여 다음을 실행합니다.

            
celery -A celery_worker worker --loglevel=info

            

              
                Copy
              
            
          

4. FastAPI 애플리케이션을 실행합니다.

            
uvicorn main:app --reload

            

              
                Copy
              
            
          

Celery를 사용한 글로벌 고려 사항:

• 브로커 선택: 글로벌 애플리케이션의 경우 단일 실패 지점을 방지하기 위해 Amazon SQS 또는 관리형 Kafka 서비스와 같이 가용성이 높고 분산된 메시지 브로커를 고려하십시오.
• 시간대: 작업을 예약하거나 시간에 민감한 데이터를 처리할 때 애플리케이션 및 작업자에서 시간대를 일관되게 처리해야 합니다. UTC를 표준으로 사용하십시오.
• 국제화(i18n) 및 현지화(l10n): 백그라운드 작업에 콘텐츠(이메일, 보고서) 생성이 포함된 경우 다양한 지역에 맞게 현지화되었는지 확인하십시오.
• 동시성 및 처리량: 다양한 지역에서 예상되는 로드 및 사용 가능한 서버 리소스를 기반으로 Celery 작업자 수와 해당 동시성 설정을 조정합니다.

2. Redis Queue (RQ)

RQ는 Redis를 기반으로 구축된 Celery의 더 간단한 대안입니다. 더 작은 프로젝트에 선호되거나 덜 복잡한 설정이 필요한 경우가 많습니다.

FastAPI로 RQ 설정

필수 조건:

• RQ 및 Redis를 설치합니다.

            
pip install rq

            

              
                Copy
              
            
          

1. 작업 파일(예: `tasks.py`)을 만듭니다.

            import time

def send_international_email(recipient: str, subject: str, body: str):
    # Simulate sending an email, considering international mail servers and delivery times.
    print(f"Sending email to {recipient} with subject: {subject}")
    time.sleep(5) # Simulate work
    print(f"Email sent to {recipient}.")
    return f"Email sent to {recipient}"

            

              
                Copy
              
            
          

2. FastAPI 애플리케이션과 통합합니다(`main.py`):

            from fastapi import FastAPI
from redis import Redis
from rq import Queue

app = FastAPI()

# Connect to Redis
redis_conn = Redis(host='localhost', port=6379, db=0)

# Create an RQ queue
q = Queue(connection=redis_conn)

@app.post("/send-email-rq/")
def send_email_rq(
    recipient: str,
    subject: str,
    body: str
):
    # Enqueue the task
    task = q.enqueue(send_international_email, recipient, subject, body)
    return {"message": "Email scheduled for sending", "task_id": task.id}

# Endpoint to check task status (optional)
@app.get("/task-status-rq/{task_id}")
def get_task_status_rq(task_id: str):
    job = q.fetch_job(task_id)
    if job:
        return {
            "task_id": task_id,
            "status": job.get_status(),
            "result": job.result if job.is_finished else None
        }
    return {"message": "Task not found"}

            

              
                Copy
              
            
          

3. RQ 작업자를 실행합니다.

별도의 터미널에서:

            
python -m rq worker default

            

              
                Copy
              
            
          

4. FastAPI 애플리케이션을 실행합니다.

            
uvicorn main:app --reload

            

              
                Copy
              
            
          

RQ를 사용한 글로벌 고려 사항:

• Redis 가용성: 애플리케이션이 짧은 대기 시간 요구 사항으로 글로벌 청중에게 서비스를 제공하는 경우 Redis 인스턴스가 가용성이 높고 잠재적으로 지리적으로 분산되어 있는지 확인하십시오. 관리형 Redis 서비스가 좋은 옵션입니다.
• 확장성 제한: RQ가 더 간단하지만 분산 환경을 위한 Celery의 광범위한 툴링에 비해 확장에 더 많은 수동 노력이 필요할 수 있습니다.

3. 기타 작업 큐(예: Dramatiq, KafkaJS/Faust를 사용하는 Apache Kafka)

특정 요구 사항에 따라 다른 작업 큐 솔루션이 더 적합할 수 있습니다.

• Dramatiq: Celery의 더 간단하고 최신 대안으로 Redis 및 RabbitMQ도 지원합니다.
• Apache Kafka: 높은 처리량, 내결함성 및 스트림 처리 기능이 필요한 애플리케이션의 경우 Kafka를 백그라운드 작업에 대한 메시지 브로커로 사용할 수 있습니다. Faust와 같은 라이브러리는 Kafka를 기반으로 Python 스트림 처리 프레임워크를 제공합니다. 이는 특히 대규모 데이터 스트림이 있는 글로벌 애플리케이션과 관련이 있습니다.

글로벌 백그라운드 작업 워크플로 설계

글로벌 대상을 위한 백그라운드 작업 시스템을 구축할 때는 기본 구현 외에도 몇 가지 요소를 신중하게 고려해야 합니다.

1. 지리적 분포 및 대기 시간

전 세계 사용자가 다양한 위치에서 API와 상호 작용합니다. 웹 서버와 작업자의 배치는 성능에 큰 영향을 미칠 수 있습니다.

• 작업자 배치: 데이터 소스 또는 상호 작용하는 서비스와 지리적으로 더 가까운 지역에 작업자를 배포하는 것을 고려하십시오. 예를 들어, 작업에 유럽 데이터 센터의 데이터 처리가 포함된 경우 유럽에 작업자를 배치하면 대기 시간을 줄일 수 있습니다.
• 메시지 브로커 위치: 메시지 브로커가 모든 웹 서버 및 작업자 인스턴스에서 짧은 대기 시간으로 액세스할 수 있는지 확인하십시오. AWS SQS, Google Cloud Pub/Sub 또는 Azure Service Bus와 같은 관리형 클라우드 서비스는 글로벌 배포 옵션을 제공합니다.
• 정적 자산용 CDN: 백그라운드 작업에서 사용자가 다운로드하는 보고서 또는 파일을 생성하는 경우 CDN(콘텐츠 전송 네트워크)을 사용하여 이러한 자산을 전 세계적으로 제공합니다.

2. 시간대 및 예약

시간을 올바르게 처리하는 것은 글로벌 애플리케이션에 매우 중요합니다. 백그라운드 작업은 특정 시간에 예약하거나 다른 시간에 발생하는 이벤트를 기반으로 트리거해야 할 수 있습니다.

• UTC 사용: 항상 타임스탬프를 협정 세계시(UTC)로 저장하고 처리합니다. 표시 목적으로만 현지 시간대로 변환하십시오.
• 예약된 작업: 특정 시간에 작업을 실행해야 하는 경우(예: 매일 보고서) 예약 메커니즘이 다양한 시간대를 고려하는지 확인하십시오. 예를 들어 Celery Beat는 특정 시간에 전 세계적으로 작업을 실행하도록 구성할 수 있는 cron과 유사한 예약을 지원합니다.
• 이벤트 기반 트리거: 이벤트 기반 작업의 경우 이벤트 타임스탬프가 UTC로 표준화되었는지 확인하십시오.

3. 국제화(i18n) 및 현지화(l10n)

백그라운드 작업에서 이메일, 알림 또는 보고서와 같은 사용자에게 표시되는 콘텐츠를 생성하는 경우 현지화해야 합니다.

• i18n 라이브러리: Python i18n 라이브러리(예: `gettext`, `babel`)를 사용하여 번역을 관리합니다.
• 로캘 관리: 백그라운드 작업 처리에서 사용자의 선호 로캘을 결정하여 올바른 언어와 형식으로 콘텐츠를 생성할 수 있는지 확인하십시오.
• 형식 지정: 날짜, 시간, 숫자 및 통화 형식은 지역에 따라 크게 다릅니다. 강력한 형식 지정 로직을 구현합니다.

4. 오류 처리 및 재시도

네트워크 불안정, 일시적인 서비스 오류 또는 데이터 불일치로 인해 작업이 실패할 수 있습니다. 복원력이 뛰어난 시스템은 글로벌 운영에 매우 중요합니다.

• 멱등성: 가능한 경우 작업을 멱등성으로 설계합니다. 즉, 초기 실행 이후 결과를 변경하지 않고 여러 번 실행할 수 있습니다. 이는 안전한 재시도에 매우 중요합니다.
• 지수 백오프: 일시적인 문제를 겪고 있는 서비스를 압도하지 않도록 재시도에 대해 지수 백오프를 구현합니다.
• 데드레터 큐(DLQ): 중요한 작업의 경우 반복적으로 실패하는 작업을 캡처하도록 DLQ를 구성하여 기본 작업 큐를 차단하지 않고 수동 검사 및 해결이 가능하도록 합니다.

5. 보안

백그라운드 작업은 종종 중요한 데이터 또는 외부 서비스와 상호 작용합니다.

• 인증 및 권한 부여: 백그라운드에서 실행되는 작업에 필요한 자격 증명 및 권한이 있는지 확인하되 필요한 것 이상은 확인하지 마십시오.
• 데이터 암호화: 작업에서 중요한 데이터를 처리하는 경우 전송 중(서비스와 작업자 간) 및 저장 시(메시지 브로커 또는 데이터베이스) 모두 암호화되었는지 확인하십시오.
• 암호 관리: 백그라운드 작업자가 필요한 API 키, 데이터베이스 자격 증명 및 기타 암호를 관리하기 위한 보안 방법을 사용합니다.

6. 모니터링 및 관찰 가능성

백그라운드 작업 시스템의 상태와 성능을 이해하는 것은 문제 해결 및 최적화에 필수적입니다.

• 로깅: 타임스탬프, 작업 ID 및 관련 컨텍스트를 포함하여 작업 내에서 포괄적인 로깅을 구현합니다.
• 메트릭: 작업 실행 시간, 성공률, 실패율, 큐 길이 및 작업자 활용률에 대한 메트릭을 수집합니다.
• 추적: 분산 추적은 여러 서비스에서 요청 및 작업의 흐름을 시각화하는 데 도움이 되어 병목 현상과 오류를 쉽게 식별할 수 있습니다. Jaeger 또는 OpenTelemetry와 같은 도구를 통합할 수 있습니다.

FastAPI에서 백그라운드 작업을 구현하기 위한 모범 사례

FastAPI의 기본 제공 `BackgroundTasks`를 사용하든 외부 작업 큐를 사용하든 다음 모범 사례를 따르십시오.

• 작업을 집중적이고 원자적으로 유지: 각 백그라운드 작업은 단일하고 잘 정의된 작업을 수행하는 것이 좋습니다. 이렇게 하면 테스트, 디버그 및 재시도가 더 쉬워집니다.
• 실패를 위한 설계: 작업이 실패할 것이라고 가정합니다. 강력한 오류 처리, 로깅 및 재시도 메커니즘을 구현합니다.
• 종속성 최소화: 백그라운드 작업자는 작업을 효율적으로 수행하는 데 필요한 종속성만 가져야 합니다.
• 데이터 직렬화 최적화: API와 작업자 간에 복잡한 데이터를 전달하는 경우 효율적인 직렬화 형식(예: JSON, Protocol Buffers)을 선택합니다.
• 철저한 테스트: 작업 함수를 단위 테스트하고 FastAPI 앱과 작업 큐 간의 통신을 통합 테스트합니다.
• 큐 모니터링: 작업 큐, 작업자 성능 및 오류율의 상태를 정기적으로 확인합니다.
• 가능한 경우 작업 내에서 비동기 작업 사용: 백그라운드 작업에서 I/O 호출(예: 다른 API 또는 데이터베이스)을 해야 하는 경우 선택한 작업 큐 실행기가 이를 지원하는 경우 작업 함수 내에서 비동기 라이브러리(`httpx`를 사용하여 HTTP 요청 또는 `asyncpg`를 사용하여 PostgreSQL)를 사용합니다(예: 예약에 `countdown` 또는 `eta`를 사용하는 `apply_async`가 있는 Celery 또는 `gevent`/`eventlet` 작업자). 이렇게 하면 효율성을 더욱 높일 수 있습니다.

예제 시나리오: 글로벌 전자 상거래 주문 처리

전 세계 사용자가 있는 전자 상거래 플랫폼을 고려해 보겠습니다. 사용자가 주문하면 다음과 같은 여러 작업이 발생해야 합니다.

• 고객에게 알림: 주문 확인 이메일을 보냅니다.
• 재고 업데이트: 재고 수준을 줄입니다.
• 결제 처리: 결제 게이트웨이와 상호 작용합니다.
• 배송 부서에 알림: 배송 명세서를 만듭니다.

이러한 작업이 모두 동기적이면 고객은 확인을 위해 오랫동안 기다려야 하고 애플리케이션이 로드 시 응답하지 않을 수 있습니다.

백그라운드 작업 사용:

1. 주문하기 위한 사용자의 요청은 FastAPI에서 처리됩니다.
2. FastAPI는 즉시 사용자에게 주문 확인 응답을 반환합니다. "주문이 접수되었으며 처리 중입니다. 곧 이메일을 받으실 수 있습니다."
3. 다음 작업이 강력한 작업 큐(예: Celery)에 추가됩니다.
• `send_order_confirmation_email(order_details)`: 이 작업은 고객의 로캘을 고려하여 이메일 템플릿에 대한 i18n을 처리합니다.
• `update_inventory_service(order_items)`: 잠재적으로 다른 지역 창고에서 재고를 업데이트하기 위한 마이크로서비스 호출입니다.
• `process_payment_gateway(payment_details)`: 지역 엔드포인트가 있을 수 있는 결제 처리기와 상호 작용합니다. 이 작업에는 강력한 오류 처리 및 재시도 로직이 필요합니다.
• `generate_shipping_manifest(order_id, shipping_address)`: 이 작업은 대상 국가의 관세 규정을 고려하여 배송 부서에 대한 데이터를 준비합니다.

이 비동기적 접근 방식은 고객에게 빠른 응답을 보장하고 기본 API가 차단되는 것을 방지하며 피크 글로벌 쇼핑 시즌에도 주문을 확장 가능하고 복원력 있게 처리할 수 있도록 합니다.

결론

비동기 작업 실행은 특히 글로벌 대상을 서비스하는 고성능의 확장 가능하고 사용자 친화적인 애플리케이션을 구축하는 데 있어 초석입니다. 백그라운드 작업의 우아한 통합을 갖춘 Python FastAPI는 견고한 기반을 제공합니다. 간단하고 즉시 실행되는 작업의 경우 FastAPI의 기본 제공 `BackgroundTasks` 클래스가 훌륭한 시작점입니다.

그러나 복원력, 지속성, 재시도, 분산 처리 및 강력한 모니터링과 같은 고급 기능을 요구하는 까다롭고 미션 크리티컬한 애플리케이션의 경우 Celery 또는 RQ와 같은 강력한 작업 큐 시스템과 통합하는 것이 필수적입니다. 지리적 분포, 시간대, 국제화 및 강력한 오류 처리와 같은 글로벌 요소를 신중하게 고려하여 백그라운드 작업을 활용하여 전 세계 사용자를 위한 진정으로 성능이 뛰어나고 안정적인 웹 서비스를 구축할 수 있습니다.

FastAPI에서 백그라운드 작업을 마스터하는 것은 단순한 기술적 구현에 관한 것이 아니라 응답성이 뛰어나고 안정적이며 글로벌 사용자 기반의 다양한 요구 사항을 충족하도록 확장할 수 있는 시스템을 설계하는 것입니다.