apollo-federation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apollo Federation Schema Authoring

Apollo Federation Schema编写指南

Apollo Federation enables composing multiple GraphQL APIs (subgraphs) into a unified supergraph.

Apollo Federation支持将多个GraphQL API（子图）组合成一个统一的超图。

Federation 2 Schema Setup

Federation 2 Schema设置

Every Federation 2 subgraph must opt-in via

@link

graphql

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.12",
        import: ["@key", "@shareable", "@external", "@requires", "@provides"])

Import only the directives your subgraph uses.

每个Federation 2子图必须通过

@link

声明启用：

graphql

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.12",
        import: ["@key", "@shareable", "@external", "@requires", "@provides"])

仅导入你的子图需要使用的指令。

Core Directives Quick Reference

核心指令速查

Directive	Purpose	Example
`@key`	Define entity with unique key	`type Product @key(fields: "id")`
`@shareable`	Allow multiple subgraphs to resolve field	`type Position @shareable { x: Int! }`
`@external`	Reference field from another subgraph	`weight: Int @external`
`@requires`	Computed field depending on external fields	`shippingCost: Int @requires(fields: "weight")`
`@provides`	Conditionally resolve external field	`@provides(fields: "name")`
`@override`	Migrate field to this subgraph	`@override(from: "Products")`
`@inaccessible`	Hide from API schema	`internalId: ID! @inaccessible`
`@interfaceObject`	Add fields to entity interface	`type Media @interfaceObject`

指令	用途	示例
`@key`	定义带有唯一键的实体	`type Product @key(fields: "id")`
`@shareable`	允许多个子图解析该字段	`type Position @shareable { x: Int! }`
`@external`	引用来自另一个子图的字段	`weight: Int @external`
`@requires`	依赖外部字段的计算字段	`shippingCost: Int @requires(fields: "weight")`
`@provides`	有条件地解析外部字段	`@provides(fields: "name")`
`@override`	将字段迁移至本子图	`@override(from: "Products")`
`@inaccessible`	在API Schema中隐藏该字段	`internalId: ID! @inaccessible`
`@interfaceObject`	为实体接口添加字段	`type Media @interfaceObject`

Reference Files

参考文档

Detailed documentation for specific topics:

Directives - All federation directives with syntax, examples, and rules
Schema Patterns - Multi-subgraph patterns and recipes
Composition - Composition rules, error codes, and debugging

特定主题的详细文档：

指令 - 所有联邦指令的语法、示例和规则
Schema模式 - 多子图模式和实践方案
组合 - 组合规则、错误代码和调试方法

Key Patterns

核心模式

Entity Definition

实体定义

graphql

type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Int
}

graphql

type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Int
}

Entity Contributions Across Subgraphs

跨子图的实体贡献

graphql

undefined

graphql

undefined

Products subgraph

type Product @key(fields: "id") { id: ID! name: String! price: Int }

Reviews subgraph

type Product @key(fields: "id") { id: ID! reviews: [Review!]! averageRating: Float }

undefined

type Product @key(fields: "id") { id: ID! reviews: [Review!]! averageRating: Float }

undefined

Computed Fields with @requires

使用@requires的计算字段

graphql

type Product @key(fields: "id") {
  id: ID!
  size: Int @external
  weight: Int @external
  shippingEstimate: String @requires(fields: "size weight")
}

graphql

type Product @key(fields: "id") {
  id: ID!
  size: Int @external
  weight: Int @external
  shippingEstimate: String @requires(fields: "size weight")
}

Value Types with @shareable

使用@shareable的值类型

graphql

type Money @shareable {
  amount: Int!
  currency: String!
}

graphql

type Money @shareable {
  amount: Int!
  currency: String!
}

Entity Stub (Reference Without Contributing)

实体存根（仅引用不贡献字段）

graphql

type Product @key(fields: "id", resolvable: false) {
  id: ID!
}

graphql

type Product @key(fields: "id", resolvable: false) {
  id: ID!
}

Ground Rules

基本原则

ALWAYS use Federation 2.x syntax with
```
@link
```
directive
ALWAYS import only the directives your subgraph uses
NEVER use
```
@shareable
```
without ensuring all subgraphs return identical values for that field
PREFER
```
@key
```
with single ID field for simple entity identification
USE
```
rover supergraph compose
```
to validate composition locally
USE
```
rover subgraph check
```
to validate against production supergraph

始终使用带有
```
@link
```
指令的Federation 2.x语法
始终仅导入你的子图需要使用的指令
切勿在未确保所有子图对该字段返回相同值的情况下使用
```
@shareable
```
优先使用单个ID字段的
```
@key
```
进行简单实体标识
使用
```
rover supergraph compose
```
在本地验证组合结果
使用
```
rover subgraph check
```
针对生产环境超图进行验证