liminfo

FastAPI Reference

FastAPI 프레임워크 레퍼런스

25개 결과

FastAPI Reference 소개

FastAPI 레퍼런스는 FastAPI 프레임워크로 고성능 비동기 API를 구축하는 Python 백엔드 개발자를 위한 실용적인 치트 시트입니다. 프로덕션 FastAPI 서비스에서 사용되는 6가지 핵심 범주를 다룹니다: HTTP 메서드와 경로/쿼리 파라미터 검증을 이용한 라우팅, Depends()를 이용한 의존성 주입, Pydantic 데이터 모델과 필드 검증, CORS와 신뢰 호스트 설정을 포함한 미들웨어, OAuth2와 JWT 보안 패턴, BackgroundTasks/WebSocket/StreamingResponse를 이용한 백그라운드 처리.

이 레퍼런스는 Python API 개발자, ML 모델 서빙 API를 구축하는 데이터 과학자, Flask나 Django REST Framework에서 FastAPI로 마이그레이션한 백엔드 엔지니어가 활용합니다. @app.get() 라우트 정의와 자동 OpenAPI 문서 생성부터 페이지네이션과 데이터베이스 세션 관리를 위한 클래스 기반 의존성 주입까지 정확한 Python 데코레이터 구문, 타입 애노테이션, Pydantic 사용 패턴을 제공합니다.

레퍼런스는 6가지 카테고리로 구성됩니다: 라우팅(Path()/Query() 검증, 모듈화 라우트를 위한 APIRouter, 출력 직렬화를 위한 response_model, HTTP 상태 코드), 의존성(DB 세션과 인증을 위한 Depends(), 중첩 의존성, 클래스 기반 Pagination 의존성), 모델(Pydantic BaseModel, Field() 검증, field_validator, Body() 파라미터, UploadFile), 미들웨어(@app.middleware, CORSMiddleware, TrustedHostMiddleware, HTTPException), 보안(OAuth2PasswordBearer, HTTPBasic, JWT 인코딩/디코딩, SecurityScopes), 백그라운드(BackgroundTasks, startup/shutdown 생명주기 이벤트, WebSocket 엔드포인트, SSE용 StreamingResponse).

주요 기능

  • Path()와 Query() 파라미터 검증 및 제약 조건이 포함된 비동기 @app.get/@app.post 라우팅
  • 자동 문서화 라우트 조직을 위한 prefix와 tags가 있는 APIRouter
  • yield 기반 컨텍스트 매니저 패턴을 이용한 데이터베이스 세션 관리용 Depends()
  • Field() 검증자와 커스텀 field_validator 메서드가 포함된 Pydantic BaseModel
  • OAuth2PasswordBearer 토큰 추출과 python-jose를 이용한 JWT 인코딩/디코딩
  • 프로덕션 보안을 위한 CORSMiddleware와 TrustedHostMiddleware 설정
  • HTTP 응답 후 이메일/알림 발송을 위한 fire-and-forget BackgroundTasks
  • WebSocket 엔드포인트와 Server-Sent Events(SSE)용 StreamingResponse

자주 묻는 질문

FastAPI와 Flask, Django REST Framework의 차이는 무엇인가요?

FastAPI는 Starlette(ASGI)와 Pydantic을 기반으로 구축되어 높은 동시성을 위한 네이티브 async/await 지원, 타입 애노테이션에서 자동으로 생성되는 OpenAPI(Swagger) 및 ReDoc 문서, 추가 비용 없이 Pydantic을 통한 요청/응답 검증을 제공합니다. Flask는 기본적으로 동기식이며 내장 검증이나 문서가 없습니다. Django REST Framework는 더 많은 기능을 제공하지만 더 무겁고 네이티브 비동기를 지원하지 않습니다.

FastAPI에서 Depends()를 이용한 의존성 주입은 어떻게 작동하나요?

