콘텐츠로 이동
@aws/nx-plugin
Blog

FastAPI

Filter this guidePick generator option values to hide sections that don't apply.

FastAPI는 Python으로 API를 구축하기 위한 프레임워크입니다.

FastAPI 생성기는 AWS CDK 또는 Terraform 인프라 설정과 함께 새로운 FastAPI를 생성합니다. 생성된 백엔드는 서버리스 배포를 위해 AWS Lambda를 사용하며, AWS API Gateway API를 통해 노출됩니다. 로깅, AWS X-Ray 추적 및 Cloudwatch Metrics를 포함한 관찰성을 위해 AWS Lambda Powertools를 설정합니다.

사용법

섹션 제목: “사용법”

FastAPI 생성

섹션 제목: “FastAPI 생성”

두 가지 방법으로 새로운 FastAPI를 생성할 수 있습니다:

Terminal window
pnpm nx g @aws/nx-plugin:py#api --framework=fastapi
어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다
Terminal window
pnpm nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

옵션

섹션 제목: “옵션”
매개변수타입기본값설명
name 필수string-생성할 API 프로젝트의 이름
framework fastapifastapi사용할 API 프레임워크.
integrationPattern isolated | sharedisolatedAPI에 대한 API Gateway 통합이 생성되는 방식입니다. isolated (기본값) 또는 shared 중에서 선택하세요.
auth iam | cognito | customiamAPI 인증에 사용할 방법입니다. iam(기본값), cognito 또는 custom 중에서 선택하세요.
directory stringpackages애플리케이션을 저장할 디렉토리입니다.
subDirectory string-프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.
iac inherit | cdk | terraforminherit선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
moduleName string-Python 모듈 이름
infra rest-lambda | http-lambda | nonerest-lambda이 API를 배포하는 데 사용할 인프라 유형입니다.
preferInstallDependencies booleantrue생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

섹션 제목: “생성기 출력”

생성기는 <directory>/<api-name> 디렉토리에 다음과 같은 프로젝트 구조를 생성합니다:

  • project.json 프로젝트 구성 및 빌드 타겟
  • pyproject.toml Python 프로젝트 구성 및 종속성
  • run.sh uvicorn을 통해 FastAPI 앱을 시작하는 Lambda Web Adapter 부트스트랩 스크립트
  • 디렉터리<module_name>
    • __init__.py 모듈 초기화
    • init.py FastAPI 앱을 설정하고 powertools 미들웨어를 구성
    • main.py API 구현
  • 디렉터리scripts
    • generate_open_api.py FastAPI 앱에서 OpenAPI 스키마를 생성하는 스크립트

인프라

섹션 제목: “인프라”

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

  • 디렉터리packages/common/constructs
    • 디렉터리src
      • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
        • …
      • 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
        • …
      • index.ts app에서 constructs를 내보내는 진입점
    • project.json 프로젝트 빌드 타겟 및 구성

API를 배포하기 위해 다음 파일들이 생성됩니다:

  • 디렉터리packages/common/constructs/src
    • 디렉터리app
      • 디렉터리apis
        • <project-name>.ts CDK construct for deploying your API
    • 디렉터리core
      • 디렉터리api
        • http-api.ts CDK construct for deploying an HTTP API (if you selected to deploy an HTTP API)
        • rest-api.ts CDK construct for deploying a REST API (if you selected to deploy a REST API)
        • utils.ts Utilities for the API constructs

아키텍처

섹션 제목: “아키텍처”

배포된 애플리케이션은 다음과 같은 아키텍처를 가집니다:

ClientWAFAPI Gateway(REST API)LambdaCloudWatch(Logs, Metrics)X-Ray(Traces)

REST API는 API Gateway 스테이지 앞에 AWS 관리형 기본 규칙 세트가 활성화된 AWS WAFv2 Web ACL을 포함합니다.

FastAPI 구현

섹션 제목: “FastAPI 구현”

주요 API 구현은 main.py에 있습니다. 여기에서 API 라우트와 구현을 정의합니다. 예시:

from pydantic import BaseModel
from .init import app, tracer


class Item(BaseModel):
  name: str


