FastAPI

FastAPI là một framework để xây dựng API trong Python.

Generator FastAPI tạo ra một FastAPI mới với cấu hình hạ tầng AWS CDK hoặc Terraform. Backend được tạo sử dụng AWS Lambda cho triển khai serverless, được expose thông qua AWS API Gateway API. Nó thiết lập AWS Lambda Powertools cho khả năng quan sát, bao gồm logging, AWS X-Ray tracing và Cloudwatch Metrics.

Cách sử dụng

Tạo một FastAPI

Bạn có thể tạo một FastAPI mới theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - py#api
5. Điền các tham số bắt buộc
   • framework: fastapi
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#api --framework=fastapi

yarn

yarn nx g @aws/nx-plugin:py#api --framework=fastapi

npm

npx nx g @aws/nx-plugin:py#api --framework=fastapi

bun

bunx nx g @aws/nx-plugin:py#api --framework=fastapi

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

yarn

yarn nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

npm

npx nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

bun

bunx nx g @aws/nx-plugin:py#api --framework=fastapi --dry-run

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của dự án API cần tạo
framework	fastapi	fastapi	Framework API để sử dụng.
integrationPattern	isolated | shared	isolated	Cách thức tạo các integration của API Gateway cho API. Chọn giữa isolated (mặc định) và shared.
auth	iam | cognito | custom	iam	Phương thức được sử dụng để xác thực với API của bạn. Chọn giữa iam (mặc định), cognito hoặc custom.
directory	string	packages	Thư mục để lưu trữ ứng dụng.
subDirectory	string	-	Thư mục con mà dự án được đặt trong đó. Mặc định đây là tên dự án.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
moduleName	string	-	Tên module Python
infra	rest-lambda | http-lambda | none	rest-lambda	Loại hạ tầng được sử dụng để triển khai API này.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Lựa chọn loại API

Bạn có thể chọn giữa REST API hoặc HTTP API để triển khai API của mình, vui lòng tham khảo Hướng dẫn Phát triển API Gateway để giúp bạn quyết định.

Loại API

Chọn rest-lambda (mặc định) làm infra của bạn nếu bạn định xây dựng bất kỳ streaming operations nào.

Mẫu tích hợp

Tùy chọn integrationPattern mặc định là isolated, tạo một Lambda cho mỗi FastAPI operation. Chọn shared nếu bạn muốn một Lambda handler dùng chung cho toàn bộ API, với khả năng override cho từng operation.

Kết quả từ Generator

Generator sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<api-name>:

• project.json Cấu hình dự án và build targets
• pyproject.toml Cấu hình dự án Python và dependencies
• run.sh Lambda Web Adapter bootstrap script để khởi động ứng dụng FastAPI thông qua uvicorn
• Thư mục<module_name>

  • __init__.py Khởi tạo module
  • init.py Thiết lập ứng dụng FastAPI và cấu hình powertools middleware
  • main.py Triển khai API
• Thư mụcscripts

  • generate_open_api.py Script để tạo OpenAPI schema từ ứng dụng FastAPI

Hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Để triển khai API của bạn, các tệp sau được tạo ra:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcapis

      • <project-name>.ts CDK construct để triển khai API của bạn
  • Thư mụccore

    • Thư mụcapi

      • http-api.ts CDK construct để triển khai HTTP API (nếu bạn chọn triển khai HTTP API)
      • rest-api.ts CDK construct để triển khai REST API (nếu bạn chọn triển khai REST API)
      • utils.ts Các tiện ích cho API constructs

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcapis

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai API của bạn
  • Thư mụccore

    • Thư mụcapi

      • Thư mụchttp-api

        • http-api.tf Module để triển khai HTTP API (nếu bạn chọn triển khai HTTP API)
      • Thư mụcrest-api

        • rest-api.tf Module để triển khai REST API (nếu bạn chọn triển khai REST API)

Architecture

Ứng dụng được triển khai có kiến trúc như sau:

REST API

REST API bao gồm một AWS WAFv2 Web ACL đặt trước API Gateway stage với bộ quy tắc mặc định do AWS quản lý được kích hoạt.

HTTP API

HTTP API không hỗ trợ WAF trực tiếp — nếu bạn cần bảo vệ WAF, hãy chọn REST API thay thế hoặc đặt HTTP API phía sau một CloudFront distribution.

Triển khai FastAPI của bạn

Triển khai API chính nằm trong main.py. Đây là nơi bạn định nghĩa các route API và triển khai của chúng. Ví dụ:

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 ...

Generator tự động thiết lập một số tính năng:

1. Tích hợp AWS Lambda Powertools cho khả năng quan sát
2. Error handling middleware
3. Request/response correlation
4. Thu thập metrics
5. Triển khai AWS Lambda thông qua Lambda Web Adapter với uvicorn
6. Type-safe streaming (chỉ REST API)

Khả năng quan sát với AWS Lambda Powertools

Logging

