Back to Details

apollo-connectors

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apollo Connectors Schema Assistant

Apollo Connectors 模式助手

MCP Tools

MCP 工具

If GraphOS MCP Tools are available, use them:
  • connectors-spec: Fetch the complete Connectors specification before starting any connector work
  • apollo_docs_search: Search for relevant documentation
  • apollo_docs_read: Read specific documentation pages by slug
Documentation paths by topic:
  • Requests: 
    /graphos/connectors/requests/url
    , 
    /headers
    , 
    /body
    , 
    /batching
  • Responses: 
    /graphos/connectors/responses/fields
    , 
    /error-handling
  • Mapping: 
    /graphos/connectors/mapping
    , 
    /arrays
    , 
    /enums
    , 
    /literals
  • Entities: 
    /graphos/connectors/entities
    , 
    /patterns
如果GraphOS MCP工具可用，请使用它们：
  • 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

Process

流程

Follow this 5-step process. DO NOT skip any steps.
请遵循以下5步流程，请勿跳过任何步骤。

Step 1: Research

步骤1：调研

  • Understand the API being called and the structure of responses
  • Ask the user for example API responses if not provided
  • Fetch relevant documentation from MCP tools or reference files
  • DO NOT write any code until research is complete
  • 了解要调用的API及响应结构
  • 如果未提供示例API响应，请向用户索要
  • 从MCP工具或参考文件中获取相关文档
  • 完成调研前请勿编写任何代码

Step 2: Implement

步骤2：实现

  • Create the schema using the template below
  • Follow the grammar, methods, and variables in the reference files
  • Ask clarifying questions if unsure about requirements
  • 使用下方的模板创建模式（schema）
  • 遵循参考文件中的语法、方法和变量规范
  • 若对需求有疑问，请提出澄清问题

Step 3: Validate (Compose)

步骤3：验证（组合）

  • Run 
    rover supergraph compose --config ./supergraph.yaml
  • Fix any composition errors before proceeding
  • 运行 
    rover supergraph compose --config ./supergraph.yaml
    命令
  • 在继续前修复所有组合错误

Step 4: Execute

步骤4：执行

  • Run 
    rover connector run --schema <file> -c "<Type.field>" -v "{}"
  • Verify the connector executes correctly
  • 运行 
    rover connector run --schema <file> -c "<Type.field>" -v "{}"
    命令
  • 验证连接器能否正确执行

Step 5: Test

步骤5：测试

  • Create or update test files under 
    /tests/
  • Run 
    rover connector test
  • Ensure full test coverage for each connector
  • 在
    /tests/
    目录下创建或更新测试文件
  • 运行 
    rover connector test
    命令
  • 确保每个连接器都有完整的测试覆盖率

Schema Template

模式模板

graphql
undefined
graphql
undefined

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.

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.12") @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 }

**Version Requirements:** Always use `federation/v2.12` and `connect/v0.3` unless specified otherwise.
extend schema @link(url: "https://specs.apollo.dev/federation/v2.12") @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 }

**版本要求：** 除非另有指定，请始终使用`federation/v2.12`和`connect/v0.3`。

Reference Files

参考文件

Before implementing connectors, read the relevant reference files:
  • Grammar - Selection mapping EBNF syntax
  • Methods - Available transformation methods
  • Variables - Available mapping variables
  • Entities - Entity patterns and batching
  • Validation - Rover commands for validation
  • Troubleshooting - Common errors and solutions
在实现连接器前，请阅读相关参考文件：
  • 语法 - 选择映射的EBNF语法
  • 方法 - 可用的转换方法
  • 变量 - 可用的映射变量
  • 实体 - 实体模式和批处理
  • 验证 - 用于验证的Rover命令
  • 故障排除 - 常见错误及解决方案

Key Rules

核心规则

Selection Mapping

选择映射

  • Prefer sub-selections over 
    ->map
    for cleaner mappings
  • Do NOT use 
    $
    when selecting fields directly from root
  • Field aliasing: 
    newName: originalField
    (only when renaming)
  • Sub-selection: 
    fieldName { ... }
    (to map nested content)
undefined
  • 优先使用子选择而非
    ->map
    以获得更简洁的映射
  • 直接从根节点选择字段时，请勿使用
    $
    符号
  • 字段别名：
    newName: originalField
    （仅在重命名时使用）
  • 子选择：
    fieldName { ... }
    （用于映射嵌套内容）
undefined

DO - Direct sub-selection for arrays

推荐 - 对数组使用直接子选择

$.results { firstName: name.first lastName: name.last }
$.results { firstName: name.first lastName: name.last }

DO NOT - Unnecessary root $

不推荐 - 不必要的根节点$

$ { id name }
$ { id name }

DO - Direct field selection

推荐 - 直接选择字段

id name
undefined
id name
undefined

Entities

实体

  • Add 
    @connect
    on a type to make it an entity (no 
    @key
    needed)
  • Create entity stubs in parent selections: 
    user: { id: userId }
  • When you see an ID field (e.g., 
    productId
    ), create an entity relationship
  • Each entity should have ONE authoritative subgraph with 
    @connect
  • 在类型上添加
    @connect
    使其成为实体（无需
    @key
    ）
  • 在父选择中创建实体存根：
    user: { id: userId }
  • 当看到ID字段（如
    productId
    ）时，创建实体关联
  • 每个实体应对应一个带有
    @connect
    的权威子图

Literal Values

字面量值

Use 
$()
wrapper for literal values in mappings:
$(1)              # number
$(true)           # boolean
$("hello")        # string
$({"a": "b"})     # object
在映射中使用
$()
包裹字面量值：
$(1)              # 数字
$(true)           # 布尔值
$("hello")        # 字符串
$({"a": "b"})     # 对象

In body

在请求体中

body: "$({ a: $args.a })" # CORRECT body: "{ a: $args.a }" # WRONG - will not compose
undefined
body: "$({ a: $args.a })" # 正确写法 body: "{ a: $args.a }" # 错误写法 - 无法完成组合
undefined

Headers

请求头

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

Batching

批处理

Convert N+1 patterns using 
$batch
:
graphql
type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}
使用
$batch
转换N+1查询模式：
graphql
type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}

Ground Rules

基本原则

  • NEVER make up syntax or directive values not in this specification
  • NEVER use 
    --elv2-license accept
    (for humans only)
  • ALWAYS ask for example API responses before writing code
  • ALWAYS validate with 
    rover supergraph compose
    after changes
  • ALWAYS create entity relationships when you see ID fields
  • Prefer 
    $env
    over 
    $config
    for environment variables
  • Use 
    rover dev
    for running Apollo Router locally
  • 切勿编造本规范中未提及的语法或指令值
  • 切勿使用
    --elv2-license accept
    （仅面向人类用户）
  • 在编写代码前，务必索要示例API响应
  • 修改后务必使用
    rover supergraph compose
    进行验证
  • 当看到ID字段时，务必创建实体关联
  • 优先使用
    $env
    而非
    $config
    来获取环境变量
  • 使用
    rover dev
    在本地运行Apollo Router