API TypeScript của Smithy

Smithy là một ngôn ngữ định nghĩa giao diện độc lập với giao thức để tạo API theo cách hướng mô hình.

Trình tạo Smithy TypeScript API tạo một API mới sử dụng Smithy để định nghĩa dịch vụ, và Smithy TypeScript Server SDK để triển khai. Trình tạo cung cấp infrastructure as code bằng CDK hoặc Terraform để triển khai dịch vụ của bạn lên AWS Lambda, được truy cập thông qua AWS API Gateway REST API. Nó cung cấp phát triển API an toàn kiểu với tự động tạo mã từ mô hình Smithy. Handler được tạo sử dụng AWS Lambda Powertools for TypeScript cho khả năng quan sát, bao gồm logging, AWS X-Ray tracing và CloudWatch Metrics

Sử dụng

Tạo một Smithy TypeScript API

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

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#smithy-api
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#smithy-api

yarn

yarn nx g @aws/nx-plugin:ts#smithy-api

npm

npx nx g @aws/nx-plugin:ts#smithy-api

bun

bunx nx g @aws/nx-plugin:ts#smithy-api

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#smithy-api --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#smithy-api --dry-run

npm

npx nx g @aws/nx-plugin:ts#smithy-api --dry-run

bun

bunx nx g @aws/nx-plugin:ts#smithy-api --dry-run

Tùy chọn

Parameter	Type	Default	Description
name Required	string	-	The name of the API (required). Used to generate class names and file paths.
namespace	string	-	The namespace for the Smithy API. Defaults to your monorepo scope
computeType	string	ServerlessApiGatewayRestApi	The type of compute to use to deploy this API.
auth	string	IAM	The method used to authenticate with your API. Choose between IAM (default), Cognito or None.
directory	string	packages	The directory to store the application in.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Kết quả của Trình tạo

Trình tạo tạo hai dự án liên quan trong thư mục <directory>/<api-name>:

• Thư mụcmodel/ Dự án mô hình Smithy

  • project.json Cấu hình dự án và build targets
  • smithy-build.json Cấu hình build Smithy
  • build.Dockerfile Cấu hình Docker để build các artifact Smithy
  • Thư mụcsrc/

    • main.smithy Định nghĩa dịch vụ chính
    • Thư mụcoperations/

      • echo.smithy Ví dụ định nghĩa operation
• Thư mụcbackend/ Triển khai backend TypeScript

  • project.json Cấu hình dự án và build targets
  • rolldown.config.ts Cấu hình bundle
  • Thư mụcsrc/

    • handler.ts AWS Lambda handler
    • local-server.ts Server phát triển local
    • service.ts Triển khai dịch vụ
    • context.ts Định nghĩa context dịch vụ
    • Thư mụcoperations/

      • echo.ts Ví dụ triển khai operation
    • Thư mụcgenerated/ TypeScript SDK được tạo (tạo trong quá trình build)

      • …

Infrastructure

Vì trình tạo này tạo 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 tương ứng.

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ể cho một dự án/trình tạo

      • Thư mụcapis/

        • <project-name>.ts CDK construct để triển khai API của bạn
    • Thư mụccore/ Constructs chung được tái sử dụng bởi constructs trong app

      • Thư mụcapi/

        • rest-api.ts CDK construct để triển khai REST API
        • utils.ts Tiện ích cho API constructs
    • index.ts Entry point xuất các constructs từ app
  • project.json Build targets và cấu hình dự án

Ghi chú

Dự án này được tạo bằng trình tạo 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ể cho một dự án/trình tạo

      • Thư mụcapis/

        • Thư mục<project-name>/

          • <project-name>.tf Module để triển khai API của bạn
    • Thư mụccore/ Modules chung được tái sử dụng bởi modules trong app

      • Thư mụcapi/

        • Thư mụcrest-api/

          • rest-api.tf Module để triển khai REST API
  • project.json Build targets và cấu hình dự án

Ghi chú

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

Triển khai Smithy API của bạn

Định nghĩa Operations trong Smithy

Operations được định nghĩa trong các file Smithy trong dự án model. Định nghĩa dịch vụ chính nằm trong main.smithy:

$version: "2.0"

namespace your.namespace

use aws.protocols#restJson1
use smithy.framework#ValidationException

@title("YourService")
@restJson1
service YourService {
    version: "1.0.0"
    operations: [
        Echo,
        // Thêm operations của bạn ở đây
    ]
    errors: [
        ValidationException
    ]
}

Các operations riêng lẻ được định nghĩa trong các file riêng biệt trong thư mục operations/:

$version: "2.0"

namespace your.namespace

