基于AWS Amplify的仅后端实现：Unity游戏GraphQL API对接咨询

架构老林

2026-7-30

独立后端GraphQL架构搭建+API文档生成方案（适配Unity客户端）

一、基于现有Amplify/Cognito资源的后端架构选型

不用浪费现有全栈资源，直接剥离前端React相关依赖，专注搭建纯后端服务：

核心采用AWS Amplify CLI构建GraphQL API，搭配TypeScript编写 resolver 业务逻辑，复用现有Cognito身份验证体系——Unity客户端可通过Cognito的Unity SDK获取JWT令牌，携带令牌调用GraphQL接口，实现无缝兼容。
后端仅维护amplify/backend目录下的资源配置，绝不引入React相关依赖；前端侧的Amplify配置（如aws-exports.js）直接转换为Unity可用的参数（用户池ID、客户端ID、GraphQL端点）提供给Unity团队。

初始化纯后端项目
执行Amplify初始化命令，跳过前端框架配置：
```
amplify init
```
选择No跳过前端设置，进入后端资源配置流程，添加GraphQL API：
```
amplify add api
```
选择GraphQL类型，通过Schema定义数据模型（如游戏玩家、分数等），并绑定Cognito权限规则：
```
type GamePlayer @model @auth(rules: [{ allow: authenticated }]) {
  id: ID!
  username: String!
  score: Int!
}
```
生成TypeScript resolver模板后，在amplify/backend/api/<你的API名称>/src/resolvers目录下编写自定义业务逻辑。
绑定Cognito身份验证
用Amplify CLI快速添加Cognito用户池：
```
amplify add auth
```
配置密码策略、多因素认证等规则，确保GraphQL的@auth规则与Cognito联动——Unity客户端只需在GraphQL请求头中携带Authorization: Bearer <Cognito令牌>，即可访问受保护的接口。
部署后端服务
执行部署命令将资源推至AWS：
```
amplify push
```
部署完成后，后端团队可获取GraphQL端点URL、Cognito用户池ID、客户端ID等核心配置，直接同步给Unity团队。

Unity团队大多不熟悉Amplify前端工具，需提供标准化、接地气的对接文档：

自动生成GraphQL Schema文档：使用graphql-codegen工具生成Markdown格式的API文档，步骤如下：
1. 安装依赖：
```
npm install -D @graphql-codegen/cli @graphql-codegen/graphql-markdown
```
2. 创建codegen.yml配置文件：
```
schema: ./amplify/backend/api/<你的API名称>/schema.graphql
generates:
  ./docs/graphql-api-docs.md:
    plugins:
      - 'graphql-markdown'
```
3. 执行命令生成文档：
```
npx graphql-codegen
```
  生成的文档包含所有查询、突变、订阅的定义、字段说明及权限规则，清晰易懂。
补充Unity专属对接指南：在文档中添加以下内容：
- Cognito获取令牌的Unity SDK调用示例
- Unity中发送GraphQL请求的代码示例（如使用UnityWebRequest或第三方库GraphQL.Client）
- 常见错误码及排查方法
提供Postman测试集合：将带身份验证的GraphQL请求导出为Postman集合，Unity团队可直接导入测试，无需自行编写请求模板。

内容的提问来源于stack exchange，提问作者Mahdi Mehrizi