Smithy API 连接到关系数据库

connection 生成器将 Smithy API 连接到 关系数据库项目，将 Prisma 客户端注入到服务上下文中，以便所有操作实现都可以访问数据库。

前置条件

在使用此生成器之前，请确保您拥有：

1. 一个 ts#smithy-api 项目（TypeScript 后端）
2. 一个 ts#rdb 项目

使用方法

运行生成器

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

选择您的 Smithy API 后端项目作为源，选择您的关系数据库项目作为目标。

选项

参数	类型	默认值	描述
sourceProject 必需	string	-	源项目
targetProject 必需	string	-	要连接到的目标项目
sourceComponent	string	-	要从其连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。
targetComponent	string	-	要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。

生成器输出

生成器会修改 Smithy API 后端中的三个现有文件：

• 文件夹packages/api/src

  • context.ts 将 db 属性添加到 ServiceContext
  • handler.ts 在 lambdaHandler 内创建 Prisma 客户端，传递给 serviceHandler.handle
  • local-server.ts 在请求处理程序内创建 Prisma 客户端，传递给 serviceHandler.handle

此外，它还会更新 API 的 serve-local 目标以自动启动数据库。

工作原理

ServiceContext

生成器在 context.ts 中向 ServiceContext 添加一个类型化的 db 属性：

packages/api/src/context.ts

import { getPrisma as getMyDb } from ':my-scope/my-db';

export interface ServiceContext {
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  myDb: Awaited<ReturnType<typeof getMyDb>>;
}

Lambda 处理程序

Prisma 客户端在 lambdaHandler 内实例化，并通过服务上下文传递：

packages/api/src/handler.ts

import { getPrisma as getMyDb } from ':my-scope/my-db';

export const lambdaHandler = async (event: APIGatewayProxyEvent) => {
  const httpRequest = convertEvent(event);
  const myDb = await getMyDb();
  const httpResponse = await serviceHandler.handle(httpRequest, {
    tracer,
    logger,
    metrics,
    myDb,
  });
  return convertVersion1Response(httpResponse);
};

在操作中使用数据库

在操作实现中从上下文访问 db：

packages/api/src/operations/list-users.ts

import { ListUsersOperationInput, ListUsersOperationOutput } from '../generated/ssdk/index.js';
import { ServiceContext } from '../context.js';

export const listUsers = async (
  input: ListUsersOperationInput,
  ctx: ServiceContext,
): Promise<ListUsersOperationOutput> => {
  const users = await ctx.myDb.user.findMany();
  return { users };
};

基础设施

为了让您的 API 在运行时能够连接到数据库,API Lambda 函数必须部署到与数据库相同的 VPC 中,并被授予网络和 IAM 访问权限。

CDK

在您的应用程序堆栈中,将 API 部署到与数据库相同的 VPC 中,然后调用 allowDefaultPortFrom 和 grantConnect 来打开网络路径并为每个 Lambda 处理程序授予 IAM rds-db:connect 权限:

packages/infra/src/stacks/application-stack.ts

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

const db = new MyDatabase(this, 'Db', { vpc, ... });

const api = new MyApi(this, 'Api', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    })
    .build(),
});

Object.entries(api.integrations).forEach(([operation, integration]) => {
  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
  db.grantConnect(integration.handler);
});

将 API Lambda 函数部署到具有出口的私有子网中,而不是私有隔离子网。在运行时,getPrisma() 从 AWS AppConfig 检索数据库连接详细信息,这是一个需要出站互联网访问的公共 AWS 服务端点。

注意

此示例授予 API 中的每个处理程序访问权限,但如果只有某些处理程序需要访问权限,最好单独配置。

Terraform

将数据库模块输出传递到您的 API 模块中,以便它可以访问数据库并读取其运行时配置:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
  lambda_subnet_ids   = module.vpc.private_subnet_ids
}

module "api" {
  source             = "..."
  vpc_id             = module.vpc.vpc_id
  private_subnet_ids = module.vpc.private_subnet_ids

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port

  environment_variables = {
    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
  }
}

将 API Lambda 函数部署到具有出口的私有子网中,而不是私有隔离子网。确保 API Lambda 角色具有 rds-db:connect 权限,并且其安全组可以在数据库端口上访问数据库安全组。

本地开发

生成器在 local-server.ts 的请求处理程序内应用相同的 Prisma 客户端注入：

packages/api/src/local-server.ts

import { getPrisma as getMyDb } from ':my-scope/my-db';

const server = createServer(async function (req, res) {
  const httpRequest = convertRequest(req);
  const myDb = await getMyDb();
  const httpResponse = await serviceHandler.handle(httpRequest, {
    tracer,
    logger,
    metrics,
    myDb,
  });
  return writeResponse(httpResponse, res);
});

pnpm

pnpm nx serve-local <api-project-name>

yarn

yarn nx serve-local <api-project-name>

npm

npx nx serve-local <api-project-name>

bun

bunx nx serve-local <api-project-name>

这将同时启动 API 和本地数据库。SERVE_LOCAL=true 环境变量会自动设置，因此 Prisma 客户端会连接到本地 Docker 数据库而不是 Aurora。