GraphQL接口推荐的用法

探索示例，避免常见陷阱

💡 技巧

如果您是企业客户，想了解更多关于这个主题的内容，尝试企业最佳实践：模式设计的课程Odyssey.

GraphQL接口允许模式字段返回多个对象类型之一，所有这些类型都必须实现该接口。为了实现接口，对象类型必须定义接口中包含的所有字段（否则，模式无效）：

1
interface Media {
2
  title: String!
3
}
4

5
type Book implements Media {
6
  title: String!
7
  author: String!
8
}

因为接口可以在实现对象类型上强制执行此要求，所以纯粹为了强制字段定义来创建接口是很有诱惑力的。下面的方案要求所有的对象类型都通过声明这些类型实现 Nameable 接口来声明 name 字段：name 字段在其所有对象类型中通过声明这些类型实现 Nameable 接口来声明：

❌

1
interface Nameable {
2
  name: String
3
}
4

5
type Cat implements Nameable {
6
  name: String
7
  meowVolume: Int
8
}
9

10
type Dog implements Nameable {
11
  name: String
12
  barkVolume: Int
13
}
14

15
type Owner implements Nameable {
16
  name: String
17
  cats: [Cat]
18
  dogs: [Dog]
19
}
20

21
type Query {
22
  owners: [Owner]
23
}

⚠️ 注意

这不是接口推荐的使用方式！注意，在这个方案中，Nameable 永远没有被用作字段的返回类型。这意味着客户端没有方法利用这种多态关系执行操作。

有效客户端用例的缺乏暗示了一种代码问题。Nameable 接口是不必要的，而且它可能会在你的方案在未来更改时引起问题。子图分配它自己的挑战，所以去除不必要的接口通常会使流程变得更简单。

在下一个示例中，我们指定Cat 和 Dog 类型实现 Pet 接口，以便我们可以在 Owner.pets 字段中返回两种类型的 Fat 和 Dog 的聚合列表。现在存在一个有效的客户端用例进行多态，使用接口是合理的。

✅

1
interface Pet {
2
  name: String
3
}
4

5
type Cat implements Pet {
6
  name: String
7
  meowVolume: Int
8
}
9

10
type Dog implements Pet {
11
  name: String
12
  barkVolume: Int
13
}
14

15
type Owner {
16
  name: String
17
  pets: [Pet]
18
}
19

20
type Query {
21
  owners: [Owner]
22
}

添加新实现类型的影响

当客户端在操作中包含返回抽象类型的字段时，他们通常会使用 "条件片段," 列举他们感兴趣的来自具体类型的字段，如下所示：

1
query OwnersAndPets {
2
  owners {
3
    name
4
    pets {
5
      name
6
      ... on Cat {
7
        meowVolume
8
      }
9
      ... on Dog {
10
        barkVolume
11
      }
12
    }
13
  }
14
}

ⓘ 注意

如果Pet是一个联合体而不是接口（union Pet = Cat | Dog），则所有请求的字段都需要包含在条件片段中。即使在两种类型都定义了该字段的情况下，也无法在name字段外包含它。

如果您的API为抽象类型添加了额外的可能类型，则客户端必须更改其操作以从这些新类型中选择数据。虽然这不是一个破坏性的更改，但这种情况下需要一些防御性编程。

1
// Trigger a TypeScript error if a new type is introduced but
2
// we haven't added a switch case for it.
3
const assertUnknown = (x: never) =>
4
  console.log(`Unknown Pet type: ${(x as any).__typename}`);
5

6
switch (pet.__typename) {
7
  case 'Cat':
8
    console.log(`Cat meows ${pet.meowVolume}`);
9
    break;
10
  case 'Dog':
11
    console.log(`Dog barks ${pet.barkVolume}`);
12
    break;
13
  default:
14
    assertUnknown(pet);
15
    console.log('Fallback behavior');
16
}

ⓘ 注意

当使用 graphql-code-generator时，访问已知的接口字段，如Pet.name将触发TypeScript错误。请参阅问题8538以获取更多信息。

1
// `when` must be used as an expression to require exhaustivity
2
val result = when (pet.__typename) {
3
  "Cat" -> println("Cat meows ${pet.onCat?.meowVolume}")
4
  "Dog" -> println("Dog barks ${pet.onDog?.barkVolume}")
5
  else -> println("Unknown animal ${pet.__typename}")
6
}

1
switch pet.__typename {
2
case "Cat":
3
    print("Cat meows \(pet.asCat?.meowVolume ?? 0)")
4
case "Dog":
5
    print("Dog barks \(pet.asDog?.barkVolume ?? 0)")
6
default:
7
    print("Unknown animal \(pet.__typename)")
8
}

下一步

首页