@http(method: "POST", uri: "/echo")
operation Echo {
    input: EchoInput
    output: EchoOutput
}

structure EchoInput {
    @required
    message: String

    foo: Integer
    bar: String
}

structure EchoOutput {
    @required
    message: String
}

Ghi chú

Bạn có thể thay đổi cấu trúc thư mục tùy thích - tất cả các file .smithy trong thư mục src sẽ được bao gồm trong Smithy build.

Mẹo

Để biết thêm chi tiết về Smithy và cú pháp của nó, tham khảo đặc tả Smithy.

Triển khai Operations trong TypeScript

Các triển khai operation nằm trong thư mục src/operations/ của dự án backend. Mỗi operation được triển khai sử dụng các kiểu được tạo từ TypeScript Server SDK (được tạo tại thời điểm build từ mô hình Smithy của bạn).

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input) => {
  // Logic nghiệp vụ của bạn ở đây
  return {
    message: `Echo: ${input.message}` // an toàn kiểu dựa trên mô hình Smithy của bạn
  };
};

Operations phải được đăng ký vào định nghĩa dịch vụ trong src/service.ts:

import { ServiceContext } from './context.js';
import { YourServiceService } from './generated/ssdk/index.js';
import { Echo } from './operations/echo.js';
// Import các operations khác ở đây

// Đăng ký operations vào dịch vụ ở đây
export const Service: YourServiceService<ServiceContext> = {
  Echo,
  // Thêm các operations khác ở đây
};

Service Context

Bạn có thể định nghĩa context được chia sẻ cho các operations của bạn trong context.ts:

export interface ServiceContext {
  // Powertools tracer, logger và metrics được cung cấp mặc định
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  // Thêm các dependencies được chia sẻ, kết nối database, v.v.
  dbClient: any;
  userIdentity: string;
}

Context này được truyền cho tất cả các triển khai operation và có thể được sử dụng để chia sẻ tài nguyên như kết nối database, cấu hình, hoặc tiện ích logging.

Chú ý

Bạn phải tự xây dựng context trong cả handler.ts (điểm vào của Lambda function) và local-server.ts (điểm vào để chạy locally thông qua target serve).

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

Logging

Trình tạo cấu hình structured logging sử dụng AWS Lambda Powertools với tự động inject context thông qua Middy middleware.

handler.ts

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Bạn có thể tham chiếu logger từ các triển khai operation của bạn thông qua context:

operations/echo.ts

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.logger.info('Thông điệp log của bạn');
  // ...
};

Tracing

AWS X-Ray tracing được cấu hình tự động thông qua middleware captureLambdaHandler.

handler.ts

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Bạn có thể thêm subsegments tùy chỉnh vào traces của bạn trong các operations:

operations/echo.ts

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  // Tạo một subsegment mới
  const subsegment = ctx.tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Logic của bạn ở đây
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

Metrics

CloudWatch metrics được thu thập tự động cho mỗi request thông qua middleware logMetrics.

handler.ts

export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Bạn có thể thêm custom metrics trong các operations của bạn:

operations/echo.ts

import { MetricUnit } from '@aws-lambda-powertools/metrics';
import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';

export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  // ...
};

Xử lý Lỗi

Smithy cung cấp xử lý lỗi tích hợp sẵn. Bạn có thể định nghĩa các lỗi tùy chỉnh trong mô hình Smithy của bạn:

@error("client")
@httpError(400)
structure InvalidRequestError {
    @required
    message: String
}

Và đăng ký chúng vào operation/service của bạn:

operation MyOperation {
  ...
  errors: [InvalidRequestError]
}

Sau đó ném chúng trong triển khai TypeScript của bạn:

import { InvalidRequestError } from '../generated/ssdk/index.js';

export const MyOperation: MyOperationHandler<ServiceContext> = async (input) => {
  if (!input.requiredField) {
    throw new InvalidRequestError({
      message: "Trường bắt buộc bị thiếu"
    });
  }

  return { /* phản hồi thành công */ };
};

Building và Tạo Mã

Dự án mô hình Smithy sử dụng Docker để build các artifact Smithy và tạo TypeScript Server SDK:

pnpm

pnpm nx run <model-project>:build

yarn

yarn nx run <model-project>:build

npm

npx nx run <model-project>:build

bun

bunx nx run <model-project>:build

Quá trình này:

1. Biên dịch mô hình Smithy và xác thực nó
2. Tạo đặc tả OpenAPI từ mô hình Smithy
3. Tạo TypeScript Server SDK với các giao diện operation an toàn kiểu
4. Xuất các build artifacts ra dist/<model-project>/build/

Dự án backend tự động sao chép SDK được tạo trong quá trình biên dịch:

pnpm