Generator cấu hình structured logging sử dụng AWS Lambda Powertools. Bạn có thể truy cập logger trong các route handler:

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}

Logger tự động bao gồm:

• Correlation IDs cho request tracing
• Request path và method
• Thông tin Lambda context
• Chỉ báo cold start

Tracing

AWS X-Ray tracing được cấu hình tự động. Bạn có thể thêm custom subsegments vào traces của mình:

from .init import app, tracer

@app.get("/items/{item_id}")
@tracer.capture_method
def read_item(item_id: int):
    # Tạo một subsegment mới
    with tracer.provider.in_subsegment("fetch-item-details"):
        # Logic của bạn ở đây
        return {"item_id": item_id}

Metrics

CloudWatch metrics được thu thập tự động cho mỗi request. Bạn có thể thêm custom metrics:

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}

Metrics mặc định bao gồm:

• Số lượng request
• Số lượng thành công/thất bại
• Metrics cold start
• Metrics theo từng route

Xử lý lỗi

Generator bao gồm xử lý lỗi toàn diện:

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}

Các exception không được xử lý sẽ được middleware bắt và:

1. Ghi log exception đầy đủ với stack trace
2. Ghi lại failure metric
3. Trả về response 500 an toàn cho client
4. Bảo toàn correlation ID

Mô hình phản hồi

Nên chỉ định response models cho các API operation để tạo code tốt hơn nếu sử dụng generator connection. Xem thêm chi tiết tại đây.

Truy cập người dùng đang gọi

Khi API của bạn được bảo vệ bởi xác thực, các route handler thường cần biết ai đang gọi. FastAPI được tạo chạy bên trong AWS Lambda thông qua Lambda Web Adapter, chuyển tiếp API Gateway request context dưới dạng JSON trên header x-amzn-request-context. Bạn có thể đọc nó từ FastAPI Request để trích xuất danh tính của người gọi.

Ví dụ, hãy thêm một endpoint /me trả về thông tin chi tiết về người dùng đang gọi. Chúng ta sẽ triển khai việc trích xuất dưới dạng FastAPI dependency để có thể tái sử dụng trên các route. Hình dạng của request context — và do đó cách bạn trích xuất danh tính — phụ thuộc vào cả phương thức auth bạn đã chọn và việc bạn triển khai REST hay HTTP API.

auth = iam

Với xác thực IAM, chúng ta tra cứu người gọi trong Cognito bằng cách sử dụng sub được trích xuất từ API Gateway request context. Tạo identity.py cùng với main.py:

REST API

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:
    # Lambda Web Adapter chuyển tiếp API Gateway request context dưới dạng 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(
        # Giả định user pool id được cấu hình trong 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)]

HTTP API

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:
    # Lambda Web Adapter chuyển tiếp API Gateway request context dưới dạng 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)
    amr = (
        request_context.get("authorizer", {})
        .get("iam", {})
        .get("cognitoIdentity", {})
        .get("amr", [])
    )
    sign_in = next((s for s in amr if ":CognitoSignIn:" in s), None)
    sub = sign_in.split(":")[-1] if sign_in else None

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

    users = cognito.list_users(
        # Giả định user pool id được cấu hình trong 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

Với auth: 'cognito', API Gateway Cognito User Pools authorizer xác minh JWT mà người gọi cung cấp trong header Authorization và đặt các claims đã xác minh trên request context.

Tạo identity.py cùng với main.py:

REST API

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:
    # Lambda Web Adapter chuyển tiếp API Gateway request context dưới dạng 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)]

HTTP API

HTTP APIs sử dụng JWT authorizer đặt các claims đã xác minh dưới authorizer.jwt.claims:

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:
    # Lambda Web Adapter chuyển tiếp API Gateway request context dưới dạng 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("jwt", {}).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)]

Không cần xác minh token

Bạn không cần bất kỳ thư viện xác minh JWT nào ở đây — API Gateway Cognito User Pools authorizer đã xác minh chữ ký, issuer, scopes và expiry vào thời điểm Lambda của bạn chạy. Nếu bất kỳ kiểm tra nào trong số đó thất bại, API Gateway trả về 401 Unauthorized và handler của bạn không bao giờ được gọi.

Sau đó, bạn có thể inject dependency CurrentUser vào bất kỳ route nào cần danh tính của người gọi:

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

Streaming

FastAPI được tạo hỗ trợ streaming responses ngay từ đầu khi sử dụng REST API. Hạ tầng được cấu hình để sử dụng AWS Lambda Web Adapter để chạy FastAPI của bạn thông qua uvicorn bên trong Lambda, với ResponseTransferMode.STREAM trong API Gateway cho tất cả các REST API operations, cho phép streaming hoạt động cùng với các non-streaming operations.

Sử dụng JsonStreamingResponse

File init.py được tạo exports một class JsonStreamingResponse cung cấp type-safe streaming với việc tạo OpenAPI schema phù hợp. Điều này đảm bảo rằng connection generator có thể tạo ra các streaming client methods được type đúng cách.

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())