@app.get("/items/{item_id}")
@tracer.capture_method
def get_item(item_id: int) -> Item:
    return Item(name=...)


@app.post("/items")
@tracer.capture_method
def create_item(item: Item):
    return ...

생성기는 여러 기능을 자동으로 설정합니다:

  1. 관찰성을 위한 AWS Lambda Powertools 통합
  2. 오류 처리 미들웨어
  3. 요청/응답 상관관계
  4. 메트릭 수집
  5. Lambda Web Adapter를 통한 uvicorn을 사용한 AWS Lambda 배포
  6. 타입 안전 스트리밍 (REST API만 해당)

AWS Lambda Powertools를 사용한 관찰성

섹션 제목: “AWS Lambda Powertools를 사용한 관찰성”

로깅

섹션 제목: “로깅”

생성기는 AWS Lambda Powertools를 사용하여 구조화된 로깅을 구성합니다. 라우트 핸들러에서 로거에 액세스할 수 있습니다:

from .init import app, logger


@app.get("/items/{item_id}")
def read_item(item_id: int):
    logger.info("Fetching item", extra={"item_id": item_id})
    return {"item_id": item_id}

로거는 자동으로 다음을 포함합니다:

  • 요청 추적을 위한 상관관계 ID
  • 요청 경로 및 메서드
  • Lambda 컨텍스트 정보
  • 콜드 스타트 표시기

추적

섹션 제목: “추적”

AWS X-Ray 추적이 자동으로 구성됩니다. 추적에 사용자 정의 하위 세그먼트를 추가할 수 있습니다:

from .init import app, tracer


@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Creates a new subsegment
    with tracer.provider.in_subsegment("fetch-item-details"):
        # Your logic here
        return {"item_id": item_id}

메트릭

섹션 제목: “메트릭”

CloudWatch 메트릭은 각 요청에 대해 자동으로 수집됩니다. 사용자 정의 메트릭을 추가할 수 있습니다:

from .init import app, metrics
from aws_lambda_powertools.metrics import MetricUnit


@app.get("/items/{item_id}")
def read_item(item_id: int):
    metrics.add_metric(name="ItemViewed", unit=MetricUnit.Count, value=1)
    return {"item_id": item_id}

기본 메트릭에는 다음이 포함됩니다:

  • 요청 수
  • 성공/실패 수
  • 콜드 스타트 메트릭
  • 라우트별 메트릭

오류 처리

섹션 제목: “오류 처리”

생성기는 포괄적인 오류 처리를 포함합니다:

from fastapi import HTTPException


@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 0:
        raise HTTPException(status_code=400, detail="Item ID must be positive")
    return {"item_id": item_id}

처리되지 않은 예외는 미들웨어에 의해 포착되어:

  1. 스택 추적과 함께 전체 예외를 로깅
  2. 실패 메트릭을 기록
  3. 클라이언트에 안전한 500 응답을 반환
  4. 상관관계 ID를 보존

호출 사용자 액세스

섹션 제목: “호출 사용자 액세스”

API가 인증으로 보호되는 경우, 라우트 핸들러는 종종 누가 호출하는지 알아야 합니다. 생성된 FastAPI는 Lambda Web Adapter를 통해 AWS Lambda 내부에서 실행되며, API Gateway 요청 컨텍스트를 x-amzn-request-context 헤더에 JSON으로 전달합니다. FastAPI Request에서 이를 읽어 호출자의 신원을 추출할 수 있습니다.

예를 들어, 호출 사용자에 대한 세부 정보를 반환하는 /me 엔드포인트를 추가해 보겠습니다. 라우트 간에 재사용할 수 있도록 추출을 FastAPI dependency로 구현하겠습니다. 요청 컨텍스트의 형태 — 따라서 신원을 추출하는 방법 — 는 선택한 auth 방법과 REST 또는 HTTP API를 배포했는지 여부에 따라 달라집니다.

auth = iam

IAM 인증의 경우, API Gateway 요청 컨텍스트에서 추출한 sub를 사용하여 Cognito에서 호출자를 조회합니다. main.py 옆에 identity.py를 생성하세요:

import json
import os
from typing import Annotated


from boto3 import client
from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel


cognito = client("cognito-idp")




class Identity(BaseModel):
    sub: str
    username: str




def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")


    request_context = json.loads(request_context_header)
    provider = request_context.get("identity", {}).get("cognitoAuthenticationProvider")


    sub = provider.split(":")[-1] if provider else None
    if not sub:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")


    users = cognito.list_users(
        # Assumes user pool id is configured in lambda environment
        UserPoolId=os.environ["USER_POOL_ID"],
        Limit=1,
        Filter=f'sub="{sub}"',
    ).get("Users", [])


    if len(users) != 1:
        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")


    return Identity(sub=sub, username=users[0]["Username"])




CurrentUser = Annotated[Identity, Depends(get_identity)]
auth = cognito

auth: 'cognito'를 사용하면, API Gateway Cognito User Pools 권한 부여자가 호출자가 Authorization 헤더에 제공하는 JWT를 검증하고 검증된 클레임을 요청 컨텍스트에 배치합니다.

main.py 옆에 identity.py를 생성하세요:

import json
from typing import Annotated


from fastapi import Depends, HTTPException, Request
from pydantic import BaseModel




class Identity(BaseModel):
    sub: str
    username: str




def get_identity(request: Request) -> Identity:
    # The Lambda Web Adapter forwards the API Gateway request context as JSON
    request_context_header = request.headers.get("x-amzn-request-context")
    if not request_context_header:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")


    request_context = json.loads(request_context_header)
    claims = request_context.get("authorizer", {}).get("claims", {})


    sub = claims.get("sub")
    username = claims.get("username")


    if not sub or not username:
        raise HTTPException(status_code=403, detail="Unable to determine calling user")


    return Identity(sub=sub, username=username)




CurrentUser = Annotated[Identity, Depends(get_identity)]

그런 다음 호출자의 신원이 필요한 모든 라우트에 CurrentUser 종속성을 주입할 수 있습니다:

from .identity import CurrentUser, Identity
from .init import app, tracer


@app.get("/me")
@tracer.capture_method
def me(identity: CurrentUser) -> Identity:
    return identity
infra = rest-lambda

스트리밍

섹션 제목: “스트리밍”

생성된 FastAPI는 REST API를 사용할 때 기본적으로 스트리밍 응답을 지원합니다. 인프라는 AWS Lambda Web Adapter를 사용하여 Lambda 내부에서 uvicorn을 통해 FastAPI를 실행하도록 구성되며, 모든 REST API 작업에 대해 API Gateway에서 ResponseTransferMode.STREAM을 사용하여 스트리밍이 비스트리밍 작업과 함께 작동할 수 있도록 합니다.

JsonStreamingResponse 사용

섹션 제목: “JsonStreamingResponse 사용”

생성된 init.py는 적절한 OpenAPI 스키마 생성과 함께 타입 안전 스트리밍을 제공하는 JsonStreamingResponse 클래스를 내보냅니다. 이를 통해 connection 생성기가 올바르게 타입이 지정된 스트리밍 클라이언트 메서드를 생성할 수 있습니다.

from pydantic import BaseModel
from .init import app, JsonStreamingResponse


class Chunk(BaseModel):
    message: str


async def generate_chunks():
    for i in range(100):
        yield Chunk(message=f"This is chunk {i}")


@app.post(
    "/stream",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(Chunk, "Stream of chunks")},
)
async def my_stream() -> JsonStreamingResponse:
    return JsonStreamingResponse(generate_chunks())

JsonStreamingResponse 클래스는:

  1. Pydantic 모델을 JSON Lines 형식(application/jsonl)으로 직렬화
  2. itemSchema와 함께 올바른 OpenAPI 스키마를 생성하는 openapi_response 헬퍼를 제공하여 connection 생성기가 타입 안전 스트리밍 클라이언트 메서드를 생성할 수 있도록 함

소비

섹션 제목: “소비”

응답 스트림을 소비하려면 connection 생성기를 사용할 수 있으며, 이는 스트리밍된 청크를 반복하기 위한 타입 안전 메서드를 제공합니다.

