Awesome Copilot 实战用 APPSYNC_JS 运行时构建生产级 AWS AppSync Event API 处理器onPublish/onSubscribe 全指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本篇技术指南以仓库中的 AWS AppSync Event API Instructions 指令文档为主体面向在 GitHub Copilot 辅助下编写 AWS AppSyncEvent API事件 API处理器onPublish、onSubscribe的开发者。它系统性地覆盖APPSYNC_JS受限运行时规则、数据源选型与 IAM 最小权限配置、处理器流程模式、ctx.prev.result与ctx.stash的取舍、内置工具与aws-appsync/utils模块用法、批量操作、安全、工具链与可观测性。读完本文你将能依据一套可直接落地的规范让 Copilot 生成符合 Event API 运行时约束、可测试、可上生产的处理器代码。指令文件的定位与生效方式在深入技术细节之前先说明这份指南在项目中的角色。它是一个标准的*.instructions.md自定义指令文件通过 YAML frontmatter 声明自己的适用范围--- description: Production-grade guidance for AWS AppSync Event API handlers using APPSYNC_JS runtime restrictions, utilities, modules, and datasource patterns applyTo: **/*.{graphql,gql,vtl,ts,js,mjs,cjs,json,yml,yaml} ---description说明该指令的用途与覆盖范围——面向使用APPSYNC_JS运行时、涉及运行时限制、工具、模块与数据源模式的 Event API 处理器。applyToglob 模式指定这些规则自动应用到哪些文件——graphql、gql、vtl、ts、js、mjs、cjs、json、yml、yaml等 Event API 相关文件均会被命中。根据仓库 自定义指令使用说明安装与启用这类指令文件有两种典型方式将其内容复制到工作区根目录的.github/copilot-instructions.md或放入.github/instructions/目录例如.github/instructions/aws-appsync.instructions.md安装后指令即会自动作用于 Copilot 的生成行为。仓库还提供了 指令文件编写规范其中对 frontmatter 字段description单引号字符串、applyToglob 规则、段落结构与指令海拔Goldilocks Zone有完整约定如果你要为团队自定义类似指令可先阅读该文件。贡献新指令的流程文件命名、存放目录、结构要求见 CONTRIBUTING.md。适用范围与核心契约本指南只用于实现 AWS AppSyncEvent API的处理器——即onPublish发布前钩子与onSubscribe订阅尝试时钩子运行环境为APPSYNC_JS运行时。设计处理器时应始终围绕频道命名空间channel namespace这条主线onPublish在广播之前运行它先于事件广播执行负责对事件进行校验、转换、持久化、授权或路由onSubscribe在订阅尝试时运行它决定是否允许订阅某个频道并可附带返回需要映射的数据。同时事件契约必须显式且稳定把频道路径channel path和事件负载payload的形状都视为对外 API 契约改动即可能破坏下游订阅者对负载字段的变更优先采用增量式additive修改避免删除或重命名既有字段防止破坏已上线订阅方。数据源选型地图Event API 处理器的 I/O 不依赖运行时自身的网络能力而是通过 AppSync 数据源完成。文档给出了一份按事件工作流需求选型的数据源地图数据源适用场景Lambda自定义计算、转换、编排、外部 AWS/服务集成DynamoDB低延迟的事件/状态持久化、基于键的读写RDSAurora关系型校验、联表查询、更强的关系完整性场景EventBridge将事件路由到更广泛的事件驱动架构OpenSearch对事件数据进行搜索与分析HTTP 端点通过 HTTP 调用外部 API 或 AWS 服务 APIBedrock模型推理以及在事件管道中做 AI 增强选型原则是每个跳点都要有明确理由鉴权、持久化、富化、路由只有在确有必要的多跳场景下才组合多个数据源避免为组合而组合。数据源创建与 IAM 配置必做Event API 的数据源配置顺序与权限模型有严格要求这是最容易在生成代码时被忽略的部分创建层级数据源应在Event API 级别创建随后以命名空间集成namespace integration的形式挂载到对应命名空间最小权限若使用服务角色service role只授予所需动作least privilege信任策略信任策略的 Principal 必须允许appsync.amazonaws.com承担该角色收紧信任尽可能用条件condition限制信任范围aws:SourceAccount限定为你的账户aws:SourceArn限定为具体的 AppSync API ARN或严格收敛的模式禁止复用不要为 AppSync 数据源访问复用宽泛的、跨服务的 IAM 角色。APPSYNC_JS 运行时限制必须遵守APPSYNC_JS是受限的 JavaScript 子集代码必须面向该环境编写而不是完整的 Node.js。Copilot 生成代码时最容易踩的坑就在这里规则如下禁用异步模式不使用 Promise、async/await或后台异步工作流禁用不支持的语句/运算符try/catch/finally、throw、while、C 风格for(;;)、continue、标签labels、不支持的 unary 运算符禁用网络与文件系统访问运行时内不得依赖网络或文件系统 I/O所有 I/O 一律走 AppSync 数据源禁用递归不能递归调用也不能把函数作为函数参数传递不依赖类或高级运行时特性超出文档支持范围的类与高级特性不要使用循环用for-of/for-in需要迭代时优先使用这两种形式。处理器流程模式Event API 处理器有两种基本形态选择取决于是否接入数据源无数据源集成直接返回转换后的事件处理器不调用数据源时直接返回转换后的ctx.events即可。示意如下export function onPublish(ctx) { // 对事件做轻量转换如附加元数据、过滤 return ctx.events.map((e) ({ ...e, processedAt: util.time.nowISO8601() })); }有数据源集成request(ctx) / response(ctx) 对象形式接入数据源的处理器必须返回带request(ctx)与response(ctx)的对象export function onPublish(ctx) { // request(ctx) 构造数据源请求response(ctx) 将结果映射为待广播事件 return { request: (ctx) ({ operation: Invoke, payload: { ... } }), response: (ctx) ctx.result.events, // 返回要广播的事件列表 }; }关键控制与路由原语runtime.earlyReturn(...)当业务逻辑决定跳过数据源调用与响应映射时使用提前终止当前处理器执行路由信息用ctx.info.channel.path、ctx.info.channel.segments、ctx.info.channelNamespace.name和ctx.info.operation驱动路由逻辑onPublish 数据源在response(ctx)中返回要广播的事件列表onSubscribe 数据源必须包含response(ctx)函数当无需后续映射时它可以为空。ctx.prev.result vs ctx.stash管道阶段数据传递当处理器内部使用 Pipeline 函数resolver/functions分步执行时数据交接方式要按语义选择机制适用场景ctx.prev.result逐步执行、下一步依赖上一步输出时作为默认的相邻管道函数数据交接机制ctx.stash需要跨多个管道阶段共享、且不只是紧邻上一步结果的数据规范同时给出两条约束ctx.stash只存放小而刻意选择的元数据如标志位、ID、关联上下文不要复制大负载当ctx.prev.result已能提供所需值时不要再把完整的前一步结果重复塞进ctx.stash。错误与授权流程禁止throw处理器内不用throw改用运行时支持的util.error(...)与util.appendError(...)模式发布失败返回显式运行时错误并携带安全消息不暴露内部细节业务级授权拒绝在处理器层级做授权拒绝时使用文档指定的 unauthorized 工具错误负载非敏感绝不暴露密钥、原始堆栈或内部标识符。内置工具util运行时安全的工具统一通过util提供包括编码类与运行时控制类编码工具util.urlEncode、util.urlDecodeutil.base64Encode、util.base64Decode运行时工具runtime.earlyReturn(obj)停止当前处理器执行跳过数据源调用与响应求值内置模块aws-appsync/utils优先使用aws-appsync/utils提供的官方模块保持代码声明式风格DynamoDB 模块import * as ddb from aws-appsync/utils/dynamodbRDS 模块import { ... } from aws-appsync/utils/rdsDynamoDB 用法优先使用模块辅助函数而非手写请求对象核心辅助get、put、remove、update、query、scan、sync批量辅助batchGet、batchPut、batchDelete事务辅助transactGet、transactWrite规范要点update时优先使用 increment / append / add / remove 之类的操作辅助做安全的补丁式变更模型键与索引设计为查询优先避免无正当理由使用scan需要正确性与乐观并发时使用条件conditions突发型发布流bursty publish优先用batchPut/batchDelete需要原子性时用transactWrite而不是大量单条目操作批次大小保持在服务/API 限制内并以确定性方式分块输入。Lambda 用法Event API 的 Lambda 数据源请求采用如下结构operation: Invoke可选invocationType: RequestResponse | Eventpayload按 Lambda 契约显式塑形指导原则处理流程依赖 Lambda 输出时用RequestResponse仅做 fire-and-forget 副作用时用Event在response(ctx)中校验ctx.result并映射到精确的出站事件形状Event API 处理器中 Lambda 操作只支持Invoke不要依赖 GraphQL 风格的BatchInvoke需要在 Event API 流程中对 Lambda 做批量时在一次Invoke中发送数组负载并在 Lambda 内部实现条目级聚合与部分失败处理。直接 Lambda 集成不写处理器代码如果整个命名空间行为可以集中放在 Lambda 中、且不需要APPSYNC_JS的 request/response 映射逻辑可以配置命名空间处理器的直接 Lambda 集成Behavior: DIRECT而不是编写onPublish/onSubscribe代码REQUEST_RESPONSE模式onPublishLambda 返回{ events?: OutgoingEvent[], error?: string }onSubscribeLambda 成功返回null拒绝返回{ error: string }EVENT模式异步调用AppSync 不等待 Lambda 响应发布时事件照常广播。在 request/response 模式中若 Lambda 返回error该错误在启用日志时被记录但不会作为详细的内部错误负载回传给客户端。HTTP / EventBridge / RDS / OpenSearch / Bedrock使用非 DynamoDB 数据源时HTTP返回resourcePath、method、可选paramsheaders、query、body检查ctx.result.statusCode、ctx.result.body与ctx.errorEventBridge使用operation: PutEvents从ctx.events构建确定性的事件条目RDS优先使用 SQL 辅助函数与createPgStatement/createMySQLStatement不要拼接不安全的 SQLOpenSearch请求路径/参数保持显式只从ctx.result映射必要字段Bedrock显式定义operationInvokeModel或Converse并包含提示注入prompt-injection防护。批量操作必读指导当目标数据源原生支持批量、且事件语义允许分组时优先批处理DynamoDB非原子批量操作batchGet、batchPut、batchDelete需要全有或全无的原子行为transactGet、transactWrite校验并限制每次请求的条目数大批次要分块LambdaEvent API JS 处理器的请求对象使用operation: Invoke 可选invocationTypeEvent API没有BatchInvoke操作伪批量模式向一次Invoke发送列表负载返回确定性的逐条目结果结构顺序保证要显式化若下游消费者依赖顺序保留并文档化排序键。安全与数据安全把ctx.identity、请求头与负载字段一律视为不可信输入每个数据源强制执行最小权限 IAM写操作前、转发转换后事件前都要加校验处理器代码中绝不硬编码密钥面向公共使用场景时默认值保持保守——无效状态一律拒绝/未授权deny/unauthorized。工具链TypeScript 与构建使用aws-appsync/eslint-plugin至少启用plugin:aws-appsync/base配置了 TypeScript 工具链时启用plugin:aws-appsync/recommendedTypeScript 不会被 AppSync 运行时直接执行部署前必须转译为受支持的 JavaScript打包时对外置externalizeaws-appsync/utils导入并附带 source map 便于调试。可观测性与运维为处理器与数据源集成启用 CloudWatch 日志使用结构化、低基数low-cardinality的日志字段频道命名空间/路径、操作、请求 ID建立可告警的信号处理器错误、数据源错误、延迟回退latency regression响应转换保持确定性并用多事件负载进行测试。最低质量检查清单文档以一份可执行清单收尾任何onPublish/onSubscribe实现都应以它为验收底线只使用APPSYNC_JS支持的运行时特性无throw、无 async/promise、无不受支持的循环/控制结构错误流使用运行时支持的工具返回非敏感消息onPublish与onSubscribe行为显式且经过测试数据源 request/response 映射确定且 schema 安全Lambda/DynamoDB 契约已文档化并验证已启用aws-appsync/eslint-plugin的 lint 检查小结这份指令文档的价值在于它把 AWS AppSync Event API 的隐藏约束显式化了APPSYNC_JS不是普通 Node.js处理器只有onPublish/onSubscribe两个钩子I/O 必须经由数据源错误必须用util而非throw。将它安装到工作区后Copilot 在编写graphql、gql、vtl、ts、js等 Event API 相关文件时会自动遵循以上规则。对于团队而言还可以参照 指令编写规范 在其基础上扩展出属于自己业务的数据源契约与命名空间策略形成一份可持续维护的 Event API 编码基线。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