Class JsonStreamingResponse:

1. Serialize các Pydantic models sang định dạng JSON Lines (application/jsonl)
2. Cung cấp helper openapi_response tạo ra OpenAPI schema đúng với itemSchema, cho phép connection generator tạo ra các type-safe streaming client methods

Sử dụng

Để sử dụng một stream của responses, bạn có thể tận dụng connection generator sẽ cung cấp một phương thức type-safe để lặp qua các streamed chunks của bạn.

Triển khai FastAPI của bạn

Generator FastAPI tạo CDK hoặc Terraform infrastructure as code dựa trên iacProvider bạn đã chọn. Bạn có thể sử dụng điều này để triển khai FastAPI của mình.

CDK

CDK construct để triển khai API của bạn trong thư mục common/constructs. Bạn có thể sử dụng nó trong một ứng dụng CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Thêm api vào stack của bạn
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Điều này thiết lập:

1. Một AWS Lambda function cho mỗi operation trong ứng dụng FastAPI
2. API Gateway HTTP/REST API làm function trigger
3. IAM roles và permissions
4. CloudWatch log group
5. Cấu hình X-Ray tracing
6. CloudWatch metrics namespace

Cấu hình CORS CDK

Nếu giải pháp của bạn bao gồm một trang web, bạn có thể cấu hình phân phối CloudFront của nó làm nguồn gốc CORS duy nhất được phép trong API gateway / tích hợp API AWS Lambda cho HTTP / REST APIs. Bạn có thể gọi phương thức restrictCorsTo của API với các construct website, phân phối CloudFront, chuỗi nguồn gốc, hoặc kết hợp chúng.

import { MyApi, MyWebsite } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
    const website = new MyWebsite(this, 'MyWebsite');
    api.restrictCorsTo(website, 'http://localhost:4200');
  }
}

Construct MyWebsite có thể được tạo bằng cách sử dụng generator ts#website

auth = cognito

Xác thực Cognito

Nếu bạn chọn sử dụng xác thực Cognito, bạn sẽ cần cung cấp thuộc tính identity cho API construct:

import { MyApi, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

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

Construct UserIdentity có thể được tạo bằng cách sử dụng generator ts#website#auth

auth = custom

Custom Lambda Authorizer

When using Custom auth, the construct creates a Lambda Authorizer internally from the generated authorizer.py file, which denies all requests by default. You must implement your authorization logic in that file before your API will accept any traffic.

Terraform

Các module Terraform để triển khai API của bạn nằm trong thư mục common/terraform. Bạn có thể sử dụng nó trong cấu hình Terraform.

Module API stages Lambda deployment zip của nó trong một shared S3 asset bucket — xem hướng dẫn hạ tầng Terraform để biết chi tiết. Khởi tạo module core/asset-bucket một lần cho mỗi deployment và truyền output bucket_name của nó vào mọi API / Lambda module thông qua input asset_bucket_name:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # Biến môi trường cho Lambda function
  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  # IAM policies bổ sung nếu cần
  additional_iam_policy_statements = [
    # Thêm bất kỳ quyền bổ sung nào mà API của bạn cần
  ]

  tags = local.common_tags
}

Điều này thiết lập:

1. Một AWS Lambda function phục vụ tất cả các route FastAPI
2. API Gateway HTTP/REST API làm function trigger
3. IAM roles và permissions
4. CloudWatch log group
5. Cấu hình X-Ray tracing
6. Cấu hình CORS

Cấu hình CORS Terraform

Nếu giải pháp của bạn bao gồm một module website Terraform thì bạn có thể sử dụng tên miền CloudFront của nó để hạn chế CORS. Với tên miền CloudFront <domain_name>, trong module Terraform để triển khai API của bạn, hãy thêm

• một thuộc tính cors_allow_origins, đặt thành ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"], cho HTTP APIs. Điều này hạn chế CORS của API gateway đối với phân phối này và local host.
• một biến môi trường ALLOWED_ORIGINS, đặt thành "https://<domain_name>", cho REST APIs. Điều này đặt phân phối CloudFront là nguồn gốc CORS duy nhất được phép (ngoài local host) trong các tích hợp AWS Lambda. Lưu ý rằng hạn chế này không được áp dụng cho preflight OPTIONS - vui lòng +1 GitHub issue này để giúp ưu tiên giải quyết vấn đề này.

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  cors_allow_origins = ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"] // Only required for HTTP API

  env = {
    ALLOWED_ORIGINS = "https://<domain name>" // Only required for REST API
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }
}

Cấu trúc MyWebsite có thể được tạo bằng cách sử dụng trình tạo ts#website

auth = cognito

Xác thực Cognito

Nếu bạn chọn sử dụng xác thực Cognito, bạn sẽ cần cung cấp cấu hình Cognito:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name    = module.asset_bucket.bucket_name

  user_pool_id         = local.user_pool_id
  user_pool_client_ids = [local.client_id]

  env = {
    ENVIRONMENT = var.environment
    LOG_LEVEL   = "INFO"
  }

  tags = local.common_tags
}

