使用 AWS AppSync Merged API 整合微服务的 GraphQL - 团队分布式开发实践
详解将多个团队独立开发 / 部署的 GraphQL API 整合到单一端点的方法。同时介绍 Schema 冲突的规避方法和认证策略的设计。
Merged API 的必要性
在微服务架构中由多个团队开发 GraphQL API 时，前端需要向多个端点发送请求，客户端的复杂度会增加。Merged API 通过将多个源 API 整合到单一端点来应对这一问题。用户团队的 User API、订单团队的 Order API、商品团队的 Product API 可以各自独立开发 / 部署，而前端通过 1 个 GraphQL 端点即可访问。与 API Gateway 这类基于 REST 的 API 聚合不同，它在 GraphQL 的 Schema 层面进行整合，因此跨服务的查询也可以在单个请求中执行。
源 API 的设计与独立部署
各团队将独立的 AppSync API 作为源 API 进行开发。Schema、解析器、数据源按源 API 分别管理，团队可以独立部署 / 更新自己的 API。如果设置了自动合并，源 API 的更新会反映到 Merged API；如果是手动合并，则由源 API 的所有者执行合并。Schema 的冲突（同名的 Query 字段、同名的类型定义）会在合并时被检测出来，并作为错误报告。为了避免冲突，有一种设计是团队之间事先就 Schema 的命名规则达成一致，使用命名空间式的前缀（user_、order_），或将通用的类型定义作为共享 Schema 管理。
认证策略
在 Merged API 层面设置默认的认证方式（Cognito 用户池、IAM、API 密钥、Lambda 授权方）。可以为每个源 API 设置额外的认证方式，并对特定字段应用源 API 的认证。例如，可以采用这样的结构：将 Merged API 的默认认证设为 Cognito，同时在源 API 层面为面向管理员的 Mutation 添加 IAM 认证。通过 @aws_auth 指令控制字段级别的认证，可以只向特定的 Cognito 组公开特定字段。
Merged API 的定价与限制
Merged API 的费用与普通的 AppSync API 相同，查询 / 变更每 100 万次请求约 4.00 美元（截至 2026 年 8 月）。Merged API 本身不产生额外费用，但源 API 的数量有上限（默认 10 个），在大规模的微服务环境中需要申请放宽上限。源 API 的解析器调用 Lambda 时，Lambda 的费用计入源 API 所在的账户。启用 Merged API 的缓存后，跨源 API 的查询结果会被缓存，可以减少后端的调用次数。
实时更新与订阅
GraphQL 的功能之一是基于订阅的实时数据更新。在 Merged API 中，也会整合各源 API 定义的订阅，前端可以通过单一端点订阅多个服务的更新通知。由于变更通过 WebSocket 从服务器推送，可以用于聊天、通知、仪表板的实时更新等用途。各团队独立定义的实时功能，可以由客户端通过同一个端点处理。
监控与可观测性
在运维整合后的 API 时，要确认是哪个源 API 的哪个解析器较慢。用 CloudWatch 的日志记录请求和解析器的执行情况，并用 X-Ray 的分布式追踪可视化请求经过源 API 和后端的路径。这样就可以找出延迟的瓶颈和错误的发生位置。如果能够按字段追踪解析情况，就更容易排查特定查询较重的原因。由于涉及多个团队的代码，事先建立可以跨团队观测的机制。
CI/CD 与 Schema 管理
由于各团队独立部署，准备保持 Schema 一致性的机制。将源 API 的变更纳入 CI/CD 管道，在合并时自动检测 Schema 冲突，防止破坏性变更流入生产环境。团队之间就命名规则和前缀达成一致，共享的类型作为通用定义进行管理。为了不破坏客户端所依赖的字段，采用通过契约测试后再反映的运维方式，即使在分布式开发中也能维持稳定的端点。将 Schema 作为代码进行版本管理，支持变更的追踪和安全的演进。
缓存与性能优化
跨多个源 API 的查询容易增加对后端的调用。启用 Merged API 的缓存后，频繁返回相同结果的查询的响应会被保留一定时间，可以降低后端的负载和延迟。在解析器的设计中，要注意逐条获取相关数据导致调用激增的 N+1 问题，并通过批量获取的批处理提高效率。将各源 API 设计为在自己的职责范围内高效返回数据，避免在整合层发生过多的重复获取，就能保持整体的性能。
总结
AppSync Merged API 是一项将多个团队的 GraphQL API 整合到单一端点的服务。它在保持各团队独立部署的同时，为前端提供简洁的单一端点。它是在微服务架构中采用 GraphQL 时的模式之一。
参考资料（AWS 官方）
本页的第一手信息来源是 AWS 官方网站及官方文档。最新的规格与价格请以下列官方页面为准。
如本页内容与官方文档不一致，请以官方文档为准。