Depends()는 FastAPI에 제공된 함수를 호출하고 반환값을 파라미터로 주입하도록 지시합니다. 데이터베이스 세션의 경우 yield를 가진 제너레이터 함수를 사용합니다: yield 전 코드는 라우트 핸들러 전에 실행되고, yield 값이 주입되며, yield 후 코드는 정리(예: 세션 닫기)로 실행됩니다. 의존성이 다른 의존성에 의존할 수 있으며 FastAPI가 자동으로 트리를 해결합니다.

FastAPI에서 Pydantic BaseModel이 요청 검증을 처리하는 방법은?

FastAPI 라우트가 Pydantic BaseModel 타입의 파라미터를 선언하면, FastAPI는 자동으로 요청 본문을 읽어 JSON으로 파싱하고 모델의 타입 애노테이션과 Field() 제약 조건에 따라 각 필드를 검증합니다. 검증에 실패하면 자세한 메시지와 함께 422 Unprocessable Entity 에러를 반환합니다. 문자열 제약에는 Field(min_length=1, max_length=100)을, 숫자 범위에는 Field(gt=0)을, 커스텀 검증 로직에는 @field_validator를 사용하세요.

FastAPI에서 JWT 인증을 구현하는 방법은?

python-jose와 passlib를 설치합니다. 토큰 URL과 함께 OAuth2PasswordBearer를 정의합니다. Depends(oauth2_scheme)에서 토큰 문자열을 받아 jwt.decode()로 디코딩하고 사용자를 반환하거나 HTTPException(401)을 발생시키는 get_current_user 의존성을 만듭니다. Depends(get_current_user)를 파라미터로 추가하여 라우트를 보호합니다. 자격 증명을 검증하고 만료 시간과 함께 jwt.encode()를 호출하는 POST /token 엔드포인트에서 토큰을 반환합니다.

FastAPI에서 response_model과 실제 반환 값의 차이는 무엇인가요?

라우트 데코레이터의 response_model 파라미터는 라우트 함수가 실제로 무엇을 반환하든 응답을 직렬화하고 필터링하는 데 사용되는 Pydantic 모델을 지정합니다. FastAPI는 response_model에 정의된 필드만 사용하여 반환 값을 직렬화하며, 외부에 노출하고 싶지 않은 비밀번호나 내부 데이터베이스 ID 같은 내부 필드를 자동으로 제외합니다. 목록 반환에는 response_model=list[Item]을, 설정되지 않은 선택적 필드를 생략하려면 response_model_exclude_unset=True를 사용하세요.

FastAPI에서 BackgroundTasks는 어떻게 작동하나요?

라우트 핸들러에 BackgroundTasks 파라미터를 선언하면 FastAPI가 자동으로 주입합니다. bg.add_task(func, arg1, arg2)를 호출하여 HTTP 응답이 전송된 후 실행될 함수를 예약합니다. 백그라운드 태스크는 서버와 동일한 프로세스/스레드 풀에서 실행되므로 이메일 전송이나 로깅 같은 가벼운 작업에 적합합니다. CPU 집약적인 무거운 작업에는 Celery나 별도의 워커 프로세스를 사용하세요.

FastAPI에서 WebSocket 엔드포인트를 만드는 방법은?

@app.websocket("/ws") 데코레이터를 WebSocket 파라미터와 함께 사용합니다. await ws.accept()를 호출하여 핸드셰이크를 완료하고, await ws.receive_text()나 receive_bytes()로 메시지를 읽고, await ws.send_text()나 send_json()으로 응답합니다. 클라이언트가 연결을 끊을 때 정리를 위해 WebSocketDisconnect 예외를 처리합니다. 여러 클라이언트에게 브로드캐스트하려면 활성 WebSocket 연결 목록을 유지하세요.

FastAPI에서 프론트엔드 접근을 위한 CORS를 설정하는 방법은?

fastapi.middleware.cors에서 CORSMiddleware를 임포트하고 app.add_middleware(CORSMiddleware, allow_origins=["https://yourfrontend.com"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"])를 호출합니다. 개발 환경에서만 allow_origins=["*"]를 사용하고 프로덕션에서는 정확한 오리진을 지정하세요. 미들웨어는 응답에 Access-Control-Allow-Origin 헤더를 추가하고 CORS preflight OPTIONS 요청을 자동으로 처리합니다.