Bạn có thể thiết lập Cognito User Pool và Client sử dụng các Terraform resources hoặc modules phù hợp.

Module Terraform cung cấp một số outputs bạn có thể sử dụng:

# Truy cập API endpoint
output "api_url" {
  value = module.my_api.stage_invoke_url
}

# Truy cập chi tiết Lambda function
output "lambda_function_name" {
  value = module.my_api.lambda_function_name
}

# Truy cập IAM role để cấp quyền bổ sung
output "lambda_execution_role_arn" {
  value = module.my_api.lambda_execution_role_arn
}

Bạn có thể tùy chỉnh cài đặt CORS bằng cách truyền biến cho module:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # Cấu hình CORS tùy chỉnh
  cors_allow_origins = ["https://myapp.com", "https://staging.myapp.com"]
  cors_allow_methods = ["GET", "POST", "PUT", "DELETE"]
  cors_allow_headers = [
    "authorization",
    "content-type",
    "x-custom-header"
  ]

  tags = local.common_tags
}

auth = custom

Custom Lambda Authorizer

When using Custom auth, your API is protected by a Lambda Authorizer that denies all requests by default. You must implement your authorization logic in the generated authorizer.py file before your API will accept any traffic.

infra = rest-lambda

WAF

Đối với REST API, construct được tạo ra sẽ liên kết một AWS WAFv2 Web ACL với API Gateway stage theo mặc định. Web ACL sử dụng bộ quy tắc mặc định được quản lý bởi AWS (AWSManagedRulesCommonRuleSet và AWSManagedRulesKnownBadInputsRuleSet), cung cấp bảo vệ chống lại các khai thác web phổ biến bao gồm OWASP Top 10. Nhật ký yêu cầu WAF được ghi vào nhóm CloudWatch Logs.

Sự khác biệt của SizeRestrictions_BODY so với mặc định

Quy tắc SizeRestrictions_BODY từ AWSManagedRulesCommonRuleSet được ghi đè thành Count thay vì Block, vì giới hạn 8 KB của quy tắc quá hạn chế đối với hầu hết các API. Các yêu cầu quá khổ vẫn sẽ được ghi lại dưới dạng số liệu để bạn có thể giám sát chúng. Xem hướng dẫn giới hạn kích thước body của AWS WAF để biết thêm chi tiết. API Gateway tự động thực thi kích thước payload tối đa 10 MB, trả về mã 413 cho các yêu cầu lớn hơn.

Bạn có thể chỉnh sửa construct rest-api được tạo ra để thêm, xóa hoặc điều chỉnh các quy tắc (ví dụ: để thêm quy tắc dựa trên tốc độ hoặc các nhóm quy tắc được quản lý bổ sung).

CDK

Để từ chối (ví dụ: để đính kèm Web ACL của riêng bạn), đặt enableWaf thành false:

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

Terraform

Để từ chối (ví dụ: để đính kèm Web ACL của riêng bạn), đặt enable_waf thành false:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
  enable_waf        = false
}

infra = rest-lambda

Access logging

Đối với REST API, cơ sở hạ tầng được tạo ra sẽ bật ghi nhật ký truy cập theo mặc định, ghi một dòng JSON có cấu trúc cho mỗi yêu cầu vào một nhóm CloudWatch Logs chuyên dụng. Nhóm nhật ký được mã hóa bằng khóa KMS do khách hàng quản lý và được giữ lại trong một năm.

API Gateway ghi nhật ký truy cập bằng cách sử dụng vai trò CloudWatch Logs ở cấp tài khoản. Vai trò này được cấu hình trên cài đặt AWS::ApiGateway::Account, đây là một singleton cho mỗi vùng trên mỗi tài khoản — chỉ có một vai trò duy nhất cho mọi REST API trong vùng. Để quản lý điều này một cách an toàn trên nhiều stack được triển khai độc lập, cơ sở hạ tầng được tạo ra sẽ:

• Tạo một vai trò CloudWatch Logs được chia sẻ và cấu hình nó trên tài khoản chỉ khi chưa có vai trò hoạt động nào được thiết lập, do đó các triển khai không bao giờ ghi đè vai trò mà một stack khác sở hữu.
• Giữ nguyên cài đặt tài khoản khi dỡ bỏ, do đó việc hủy một stack không bao giờ vô hiệu hóa ghi nhật ký cho các REST API khác trong vùng.

CDK

Vai trò tài khoản được quản lý bởi construct ApiGatewayAccount, một singleton có phạm vi stack được giải quyết thông qua ApiGatewayAccount.ensure(scope). Mỗi stage của REST API phụ thuộc vào nó, và vai trò được cấu hình bởi một tài nguyên tùy chỉnh được hỗ trợ bởi Lambda.

Bạn có thể tùy chỉnh định dạng nhật ký truy cập bằng cách truyền deployOptions khi xây dựng API của bạn:

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