pnpm nx run <backend-project>:copy-ssdk

yarn

yarn nx run <backend-project>:copy-ssdk

npm

npx nx run <backend-project>:copy-ssdk

bun

bunx nx run <backend-project>:copy-ssdk

Bundle Target

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

pnpm

pnpm nx run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Mẹo

Bạn có thể điều chỉnh cấu hình cho Rolldown trong rolldown.config.ts, ví dụ nếu bạn có các dependency phụ thuộc vào đường dẫn file và không thể được bundle, bạn có thể thêm chúng vào danh sách các module external.

Phát triển Local

Trình tạo cấu hình một server phát triển local với hot reloading:

pnpm

pnpm nx run <backend-project>:serve

yarn

yarn nx run <backend-project>:serve

npm

npx nx run <backend-project>:serve

bun

bunx nx run <backend-project>:serve

Mẹo

Server local sẽ không chỉ hot-reload khi bạn thực hiện thay đổi TypeScript cho mã backend của bạn, mà còn reload khi bạn thực hiện thay đổi cho dự án mô hình Smithy của bạn, cho phép bạn liên tục lặp lại trên mô hình Smithy và server cùng nhau.

Triển khai Smithy API của bạn

Trình tạo tạo infrastructure CDK hoặc Terraform dựa trên iacProvider bạn đã chọn.

CDK

CDK construct để triển khai API của bạn nằm trong thư mục common/constructs:

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 dịch vụ Smithy
2. API Gateway REST API làm trigger cho function
3. IAM roles và permissions
4. CloudWatch log group
5. Cấu hình X-Ray tracing

Ghi chú

Nếu bạn đã chọn 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 trình tạo ts#react-website-auth

Terraform

Các Terraform modules để triển khai API của bạn nằm trong thư mục common/terraform:

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

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

  # Các 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ụ Smithy API
2. API Gateway REST API làm trigger cho function
3. IAM roles và permissions
4. CloudWatch log group
5. Cấu hình X-Ray tracing
6. Cấu hình CORS

Ghi chú

Nếu bạn đã chọn 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"

  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
}

Terraform module cung cấp một số outputs:

# 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
}

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

Ghi chú

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"

  # 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: [...],
}));

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"

  # 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
}

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 chú

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 chú

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

Để 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 = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, 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 = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, 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 = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, 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 = merge({
       AWS_CONNECTION_REUSE_ENABLED = "1"
     }, 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}/*/*"
 }

Router Pattern

CDK

Nếu bạn muốn triển khai một Lambda function duy nhất để phục vụ tất cả các request API, bạn có thể tự do chỉnh sửa phương thức defaultIntegrations cho API của mình để 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) => {
    const router = new Function(scope, 'RouterHandler', { ... });
    return IntegrationBuilder.rest({
      ...
      defaultIntegrationOptions: {},
      buildDefaultIntegration: (op) => {
        return {
          // Tham chiếu cùng một router lambda handler trong mọi tích hợp
          integration: new LambdaIntegration(router),
        };
      },
    });
  };
}

Bạn có thể sửa đổi code theo các cách khác nếu muốn, ví dụ bạn có thể muốn định nghĩa function router như một tham số cho defaultIntegrations thay vì xây dựng nó trong phương thức.

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"

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

Tạo Mã

CDK

Vì operations được định nghĩa trong Smithy, chúng tôi sử dụng tạo mã để cung cấp metadata cho CDK construct để có integrations an toàn kiểu.

Một target generate:<ApiName>-metadata được thêm vào project.json của common constructs để tạo điều kiện cho việc tạo mã này, xuất 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 kiểm soát phiên bản.

Ghi chú

Bạn sẽ cần chạy build bất cứ khi nào bạn thay đổi mô hình Smithy của mình để đảm bảo các kiểu được sử dụng bởi CDK construct được cập nhật.

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Mẹo

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

pnpm

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

yarn

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

npm

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

bun

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

Terraform

Ghi chú

Chúng tôi không hỗ trợ integrations an toàn kiểu cho Terraform, và do đó không có targets tạo mã nào được cấu hình nếu bạn đã chọn Terraform cho iacProvider của mình.

Cấp Quyền Truy cập (Chỉ IAM)

Nếu bạn đã chọn 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 bạn:

CDK

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Terraform

# Tạo một IAM policy để cho phép gọi API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "MyApiInvokePolicy"
  description = "Policy để cho phép gọi Smithy API"

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

# Đính kèm policy vào IAM role
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
}

Gọi Smithy API của bạn

Để gọi API của bạn từ một React website, bạn có thể sử dụng trình tạo api-connection, cung cấp tạo client an toàn kiểu từ mô hình Smithy của bạn.