AI地牢游戏

模块二：游戏API实现

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

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

API模式定义

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

action.ts

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

common.ts

import { z } from 'zod';

export const QueryInputSchema = z.object({
  cursor: z.string().optional(),
  limit: z.number().optional().default(100),
});

export const createPaginatedQueryOutput = <ItemType extends z.ZodTypeAny>(
  itemSchema: ItemType,
) => {
  return z.object({
    items: z.array(itemSchema),
    cursor: z.string().nullable(),
  });
};

export type IQueryInput = z.TypeOf<typeof QueryInputSchema>;

game.ts

import { z } from 'zod';

export const GameSchema = z.object({
  playerName: z.string(),
  genre: z.enum(['zombie', 'superhero', 'medieval']),
  lastUpdated: z.string().datetime(),
});

export type IGame = z.TypeOf<typeof GameSchema>;

index.ts

export * from './echo.js'
export * from './action.js';
export * from './common.js';
export * from './game.js';

可删除packages/game-api/src/schema/echo.ts文件，本项目不再使用。

提示

如上所示，每个Zod模式定义都通过z.TypeOf语法导出接口类型。这实现了Zod定义到TypeScript接口的自动转换，无需重复工作！

实体建模

应用实体关系图如下：

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

pnpm

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

yarn

yarn add electrodb @aws-sdk/client-dynamodb

npm

npm install --legacy-peer-deps electrodb @aws-sdk/client-dynamodb

bun

bun install electrodb @aws-sdk/client-dynamodb

注意

所有依赖项都添加到根目录package.json，因@aws/nx-plugin遵循单一版本策略。更多信息请参考TS项目指南。

在packages/game-api/src/entities目录下创建以下文件定义ElectroDB实体：

action.ts

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

game.ts

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

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

ElectroDB不仅支持类型定义，还能为时间戳等字段提供默认值。同时遵循DynamoDB最佳实践——单表设计。

注意

虽然ElectroDB支持集合，但本教程为简化流程暂不使用。

将DynamoDB客户端注入tRPC上下文

为在所有流程中共享DynamoDB客户端实例，需通过上下文传递。修改以下文件：

middleware/dynamodb.ts

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并注入上下文。

middleware/index.ts

middleware/index.ts

import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
import type { APIGatewayProxyEvent } from 'aws-lambda';
import { ILoggerContext } from './logger.js';
import { IMetricsContext } from './metrics.js';
import { ITracerContext } from './tracer.js';
import { IDynamoDBContext } from './dynamodb.js';

export * from './dynamodb.js';
export * from './logger.js';
export * from './metrics.js';
export * from './tracer.js';
export * from './error.js';

export type IMiddlewareContext =
  CreateAWSLambdaContextOptions<APIGatewayProxyEvent> &
    IDynamoDBContext &
    ILoggerContext &
    IMetricsContext &
    ITracerContext;

扩展IMiddlewareContext添加IDynamoDBContext。

init.ts

init.ts

import { initTRPC } from '@trpc/server';
import {
  createDynamoDBPlugin,
  createErrorPlugin,
  createLoggerPlugin,
  createMetricsPlugin,
  createTracerPlugin,
  IMiddlewareContext,
} from './middleware/index.js';

process.env.POWERTOOLS_SERVICE_NAME = 'GameApi';
process.env.POWERTOOLS_METRICS_NAMESPACE = 'GameApi';

export type Context = IMiddlewareContext;

export const t = initTRPC.context<Context>().create();

export const publicProcedure = t.procedure
  .concat(createDynamoDBPlugin())
  .concat(createLoggerPlugin())
  .concat(createTracerPlugin())
  .concat(createMetricsPlugin())
  .concat(createErrorPlugin());

DynamoDB插件已集成。

注意

concat API将中间件绑定到流程定义。详情参考concat指南。

定义流程

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

query-actions.ts

import { createActionEntity } from '../entities/action.js';
import {
  ActionSchema,
  IAction,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from '../schema/index.js';
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,
    };
  });

query-games.ts

import { createGameEntity } from '../entities/game.js';
import {
  GameSchema,
  IGame,
  QueryInputSchema,
  createPaginatedQueryOutput,
} from '../schema/index.js';
import { publicProcedure } from '../init.js';