Terraform

Vai trò tài khoản được quản lý bởi module core/api/api-gateway-account, được khởi tạo bởi module API được tạo ra. Nó cấu hình tài khoản một cách idempotent và không bao giờ được đặt lại khi chạy terraform destroy.

Bạn có thể tùy chỉnh định dạng nhật ký truy cập bằng cách chỉnh sửa khối access_log_settings trên tài nguyên aws_api_gateway_stage trong module API được tạo ra.

Integrations

Các construct CDK của REST/HTTP API được cấu hình để cung cấp giao diện type-safe cho việc định nghĩa các tích hợp cho từng operation của bạn.

CDK

Các construct CDK cung cấp hỗ trợ tích hợp type-safe đầy đủ như mô tả bên dưới.

Terraform

Mẫu router

Các module Terraform sử dụng “router pattern” với một Lambda function duy nhất phục vụ tất cả các operation. Các tích hợp type-safe không được hỗ trợ - module tạo một Lambda function xử lý tất cả các request API.

Để có các tích hợp rõ ràng cho từng operation với Terraform, bạn cần tự tạo các Lambda function riêng lẻ và các route API Gateway. Xem phần Tích hợp rõ ràng để biết các ví dụ.

Tích hợp mặc định

CDK

Bạn có thể sử dụng defaultIntegrations tĩnh để sử dụng pattern mặc định, định nghĩa một AWS Lambda function riêng biệt cho mỗi operation:

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

Terraform

Các module Terraform tự động sử dụng router pattern với một Lambda function duy nhất. Không cần cấu hình thêm:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # Module tự động tạo một Lambda function duy nhất
  # xử lý tất cả các operation API
  tags = local.common_tags
}

Truy cập các tích hợp

CDK

Bạn có thể truy cập các AWS Lambda function bên dưới thông qua thuộc tính integrations của construct API, theo cách type-safe. Ví dụ, nếu API của bạn định nghĩa một operation tên là sayHello và bạn cần thêm một số quyền cho function này, bạn có thể làm như sau:

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

// sayHello được type theo các operation được định nghĩa trong API của bạn
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Nếu API của bạn sử dụng pattern shared, router Lambda dùng chung được expose dưới dạng api.integrations.$router:

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

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

Terraform

Với router pattern của Terraform, chỉ có một Lambda function duy nhất. Bạn có thể truy cập nó thông qua các output của module:

# Cấp thêm quyền cho Lambda function duy nhất
resource "aws_iam_role_policy" "additional_permissions" {
  name = "additional-api-permissions"
  role = module.my_api.lambda_execution_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "s3:GetObject",
          "s3:PutObject"
        ]
        Resource = "arn:aws:s3:::my-bucket/*"
      }
    ]
  })
}

Tùy chỉnh các tùy chọn mặc định

CDK

Nếu bạn muốn tùy chỉnh các tùy chọn được sử dụng khi tạo Lambda function cho mỗi tích hợp mặc định, bạn có thể sử dụng phương thức withDefaultOptions. Ví dụ, nếu bạn muốn tất cả các Lambda function của mình nằm trong một Vpc:

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

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

Terraform

Để tùy chỉnh các tùy chọn như cấu hình VPC, bạn cần chỉnh sửa module Terraform đã được tạo. Ví dụ, để thêm hỗ trợ VPC cho tất cả các Lambda function:

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Thêm các biến VPC
variable "vpc_subnet_ids" {
  description = "List of VPC subnet IDs for Lambda function"
  type        = list(string)
  default     = []
}

variable "vpc_security_group_ids" {
  description = "List of VPC security group IDs for Lambda function"
  type        = list(string)
  default     = []
}

# Cập nhật resource Lambda function
resource "aws_lambda_function" "api_lambda" {
  # ... cấu hình hiện có ...

  # Thêm cấu hình VPC
  vpc_config {
    subnet_ids         = var.vpc_subnet_ids
    security_group_ids = var.vpc_security_group_ids
  }
}

Sau đó sử dụng module với cấu hình VPC:

module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # Cấu hình VPC
  vpc_subnet_ids         = [aws_subnet.private_a.id, aws_subnet.private_b.id]
  vpc_security_group_ids = [aws_security_group.lambda_sg.id]

  tags = local.common_tags
}

Tùy chỉnh các tùy chọn cho từng operation

CDK

Để tùy chỉnh các tùy chọn được sử dụng để tạo tích hợp mặc định cho các operation cụ thể (mà không ảnh hưởng đến các operation khác), bạn có thể sử dụng phương thức withOperationOptions. Ví dụ, nếu bạn muốn tăng thời gian chờ của Lambda function chỉ cho một operation:

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