FastAPI 배포

섹션 제목: “FastAPI 배포”

FastAPI 생성기는 선택한 iac에 따라 CDK 또는 Terraform 인프라 코드를 생성합니다. 이를 사용하여 FastAPI를 배포할 수 있습니다.

common/constructs 폴더에 API를 배포하기 위한 CDK 구성이 있습니다. CDK 애플리케이션에서 이를 사용할 수 있습니다:

import { MyApi } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the api to your stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

이는 다음을 설정합니다:

  1. FastAPI 애플리케이션의 각 작업에 대한 AWS Lambda 함수
  2. 함수 트리거로서의 API Gateway HTTP/REST API
  3. IAM 역할 및 권한
  4. CloudWatch 로그 그룹
  5. X-Ray 추적 구성
  6. CloudWatch 메트릭 네임스페이스
auth = cognito
auth = custom
infra = rest-lambda

WAF

섹션 제목: “WAF”

REST API의 경우, 생성된 구성 요소는 기본적으로 AWS WAFv2 Web ACL을 API Gateway 스테이지와 연결합니다. Web ACL은 AWS 관리형 기본 규칙 세트(AWSManagedRulesCommonRuleSet 및 AWSManagedRulesKnownBadInputsRuleSet)를 사용하여 OWASP Top 10을 포함한 일반적인 웹 공격으로부터 보호합니다. WAF 요청 로그는 CloudWatch Logs 그룹에 기록됩니다.

생성된 rest-api 구성 요소를 편집하여 규칙을 추가, 제거 또는 조정할 수 있습니다(예: 속도 기반 규칙 또는 추가 관리형 규칙 그룹 추가).

옵트아웃하려면(예: 자체 Web ACL을 연결하려면) enableWaf를 false로 설정하세요:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
  enableWaf: false,
});
infra = rest-lambda

액세스 로깅

섹션 제목: “액세스 로깅”

REST API의 경우, 생성된 인프라는 기본적으로 액세스 로깅을 활성화하여 요청당 하나의 구조화된 JSON 라인을 전용 CloudWatch Logs 그룹에 작성합니다. 로그 그룹은 고객 관리형 KMS 키로 암호화되며 1년 동안 보관됩니다.

API Gateway는 계정 수준의 CloudWatch Logs 역할을 사용하여 액세스 로그를 작성합니다. 이 역할은 AWS::ApiGateway::Account 설정에 구성되며, 이는 리전당 계정당 싱글톤입니다 — 리전의 모든 REST API에 대해 하나의 역할만 존재합니다. 독립적으로 배포된 여러 스택에서 이를 안전하게 관리하기 위해, 생성된 인프라는:

  • 작동하는 역할이 이미 설정되어 있지 않은 경우에만 공유 CloudWatch Logs 역할을 생성하고 계정에 구성하므로, 배포가 다른 스택이 소유한 역할을 덮어쓰지 않습니다.
  • 해체 시 계정 설정을 그대로 두므로, 하나의 스택을 삭제해도 리전의 다른 REST API에 대한 로깅이 비활성화되지 않습니다.

계정 역할은 ApiGatewayAccount 구성 요소에 의해 관리되며, 이는 ApiGatewayAccount.ensure(scope)를 통해 해결되는 스택 범위 싱글톤입니다. 각 REST API의 스테이지는 이에 의존하며, 역할은 Lambda 기반 사용자 지정 리소스에 의해 구성됩니다.

API를 구성할 때 deployOptions를 전달하여 액세스 로그 형식을 사용자 지정할 수 있습니다:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
  deployOptions: {
    accessLogFormat: AccessLogFormat.clf(),
  },
});

통합

섹션 제목: “통합”

REST/HTTP API CDK 구성은 각 작업에 대한 통합을 정의하기 위한 타입 안전 인터페이스를 제공하도록 구성되어 있습니다.

CDK 구성은 아래에 설명된 대로 완전한 타입 안전 통합 지원을 제공합니다.

기본 통합

섹션 제목: “기본 통합”

정적 defaultIntegrations를 사용하여 각 작업에 대해 개별 AWS Lambda 함수를 정의하는 기본 패턴을 활용할 수 있습니다:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});

