apollo-connectors

Apollo Connectors Schema Assistant

已弃用。 此技能已由 graphos-factory 技能取代，该技能 可基于 REST API（无论是否有 OpenAPI 规范）构建和维护 Apollo Connectors 子图，并使用 rover、router 和录制的测试样例对其进行验证。如果用户正在构建或扩展连接器子图，建议安装此技能： npx skills add apollographql/skills@graphos-factory（适用于任何 Agent）；在 Claude Code 中，apollo-skills 插件已包含此技能，可通过 /apollo-skills:graphos-factory 使用。此技能仍适用于对现有 Connectors schema 进行快速、一次性的编辑，并将在未来版本中移除。

MCP 工具

如果有 GraphOS MCP Tools，请使用：

• connectors-spec：在开始任何连接器工作之前，获取完整的 Connectors 规范
• apollo_docs_search：搜索相关文档
• apollo_docs_read：按 slug 读取特定文档页面

按主题划分的文档路径：

• 请求：/graphos/connectors/requests/url、/headers、/body、/batching
• 响应：/graphos/connectors/responses/fields、/error-handling
• 映射：/graphos/connectors/mapping、/arrays、/enums、/literals
• 实体：/graphos/connectors/entities、/patterns

流程

请遵循这 5 个步骤。不得跳过任何步骤。

步骤 1：调研

• 了解所调用的 API 及其响应结构
• 如果用户未提供 API 响应示例，请向用户索取
• 从 MCP 工具或参考文件中获取相关文档
• 调研完成前不得编写任何代码

步骤 2：实现

• 使用下方模板创建 schema
• 遵循参考文件中的语法、方法和变量
• 如果不确定需求，请提出澄清问题

步骤 3：验证（Compose）

• 运行 rover supergraph compose --config ./supergraph.yaml
• 继续之前修复所有组合错误

步骤 4：执行

• 运行 rover connector run --schema <file> -c "<Type.field>" -v "{}"
• 验证连接器是否正确执行

步骤 5：测试

• 在 /tests/ 下创建或更新测试文件
• 运行 rover connector test
• 确保每个连接器都达到完整的测试覆盖率

Schema 模板

# Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.15")
  @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])

@source(name: "api_name", http: { baseURL: "https://api.example.com" })

type Query {
  example(id: ID!): Example
    @connect(
      source: "api_name"
      http: { GET: "/example/{$args.id}" }
      selection: """
      id
      name
      """
    )
}

type Example {
  id: ID!
  name: String
}

版本要求

使用 Apollo Federation 和 Apollo Connectors 的最新长期支持（LTS）版本。只有在用户明确提出要求时，才使用预览版或实验性规范。

在编写 @link URL 或 federation_version 之前，确认当前的 LTS 版本。如果有 GraphOS 文档工具，请优先使用：

• **Federation：**读取 /graphos/schema-design/federated-schemas/reference/versions，并使用标记为 LTS 的最高版本。该版本就是 schema 的 @link（https://specs.apollo.dev/federation/vX.Y）。将 supergraph.yaml 中的 federation_version 设为同一 LTS 系列的最新补丁版本。
• **Connectors：**读取 /graphos/connectors/getting-started/version-requirements 和 /graphos/connectors/reference/changelog。使用最新的正式发布版 Connectors 规范（未标记为实验性），且该规范需与此 Federation LTS 版本兼容（https://specs.apollo.dev/connect/vX.Y）。

上方模板使用当前的 LTS：Federation v2.15 和 Connectors v0.3。如果文档列出了更新的 LTS 版本，请使用文档中的版本。

参考文件

实现连接器之前，请阅读相关参考文件：

• 语法 - Selection mapping 的 EBNF 语法
• 方法 - 可用的转换方法
• 变量 - 可用的映射变量
• 实体 - 实体模式和批处理
• 验证 - 用于验证的 Rover 命令
• 故障排除 - 常见错误及解决方案

关键规则

选择映射

• 优先使用子选择，而不是 ->map，以获得更清晰的映射
• 直接从根节点选择字段时，不要使用 $
• 字段别名：newName: originalField（仅在重命名时使用）
• 子选择：fieldName { ... }（用于映射嵌套内容）

# DO - Direct sub-selection for arrays
$.results {
  firstName: name.first
  lastName: name.last
}

# DO NOT - Unnecessary root $
$ {
  id
  name
}

# DO - Direct field selection
id
name

实体

• 在类型上添加 @connect，使其成为实体（无需 @key）
• 在父级选择中创建实体占位项：user: { id: userId }
• 遇到 ID 字段（例如 productId）时，创建实体关系
• 每个实体都应有一个且仅有一个权威子图带有 @connect

字面值

在映射中使用 $() 包装字面值：

$(1)              # number
$(true)           # boolean
$("hello")        # string
$({"a": "b"})     # object

# In body
body: "$({ a: $args.a })"  # CORRECT
body: "{ a: $args.a }"     # WRONG - will not compose

标头

http: {
  GET: "/api"
  headers: [
    { name: "Authorization", value: "Bearer {$env.API_KEY}" },
    { name: "X-Forwarded", from: "x-client" }
  ]
}

批处理

使用 $batch 转换 N+1 模式：

type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}

基本规则

• 绝不要编造本规范中未列出的语法或指令值
• 绝不要使用 --elv2-license accept（仅供人类使用）
• 编写代码前，务必索取 API 响应示例
• 修改后，务必使用 rover supergraph compose 进行验证
• 遇到 ID 字段时，务必创建实体关系
• 环境变量优先使用 $env，而不是 $config
• 使用 rover dev 在本地运行 Apollo Router