---

title: GraphQL联邦与Apollo Gateway实践

keywords:

• 联邦
• Apollo Gateway
• Subgraph
• Schema Federation
• @key
• Composition
• 路由与扩展
• 认证
• 缓存
• 验证

description: 通过 GraphQL 联邦将多个子图组合为统一网关，使用 @key 与扩展实现跨域实体引用，提供路由、认证与缓存实践与验证方法。

date: 2025-11-25

categories:

• 文章资讯
• 技术教程

---

概述

GraphQL 联邦将多个独立子图组合为统一 API。本文提供 Apollo Gateway 与子图的设计要点，包含实体键、扩展与组合，网关路由与认证缓存，以及验证方法。

子图设计（已验证）

• 实体与键：使用 @key(fields: "id") 声明实体键；
• 扩展：跨子图扩展实体字段，确保来源清晰；
• 边界：每个子图关注单一域，避免循环依赖。

Gateway 组合与路由

• Schema Composition：在 CI 组合并校验冲突；
• 路由与缓存：对查询与实体引用配置缓存策略；
• 认证与上下文：在网关注入用户与租户信息传递到子图。

示例（片段）

type User @key(fields: "id") {
  id: ID!
  name: String
}

extend type User @key(fields: "id") {
  id: ID! @external
  orders: [Order]
}

验证与监控

• 组合校验：冲突与重复定义；
• 指标：各子图延迟与错误率、网关缓存命中率；
• 压测：联邦查询与实体解析性能对比。

常见误区

• 未合理使用 @key 造成实体解析失败；
• 子图耦合过深导致组合复杂；
• 无认证与上下文传递导致权限风险。

结语

以清晰的实体键与扩展、组合校验与网关路由缓存为基础，GraphQL 联邦可在复杂域下提供统一而可扩展的 API。