통합 액세스

섹션 제목: “통합 액세스”

API 구성의 integrations 속성을 통해 타입 안전 방식으로 기본 AWS Lambda 함수에 액세스할 수 있습니다. 예를 들어, API가 sayHello라는 작업을 정의하고 이 함수에 일부 권한을 추가해야 하는 경우 다음과 같이 할 수 있습니다:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});


// sayHello is typed to the operations defined in your API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

API가 shared 패턴을 사용하는 경우, 공유 라우터 Lambda는 api.integrations.$router로 노출됩니다:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});


api.integrations.$router.handler.addEnvironment('LOG_LEVEL', 'DEBUG');

기본 옵션 사용자 정의

섹션 제목: “기본 옵션 사용자 정의”

각 기본 통합에 대해 Lambda 함수를 생성할 때 사용되는 옵션을 사용자 정의하려면 withDefaultOptions 메서드를 사용할 수 있습니다. 예를 들어, 모든 Lambda 함수를 Vpc에 배치하려면:

const vpc = new Vpc(this, 'Vpc', ...);


new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
    })
    .build(),
});

작업별 옵션 사용자 정의

섹션 제목: “작업별 옵션 사용자 정의”

특정 작업에 대한 기본 통합을 생성하는 데 사용되는 옵션을 사용자 정의하려면(다른 작업에 영향을 주지 않고) withOperationOptions 메서드를 사용할 수 있습니다. 예를 들어, 하나의 작업에 대해서만 Lambda 함수 타임아웃을 늘리려면:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOperationOptions({
      sayHello: {
        timeout: Duration.seconds(60),
      },
    })
    .build(),
});


// The selected operations remain default integrations, so they're still typed accordingly:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

지정한 옵션은 기본 통합 옵션(및 withDefaultOptions를 통해 설정된 모든 옵션)과 병합됩니다. withOverrides를 통해 교체한 작업에 대해서는 옵션을 지정할 수 없습니다. 이러한 작업은 더 이상 기본 통합을 사용하지 않기 때문입니다.

호출 순서에 관계없이 withOperationOptions와 withOverrides 모두에서 동일한 작업을 대상으로 하는 경우 타입 오류가 발생합니다.

통합 재정의

섹션 제목: “통합 재정의”

withOverrides 메서드를 사용하여 특정 작업에 대한 통합을 재정의할 수도 있습니다. 각 재정의는 HTTP 또는 REST API에 대한 적절한 CDK 통합 구성으로 타입이 지정된 integration 속성을 지정해야 합니다. withOverrides 메서드도 타입 안전합니다. 예를 들어, getDocumentation API를 일부 외부 웹사이트에서 호스팅하는 문서를 가리키도록 재정의하려면 다음과 같이 할 수 있습니다:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
      },
    })
    .build(),
});

또한 재정의된 통합은 api.integrations.getDocumentation을 통해 액세스할 때 더 이상 handler 속성을 갖지 않습니다.

통합에 추가 속성을 추가할 수 있으며 이는 타입에 따라 적절하게 지정되어 다른 유형의 통합을 추상화하면서도 타입 안전을 유지할 수 있습니다. 예를 들어 REST API에 대한 S3 통합을 생성했고 나중에 특정 작업에 대한 버킷을 참조하려는 경우 다음과 같이 할 수 있습니다:

const storageBucket = new Bucket(this, 'Bucket', { ... });


const apiGatewayRole = new Role(this, 'ApiGatewayS3Role', {
  assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
});


storageBucket.grantRead(apiGatewayRole);


const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getFile: {
        bucket: storageBucket,
        integration: new AwsIntegration({
          service: 's3',
          integrationHttpMethod: 'GET',
          path: `${storageBucket.bucketName}/{fileName}`,
          options: {
            credentialsRole: apiGatewayRole,
            requestParameters: {
              'integration.request.path.fileName': 'method.request.querystring.fileName',
            },
            integrationResponses: [{ statusCode: '200' }],
          },
        }),
        options: {
          requestParameters: {
            'method.request.querystring.fileName': true,
          },
          methodResponses: [{
            statusCode: '200',
          }],
        }
      },
    })
    .build(),
});


