用途
该技能用于为 GraphQL API 编写 AWS AppSync JavaScript（APPSYNC_JS）解析器。当需要创建、修改或调试 AppSync 解析器时使用。解析器使用 APPSYNC_JS 运行时，以熟悉的 JavaScript 语法将 GraphQL 操作连接到数据源。
核心模式
每个解析器导出 request 函数和 response 函数：
export function request(ctx) { // 使用 ctx.args、ctx.identity、ctx.source 等构建数据源请求 return { /* data source request */ }; }
export function response(ctx) { // 转换并返回数据源响应 return ctx.result; }
ctx（上下文）对象提供：
- ctx.args — GraphQL 字段参数
- ctx.result — 数据源响应（在 response 处理器中）
- ctx.error — 来自数据源的错误（如有）
- ctx.identity — 调用者身份（Cognito、IAM 等）
- ctx.source — 父字段值（用于嵌套解析器）
- ctx.info — 字段名、父类型、选择集
- ctx.prev.result — 上一个函数的结果（管道解析器）
- ctx.stash — 管道函数间共享的对象
- ctx.request — 请求头
导入
import { util } from '@aws-appsync/utils'; import * as ddb from '@aws-appsync/utils/dynamodb'; import { sql, select, insert, update, remove, createPgStatement, createMySQLStatement, toJsonObject } from '@aws-appsync/utils/rds';
只导入所需内容。@aws-appsync/utils/dynamodb 模块提供高层辅助函数，@aws-appsync/utils/rds 模块提供 SQL 构建器。
选择合适的数据源
- DynamoDB：NoSQL 键值/文档存储 — 最常用
- HTTP：REST API、API Gateway 或 AWS 服务 API（SNS、Translate 等）
- Lambda：无法在 APPSYNC_JS 中运行的复杂业务逻辑
- RDS：通过 Data API 访问 Aurora PostgreSQL/MySQL
- OpenSearch：全文搜索、地理查询、分析
- EventBridge：事件驱动架构、发布事件
- NONE：本地操作 — 订阅、转换、无外部调用
参考文件
每个数据源都有专门的参考文件，包含完整代码示例：
- references/dynamodb.md — DynamoDB CRUD、查询、批量操作、扫描、分页
- references/http.md — HTTP 请求、API Gateway、SNS、AWS Translate
- references/rds.md — 使用 select/sql 构建器的 Aurora PostgreSQL/MySQL
- references/opensearch.md — 全文搜索、地理、分页
- references/lambda-eventbridge-none.md — Lambda 调用、EventBridge PutEvents、本地发布、增强订阅
- references/pipeline.md — 管道解析器（链接多个函数）
APPSYNC_JS 运行时限制
APPSYNC_JS 运行时不支持：
- for / while / do...while 循环 — 改用 .forEach()、.map()、.filter()、.reduce()
- Array.sort() — 不可用；通过 .forEach() 在拼接数组上实现合并逻辑
- 数组方法回调中的箭头函数 — 可能导致回调参数的 ReferenceError。始终使用传统函数表达式：
// 错误 — 箭头函数参数在运行时可能为 undefined items.forEach((item) => { doSomething(item) })
// 正确 — 传统函数表达式 items.forEach(function (item) { doSomething(item) })
- try / catch / finally — 改用 ctx.error 检查
- async / await — 不支持
- 类、生成器、符号、WeakRef、eval
- UpdateItem 中的 returnValues — 不支持；错误：Unsupported element '$[returnValues]'。UpdateItem 后的 ctx.result 为空（无更新属性）。可在前端使用乐观计数，或添加后续 GetItem 管道函数读取更新值
错误处理
根据严重程度有两种模式：
// 硬错误 — 停止执行并向客户端返回错误 if (ctx.error) { util.error(ctx.error.message, ctx.error.type); }
// 软错误 — 追加错误但仍返回数据 util.appendError(body, statusCode);
常用工具函数
- util.autoId() — 生成唯一 ID
- util.time.nowISO8601() — 当前时间戳
- util.dynamodb.toMapValues({ id }) — 将 JS 对象转换为 DynamoDB 属性映射
- util.transform.toSubscriptionFilter() — 构建订阅过滤器
- util.xml.toMap(body) — 将 XML 解析为对象
- util.urlEncode(str) — 对字符串进行 URL 编码
- util.http.copyHeaders(ctx.request.headers) — 复制请求头
开发环境设置
安装 AppSync 工具以进行类型检查和编辑器支持：
npm install @aws-appsync/utils @aws-appsync/eslint-plugin
使用 JSDoc 类型注解以获得更好的 IDE 支持：
/** @param {import('@aws-appsync/utils').Context<{id: string}>} ctx */ export function request(ctx) { ... }
适用场景
适用于需要为 AWS AppSync GraphQL API 编写、修改或调试 JavaScript 解析器的开发场景，尤其是涉及 DynamoDB、HTTP、Lambda、RDS、OpenSearch、EventBridge 等数据源集成时。
限制
需遵守 APPSYNC_JS 运行时的上述限制，例如不支持循环、try/catch、async/await、Array.sort() 等。