// Các operation được chọn vẫn là tích hợp mặc định, vì vậy chúng vẫn được type tương ứng:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Các tùy chọn bạn chỉ định được hợp nhất với các tùy chọn tích hợp mặc định (và bất kỳ tùy chọn nào được đặt thông qua withDefaultOptions). Lưu ý rằng bạn không thể chỉ định tùy chọn cho các operation mà bạn đã thay thế thông qua withOverrides, vì chúng không còn sử dụng tích hợp mặc định nữa.

Bạn sẽ gặp lỗi type nếu cùng một operation được nhắm mục tiêu bởi cả withOperationOptions và withOverrides, bất kể thứ tự bạn gọi chúng.

Terraform

Để tùy chỉnh các tùy chọn cho các operation cụ thể với Terraform, bạn cần chỉnh sửa module Terraform đã được tạo để cấu hình các Lambda function riêng lẻ cho từng operation (xem phần Tích hợp rõ ràng bên dưới).

Ghi đè các tích hợp

CDK

Bạn cũng có thể ghi đè các tích hợp cho các operation cụ thể bằng phương thức withOverrides. Mỗi ghi đè phải chỉ định một thuộc tính integration được type theo construct tích hợp CDK phù hợp cho HTTP hoặc REST API. Phương thức withOverrides cũng là type-safe. Ví dụ, nếu bạn muốn ghi đè một API getDocumentation để trỏ đến tài liệu được lưu trữ bởi một trang web bên ngoài, bạn có thể thực hiện như sau:

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

Bạn cũng sẽ nhận thấy rằng tích hợp được ghi đè không còn có thuộc tính handler khi truy cập nó thông qua api.integrations.getDocumentation.

Bạn có thể thêm các thuộc tính bổ sung vào một tích hợp cũng sẽ được type tương ứng, cho phép các loại tích hợp khác được trừu tượng hóa nhưng vẫn giữ type-safe, ví dụ nếu bạn đã tạo một tích hợp S3 cho REST API và sau này muốn tham chiếu bucket cho một operation cụ thể, bạn có thể làm như sau:

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(),
});

// Sau này, có thể trong một file khác, bạn có thể truy cập thuộc tính bucket mà chúng ta đã định nghĩa
// theo cách type-safe
api.integrations.getFile.bucket.grantRead(...);

Terraform

Ghi đè tích hợp

Việc ghi đè các tích hợp cụ thể không được hỗ trợ với các module Terraform vì chúng sử dụng router pattern. Tất cả các operation được xử lý bởi Lambda function duy nhất.

Để có các loại tích hợp khác nhau cho mỗi operation, bạn cần triển khai các tích hợp rõ ràng thủ công (xem phần Tích hợp rõ ràng bên dưới).

Ghi đè các Authorizer

CDK

Bạn cũng có thể cung cấp options trong tích hợp của mình để ghi đè các tùy chọn method cụ thể như authorizer, ví dụ nếu bạn muốn sử dụng xác thực Cognito cho operation getDocumentation của mình:

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

Terraform

Ghi đè bộ xác thực

Việc ghi đè authorizer cho từng operation không được hỗ trợ với các module Terraform. Toàn bộ API sử dụng phương thức xác thực được chỉ định khi tạo API (IAM, Cognito, hoặc Custom).

Để có authorization cho từng operation, bạn cần triển khai các tích hợp rõ ràng thủ công như bên dưới.

Tích hợp rõ ràng

CDK

Nếu bạn muốn, bạn có thể chọn không sử dụng các tích hợp mặc định và thay vào đó cung cấp trực tiếp một tích hợp cho mỗi operation. Điều này hữu ích nếu, ví dụ, mỗi operation cần sử dụng một loại tích hợp khác nhau hoặc bạn muốn nhận lỗi type khi thêm các operation mới:

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

Terraform

Để có các tích hợp rõ ràng cho từng operation với Terraform, bạn nên sửa đổi module dành riêng cho ứng dụng đã được tạo để thay thế tích hợp proxy mặc định bằng các tích hợp cụ thể cho từng operation.

Chỉnh sửa packages/common/terraform/src/app/apis/my-api/my-api.tf:

1. Xóa các route proxy mặc định (ví dụ: resource "aws_apigatewayv2_route" "proxy_routes")
2. Thay thế Lambda function duy nhất bằng các function riêng lẻ cho từng operation
3. Tạo các tích hợp và route cụ thể cho từng operation, tái sử dụng cùng một bundle ZIP:

HTTP API

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Xóa Lambda function mặc định duy nhất
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... phần còn lại của cấu hình
 }

# Xóa tích hợp proxy mặc định
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... phần còn lại của cấu hình
 }

# Xóa các route proxy mặc định
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... phần còn lại của cấu hình
 }

# Thêm các Lambda function riêng lẻ cho mỗi operation sử dụng cùng một bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Handler cụ thể cho operation này
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler cụ thể cho operation này
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

# Thêm các tích hợp cụ thể cho mỗi operation
 resource "aws_apigatewayv2_integration" "say_hello_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.say_hello_handler.invoke_arn
   payload_format_version = "2.0"
   timeout_milliseconds   = 30000
 }

 resource "aws_apigatewayv2_integration" "get_documentation_integration" {
   api_id           = module.http_api.api_id
   integration_type = "HTTP_PROXY"
   integration_uri  = "https://example.com/documentation"
   integration_method = "GET"
 }

