跳转到内容
@aws/nx-plugin
Blog

AI地牢游戏

模块 2：游戏 API 实现

我们将从实现游戏 API 开始。为此需要创建 4 个 API：

  1. createGame - 创建新游戏实例
  2. queryGames - 返回分页的历史游戏列表
  3. saveAction - 保存指定游戏的操作记录
  4. queryActions - 返回分页的指定游戏所有操作记录

API 模式定义

使用 Zod 在 packages/game-api/schema/src 项目中定义 API 输入输出模式：

import { z } from 'zod';


export const ActionSchema = z.object({
  playerName: z.string(),
  timestamp: z.string().datetime(),
  role: z.enum(['assistant', 'user']),
  content: z.string(),
});


export type IAction = z.TypeOf<typeof ActionSchema>;

可以删除 ./procedures/echo.ts 文件，本项目不会使用。

实体建模

应用实体关系图如下：

dungeon-adventure-er.png

我们将使用 DynamoDB 实现数据库，并通过 ElectroDB 客户端库简化操作。首先安装依赖：

Terminal window
pnpm add -w electrodb @aws-sdk/client-dynamodb

在 packages/game-api/backend/src/entities 目录下创建实体文件：

import { Entity } from 'electrodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';


export const createActionEntity = (client?: DynamoDBClient) =>
  new Entity(
    {
      model: {
        entity: 'Action',
        version: '1',
        service: 'game',
      },
      attributes: {
        playerName: { type: 'string', required: true, readOnly: true },
        timestamp: {
          type: 'string',
          required: true,
          readOnly: true,
          set: () => new Date().toISOString(),
          default: () => new Date().toISOString(),
        },
        role: { type: 'string', required: true, readOnly: true },
        content: { type: 'string', required: true, readOnly: true },
      },
      indexes: {
        primary: {
          pk: { field: 'pk', composite: ['playerName'] },
          sk: { field: 'sk', composite: ['timestamp'] },
        },
      },
    },
    { client, table: process.env.TABLE_NAME },
  );

ElectroDB 功能强大，支持设置默认值（如时间戳）并遵循 DynamoDB 最佳实践的单表设计。

将 DynamoDB 客户端注入 tRPC 上下文

为在 API 过程中访问 DynamoDB 客户端，需创建单例并通过上下文传递。修改以下文件：

middleware/dynamodb.ts
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { initTRPC } from '@trpc/server';


export interface IDynamoDBContext {
  dynamoDb?: DynamoDBClient;
}


export const createDynamoDBPlugin = () => {
  const t = initTRPC.context<IDynamoDBContext>().create();
  return t.procedure.use(async (opts) => {
    const dynamoDb = new DynamoDBClient();


    const response = await opts.next({
      ctx: {
        ...opts.ctx,
        dynamoDb,
      },
    });


    return response;
  });
};

此插件用于创建 DynamoDBClient 并注入上下文。

定义 API 过程

在 packages/game-api/backend/src/procedures 中实现 API 方法：

import { createActionEntity } from '../entities/action.js';
import {
  ActionSchema,
  IAction,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from ':dungeon-adventure/game-api-schema';
import { publicProcedure } from '../init.js';
import { z } from 'zod';


export const queryActions = publicProcedure
  .input(QueryInputSchema.extend({ playerName: z.string() }))
  .output(createPaginatedQueryOutput(ActionSchema))
  .query(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const result = await actionEntity.query
      .primary({ playerName: input.playerName })
      .go({ cursor: input.cursor, count: input.limit });


    return {
      items: result.data as IAction[],
      cursor: result.cursor,
    };
  });

可删除 echo.ts 文件（位于 packages/game-api/backend/src/procedures）。

路由配置

更新路由文件整合 API：

packages/game-api/backend/src/router.ts
import {
  awsLambdaRequestHandler,
  CreateAWSLambdaContextOptions,
} from '@trpc/server/adapters/aws-lambda';
import { echo } from './procedures/echo.js';
import { t } from './init.js';
import { APIGatewayProxyEvent } from 'aws-lambda';
import { queryActions } from './procedures/query-actions.js';
import { saveAction } from './procedures/save-action.js';
import { queryGames } from './procedures/query-games.js';
import { saveGame } from './procedures/save-game.js';


export const router = t.router;


export const appRouter = router({
  echo,
  actions: router({
    query: queryActions,
    save: saveAction,
  }),
  games: router({
    query: queryGames,
    save: saveGame,
  }),
});


export const handler = awsLambdaRequestHandler({
  router: appRouter,
  createContext: (
    ctx: CreateAWSLambdaContextOptions<APIGatewayProxyEvent>,
  ) => ctx,
  responseMeta: () => ({
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': '*',
    },
  }),
});


export type AppRouter = typeof appRouter;

基础设施

最后更新基础设施以创建 DynamoDB 表并配置权限：

constructs/electrodb-table.ts
import { CfnOutput } from 'aws-cdk-lib';
import {
  AttributeType,
  BillingMode,
  ProjectionType,
  Table,
  TableProps,
} from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';


export type ElectrodbDynamoTableProps = Omit<
  TableProps,
  'partitionKey' | 'sortKey' | 'billingMode'
>;


export class ElectrodbDynamoTable extends Table {
  constructor(scope: Construct, id: string, props?: ElectrodbDynamoTableProps) {
    super(scope, id, {
      partitionKey: {
        name: 'pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'sk',
        type: AttributeType.STRING,
      },
      billingMode: BillingMode.PAY_PER_REQUEST,
      ...props,
    });


    this.addGlobalSecondaryIndex({
      indexName: 'gsi1pk-gsi1sk-index',
      partitionKey: {
        name: 'gsi1pk',
        type: AttributeType.STRING,
      },
      sortKey: {
        name: 'gsi1sk',
        type: AttributeType.STRING,
      },
      projectionType: ProjectionType.ALL,
    });


    new CfnOutput(this, 'TableName', { value: this.tableName });
  }
}

部署与测试

首先构建代码：

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

部署应用：

Terminal window
pnpm nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox

首次部署约需 8 分钟，后续部署约 2 分钟。

点击查看批量部署详情

部署完成后输出示例如下（部分值已脱敏）：

Terminal window
dungeon-adventure-infra-sandbox
dungeon-adventure-infra-sandbox: deploying... [2/2]


 ✅  dungeon-adventure-infra-sandbox


✨  部署时间: 354s


输出:
dungeon-adventure-infra-sandbox.ElectroDbTableTableNameXXX = dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY
dungeon-adventure-infra-sandbox.GameApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-infra-sandbox.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
dungeon-adventure-infra-sandbox.StoryApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-infra-sandbox.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
dungeon-adventure-infra-sandbox.UserIdentityUserIdentityUserPoolIdXXX = region_xxx

测试方式：

  • 本地启动 tRPC 后端并通过 curl 调用 API
  • 调用已部署 API

启动本地服务：

Terminal window
TABLE_NAME=dungeon-adventure-infra-sandbox-ElectroDbTableXXX-YYY pnpm nx run @dungeon-adventure/game-api:serve

调用示例：

Terminal window
curl -X GET 'http://localhost:2022/games.query?input=%7B%7D'

成功响应示例：

{"result":{"data":{"items":[],"cursor":null}}}

恭喜！你已成功使用 tRPC 构建并部署首个 API！🎉🎉🎉