// Later, perhaps in another file, you can access the bucket property we defined
// in a type-safe manner
api.integrations.getFile.bucket.grantRead(...);

인증자 재정의

섹션 제목: “인증자 재정의”

통합에 options를 제공하여 인증자와 같은 특정 메서드 옵션을 재정의할 수도 있습니다. 예를 들어 getDocumentation 작업에 Cognito 인증을 사용하려면:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
        options: {
          authorizer: new CognitoUserPoolsAuthorizer(...) // for REST, or HttpUserPoolAuthorizer for an HTTP API
        }
      },
    })
    .build(),
});

명시적 통합

섹션 제목: “명시적 통합”

원하는 경우 기본 통합을 사용하지 않고 각 작업에 대해 직접 통합을 제공할 수 있습니다. 이는 예를 들어 각 작업이 다른 유형의 통합을 사용해야 하거나 새 작업을 추가할 때 타입 오류를 받고 싶을 때 유용합니다:

new MyApi(this, 'MyApi', {
  integrations: {
    sayHello: {
      integration: new LambdaIntegration(...),
    },
    getDocumentation: {
      integration: new HttpIntegration(...),
    },
  },
});

통합 패턴

섹션 제목: “통합 패턴”

생성된 CDK API 구성은 두 가지 통합 패턴을 지원합니다:

  • isolated는 작업당 하나의 Lambda 함수를 생성합니다. 이것이 생성된 API의 기본값입니다.
  • shared는 단일 기본 라우터 Lambda를 생성하고 특정 통합을 재정의하지 않는 한 모든 작업에 재사용합니다.

isolated는 작업별로 더 세밀한 권한과 구성을 제공합니다. shared는 선택적 재정의를 허용하면서 Lambda 및 API Gateway 통합 확산을 줄입니다.

예를 들어, pattern을 'shared'로 설정하면 통합당 하나가 아닌 단일 함수를 생성합니다:

packages/common/constructs/src/app/apis/my-api.ts
export class MyApi<...> extends ... {


  public static defaultIntegrations = (scope: Construct) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}

코드 생성

섹션 제목: “코드 생성”

FastAPI의 작업은 Python으로 정의되고 CDK 인프라는 TypeScript로 정의되므로, 통합을 위한 타입 안전 인터페이스를 제공하기 위해 CDK 구성에 메타데이터를 제공하는 코드 생성을 계측합니다.

이 코드 생성을 용이하게 하기 위해 공통 구성 project.json에 generate:<ApiName>-metadata 타겟이 추가되며, packages/common/constructs/src/generated/my-api/metadata.gen.ts와 같은 파일을 생성합니다. 이는 빌드 시 생성되므로 버전 관리에서 무시됩니다.

auth = iam

액세스 권한 부여 (IAM만 해당)

섹션 제목: “액세스 권한 부여 (IAM만 해당)”

IAM 인증을 사용하도록 선택한 경우, grantInvokeAccess 메서드를 사용하여 API에 대한 액세스 권한을 부여할 수 있습니다:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

로컬 개발

섹션 제목: “로컬 개발”

생성기는 다음 명령으로 실행할 수 있는 로컬 개발 서버를 구성합니다:

Terminal window
pnpm nx serve my-api

이는 다음과 함께 로컬 FastAPI 개발 서버를 시작합니다:

  • 코드 변경 시 자동 리로드
  • /docs 또는 /redoc에서 대화형 API 문서
  • /openapi.json에서 OpenAPI 스키마

FastAPI 호출

섹션 제목: “FastAPI 호출”

React 웹사이트에서 API를 호출하려면 connection 생성기를 사용할 수 있습니다.

연결

섹션 제목: “연결”

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합하세요. 다음 연결은 이 프로젝트와 관련됩니다:

FastAPI
React to FastAPIReact 웹사이트에서 Python FastAPI 호출
FastAPIAmazon DynamoDBPython
FastAPI to Python DynamoDBFastAPI를 DynamoDB 테이블에 연결