# Thêm các route cụ thể cho mỗi operation
 resource "aws_apigatewayv2_route" "say_hello_route" {
   api_id    = module.http_api.api_id
   route_key = "POST /sayHello"
   target    = "integrations/${aws_apigatewayv2_integration.say_hello_integration.id}"
   authorization_type = "AWS_IAM"
 }

 resource "aws_apigatewayv2_route" "get_documentation_route" {
   api_id    = module.http_api.api_id
   route_key = "GET /documentation"
   target    = "integrations/${aws_apigatewayv2_integration.get_documentation_integration.id}"
   authorization_type = "NONE"
 }

# Thêm quyền Lambda cho mỗi function
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.http_api.api_execution_arn}/*/*"
 }

REST API

packages/common/terraform/src/app/apis/my-api/my-api.tf

# Xóa Lambda function mặc định duy nhất
 resource "aws_lambda_function" "api_lambda" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApiHandler"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "index.handler"
   runtime         = "nodejs22.x"
   timeout         = 30
   # ... phần còn lại của cấu hình
 }

# Xóa tích hợp proxy mặc định
 resource "aws_apigatewayv2_integration" "lambda_integration" {
   api_id           = module.http_api.api_id
   integration_type = "AWS_PROXY"
   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
   # ... phần còn lại của cấu hình
 }

# Xóa các route proxy mặc định
 resource "aws_apigatewayv2_route" "proxy_routes" {
   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
   api_id    = module.http_api.api_id
   route_key = "${each.key} /{proxy+}"
   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
   # ... phần còn lại của cấu hình
 }

# Thêm các Lambda function riêng lẻ cho mỗi operation sử dụng cùng một bundle
 resource "aws_lambda_function" "say_hello_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-SayHello"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "sayHello.handler"  # Handler cụ thể cho operation này
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

 resource "aws_lambda_function" "get_documentation_handler" {
   filename         = data.archive_file.lambda_zip.output_path
   function_name    = "MyApi-GetDocumentation"
   role            = aws_iam_role.lambda_execution_role.arn
   handler         = "getDocumentation.handler"  # Handler cụ thể cho operation này
   runtime         = "nodejs22.x"
   timeout         = 30
   source_code_hash = data.archive_file.lambda_zip.output_base64sha256

   tracing_config {
     mode = "Active"
   }

   environment {
     variables = var.env
   }

   tags = var.tags
 }

# Thêm các resource và method cụ thể cho mỗi operation
 resource "aws_api_gateway_resource" "say_hello_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "sayHello"
 }

 resource "aws_api_gateway_method" "say_hello_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.say_hello_resource.id
   http_method   = "POST"
   authorization = "AWS_IAM"
 }

 resource "aws_api_gateway_integration" "say_hello_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.say_hello_resource.id
   http_method = aws_api_gateway_method.say_hello_method.http_method

   integration_http_method = "POST"
   type                   = "AWS_PROXY"
   uri                    = aws_lambda_function.say_hello_handler.invoke_arn
 }

 resource "aws_api_gateway_resource" "get_documentation_resource" {
   rest_api_id = module.rest_api.api_id
   parent_id   = module.rest_api.api_root_resource_id
   path_part   = "documentation"
 }

 resource "aws_api_gateway_method" "get_documentation_method" {
   rest_api_id   = module.rest_api.api_id
   resource_id   = aws_api_gateway_resource.get_documentation_resource.id
   http_method   = "GET"
   authorization = "NONE"
 }

 resource "aws_api_gateway_integration" "get_documentation_integration" {
   rest_api_id = module.rest_api.api_id
   resource_id = aws_api_gateway_resource.get_documentation_resource.id
   http_method = aws_api_gateway_method.get_documentation_method.http_method

   integration_http_method = "GET"
   type                   = "HTTP"
   uri                    = "https://example.com/documentation"
 }

# Cập nhật deployment để phụ thuộc vào các tích hợp mới
~ resource "aws_api_gateway_deployment" "api_deployment" {
    rest_api_id = module.rest_api.api_id

    depends_on = [
     aws_api_gateway_integration.lambda_integration,
     aws_api_gateway_integration.say_hello_integration,
     aws_api_gateway_integration.get_documentation_integration,
    ]

    lifecycle {
      create_before_destroy = true
    }

   triggers = {
     redeployment = sha1(jsonencode([
       aws_api_gateway_integration.say_hello_integration,
       aws_api_gateway_integration.get_documentation_integration,
     ]))
   }
  }

# Thêm quyền Lambda cho mỗi function
 resource "aws_lambda_permission" "say_hello_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.say_hello_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

 resource "aws_lambda_permission" "get_documentation_permission" {
   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.get_documentation_handler.function_name
   principal     = "apigateway.amazonaws.com"
   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
 }

Integration Pattern

CDK

Các construct CDK API được tạo hỗ trợ hai integration pattern:

• isolated tạo một Lambda function cho mỗi operation. Đây là mặc định cho các API được tạo.
• shared tạo một router Lambda mặc định duy nhất và tái sử dụng nó cho mọi operation trừ khi bạn ghi đè các tích hợp cụ thể.

isolated cung cấp cho bạn quyền và cấu hình chi tiết hơn cho mỗi operation. shared giảm sự phân tán của Lambda và tích hợp API Gateway trong khi vẫn cho phép ghi đè có chọn lọc.

Ví dụ, đặt pattern thành 'shared' sẽ tạo một function duy nhất thay vì một function cho mỗi tích hợp:

packages/common/constructs/src/app/apis/my-api.ts

export class MyApi<...> extends ... {

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

Terraform

Các module Terraform tự động sử dụng router pattern - đây là cách tiếp cận mặc định và duy nhất được hỗ trợ. Module được tạo tạo một Lambda function duy nhất xử lý tất cả các operation API.

Bạn chỉ cần khởi tạo module mặc định để có router pattern:

# Router pattern mặc định - Lambda function duy nhất cho tất cả các operation
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name

  # Lambda function duy nhất xử lý tất cả các operation tự động
  tags = local.common_tags
}

Tạo Code

CDK

Vì các operation trong FastAPI được định nghĩa bằng Python và hạ tầng CDK bằng TypeScript, chúng tôi sử dụng code-generation để cung cấp metadata cho CDK construct nhằm cung cấp giao diện type-safe cho integrations.

Một target generate:<ApiName>-metadata được thêm vào project.json của common constructs để hỗ trợ việc tạo code này, tạo ra một file như packages/common/constructs/src/generated/my-api/metadata.gen.ts. Vì điều này được tạo tại thời điểm build, nó bị bỏ qua trong version control.

Build trước khi triển khai

Bạn sẽ cần chạy build mỗi khi thay đổi API để đảm bảo các kiểu được sử dụng bởi CDK construct được cập nhật.

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Tải lại nóng

Nếu bạn đang tích cực làm việc trên cả hạ tầng CDK và FastAPI cùng nhau, bạn có thể sử dụng nx watch để tạo lại các kiểu này mỗi khi bạn thực hiện thay đổi API:

pnpm

pnpm nx watch --projects=<FastAPIProject> -- \
pnpm nx run <InfraProject>:"generate:<ApiName>-metadata"

yarn

yarn nx watch --projects=<FastAPIProject> -- \
yarn nx run <InfraProject>:"generate:<ApiName>-metadata"

npm

npx nx watch --projects=<FastAPIProject> -- \
npx nx run <InfraProject>:"generate:<ApiName>-metadata"

bun

bunx nx watch --projects=<FastAPIProject> -- \
bunx nx run <InfraProject>:"generate:<ApiName>-metadata"

Terraform

Hạn chế của Terraform

Chúng tôi không hỗ trợ type-safe integrations cho Terraform, và do đó không có targets tạo code nào được cấu hình nếu bạn chọn Terraform cho iacProvider.

auth = iam

Cấp quyền truy cập (Chỉ IAM)

Nếu bạn chọn sử dụng xác thực IAM, bạn có thể sử dụng phương thức grantInvokeAccess để cấp quyền truy cập vào API của mình:

CDK

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Terraform

# Tạo IAM policy để cho phép invoke API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Policy để cho phép invoke FastAPI"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "execute-api:Invoke"
        Resource = "${module.my_api.api_execution_arn}/*/*"
      }
    ]
  })
}