export const queryGames = publicProcedure
  .input(QueryInputSchema)
  .output(createPaginatedQueryOutput(GameSchema))
  .query(async ({ input, ctx }) => {
    const gameEntity = createGameEntity(ctx.dynamoDb);
    const result = await gameEntity.scan.go({
      cursor: input.cursor,
      count: input.limit,
    });

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

save-action.ts

import { ActionSchema, IAction } from '../schema/index.js';
import { publicProcedure } from '../init.js';
import { createActionEntity } from '../entities/action.js';
import { createGameEntity } from '../entities/game.js';

export const saveAction = publicProcedure
  .input(ActionSchema.omit({ timestamp: true }))
  .output(ActionSchema)
  .mutation(async ({ input, ctx }) => {
    const actionEntity = createActionEntity(ctx.dynamoDb);
    const gameEntity = createGameEntity(ctx.dynamoDb);

    const action = await actionEntity.put(input).go();
    await gameEntity
      .update({ playerName: input.playerName })
      .set({ lastUpdated: action.data.timestamp })
      .go();
    return action.data as IAction;
  });

save-game.ts

import { createGameEntity } from '../entities/game.js';
import { GameSchema, IGame } from '../schema/index.js';
import { publicProcedure } from '../init.js';

export const saveGame = publicProcedure
  .input(GameSchema.omit({ lastUpdated: true }))
  .output(GameSchema)
  .mutation(async ({ input, ctx }) => {
    const gameEntity = createGameEntity(ctx.dynamoDb);

    const result = await gameEntity.put(input).go();
    return result.data as IGame;
  });

可删除packages/game-api/src/procedures/echo.ts文件。

路由配置

更新路由文件整合流程：

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

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';
import { suppressRules } from ':dungeon-adventure/common-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,
    });

    // Suppress checkov rules that expect a KMS customer managed key and backup to be enabled
    suppressRules(this, ['CKV_AWS_119', 'CKV_AWS_28'], 'No need for custom encryption or backup');

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

stacks/application-stack.ts

stacks/application-stack.ts

import {
  GameApi,
  GameUI,
  StoryApi,
  UserIdentity,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { ElectrodbDynamoTable } from '../constructs/electrodb-table.js';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const userIdentity = new UserIdentity(this, 'UserIdentity');

    const electroDbTable = new ElectrodbDynamoTable(this, 'ElectroDbTable');

    const gameApi = new GameApi(this, 'GameApi', {
      integrations: GameApi.defaultIntegrations(this).build(),
      integrations: GameApi.defaultIntegrations(this)
        .withDefaultOptions({
          environment: {
            TABLE_NAME: electroDbTable.tableName,
          },
        })
        .build(),
    });

    // Grant read/write access to each procedure's lambda handler according to the permissions it requires
    electroDbTable.grantReadData(gameApi.integrations['actions.query'].handler);
    electroDbTable.grantReadData(gameApi.integrations['games.query'].handler);
    electroDbTable.grantReadWriteData(
      gameApi.integrations['actions.save'].handler,
    );
    electroDbTable.grantReadWriteData(
      gameApi.integrations['games.save'].handler,
    );

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

    // grant our authenticated role access to invoke our APIs
    [storyApi, gameApi].forEach((api) =>
      api.grantInvokeAccess(userIdentity.identityPool.authenticatedRole),
    );

    // Ensure this is instantiated last so our runtime-config.json can be automatically configured
    new GameUI(this, 'GameUI');
  }
}

注意

由于每个流程由独立Lambda函数处理，可根据实现按需分配最小读写权限。

部署与测试

首先构建代码：

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

提示

若出现lint错误，可运行以下命令自动修复：

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

部署应用：

pnpm

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

yarn

yarn nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/*

npm

npx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/*

bun

bunx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/*

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

提示

迭代Lambda代码时，构建后使用--hotswap标志可大幅缩短部署时间（2-3秒）：

pnpm

pnpm nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

yarn

yarn nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

npm

npx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

bun

bunx nx run @dungeon-adventure/infra:deploy dungeon-adventure-infra-sandbox/* --hotswap

部署完成后将看到类似输出（部分值已脱敏）：

dungeon-adventure-sandbox-Application
dungeon-adventure-sandbox-Application: deploying... [2/2]

 ✅  dungeon-adventure-sandbox-Application

✨  Deployment time: 354s

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

测试方式：

• 本地启动tRPC后端，使用curl调用API
• 调用已部署API（需Sigv4签名）

本地测试

运行以下命令启动本地服务：

pnpm

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

yarn

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY yarn nx run @dungeon-adventure/game-api:serve

npm

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY npx nx run @dungeon-adventure/game-api:serve

bun

TABLE_NAME=dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY bunx nx run @dungeon-adventure/game-api:serve

警告

使用CDK部署输出中的dungeon-adventure-infra-sandbox-Application.ElectroDbTableTableNameXXX替换高亮占位符。

服务启动后执行：

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

云端测试

acurl ap-southeast-2 execute-api -X GET 'https://xxx.execute-api.ap-southeast-2.amazonaws.com/prod/games.query?input=%7B%7D'

警告

使用CDK输出中的dungeon-adventure-infra-sandbox-Application.GameApiGameApiEndpointXXX替换URL，并设置正确区域。

注意

%7B%7D是URI编码的空JSON对象{}。

成功执行后将返回：

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

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