# Attach policy vào IAM role (ví dụ, cho authenticated users)
resource "aws_iam_role_policy_attachment" "api_invoke_access" {
  role       = aws_iam_role.authenticated_user_role.name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Hoặc attach vào một role hiện có theo tên
resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
  role       = "MyExistingRole"
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

Các outputs chính từ API module mà bạn có thể sử dụng cho IAM policies là:

• module.my_api.api_execution_arn - Để cấp quyền execute-api:Invoke
• module.my_api.api_arn - API Gateway ARN
• module.my_api.lambda_function_arn - Lambda function ARN

Phát triển Local

Generator cấu hình một local development server mà bạn có thể chạy với:

pnpm

pnpm nx serve my-api

yarn

yarn nx serve my-api

npm

npx nx serve my-api

bun

bunx nx serve my-api

Điều này khởi động một local FastAPI development server với:

• Auto-reload khi có thay đổi code
• Tài liệu API tương tác tại /docs hoặc /redoc
• OpenAPI schema tại /openapi.json

Gọi FastAPI của bạn

Để gọi API của bạn từ một React website, bạn có thể sử dụng connection generator.

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

React to FastAPIGọi Python FastAPI từ một trang web React

FastAPI to Python DynamoDBKết nối FastAPI với bảng DynamoDB