学习教程
内省

内省

¥Introspection

向 GraphQL 结构询问有关其支持哪些查询的信息通常很有用。GraphQL 允许我们使用内省系统来做到这一点！

¥It’s often useful to ask a GraphQL schema for information about what queries it supports. GraphQL allows us to do so using the introspection system!

对于我们的星球大战示例，文件 starWarsIntrospection-test.ts 包含许多演示自省系统的查询，并且是一个测试文件，可以运行该文件来练习参考实现的自省系统。

¥For our Star Wars example, the file starWarsIntrospection-test.ts contains a number of queries demonstrating the introspection system, and is a test file that can be run to exercise the reference implementation’s introspection system.

我们设计了类型系统，因此我们知道哪些类型可用，但如果我们不知道，我们可以通过查询 __schema 字段来询问 GraphQL，该字段始终在查询的根类型上可用。我们现在就这样做，并询问有哪些类型可用。

¥We designed the type system, so we know what types are available, but if we didn’t, we can ask GraphQL, by querying the __schema field, always available on the root type of a Query. Let’s do so now, and ask what types are available.

哇，种类真多啊！这些是什么？让我们将它们分组：

¥Wow, that’s a lot of types! What are they? Let’s group them:

  • Query, Character, Human, Episode, Droid - 这些是我们在类型系统中定义的。

    ¥Query, Character, Human, Episode, Droid - These are the ones that we defined in our type system.

  • String, Boolean - 这些是类型系统提供的内置标量。

    ¥String, Boolean - These are built-in scalars that the type system provided.

  • __Schema, __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive - 这些都前面有一个双下划线，表明它们是内省系统的一部分。

    ¥__Schema, __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive - These all are preceded with a double underscore, indicating that they are part of the introspection system.

现在，让我们尝试找出一个开始探索可用查询的好地方。当我们设计类型系统时，我们指定了所有查询将从什么类型开始；咱们去问问内省系统吧！

¥Now, let’s try and figure out a good place to start exploring what queries are available. When we designed our type system, we specified what type all queries would start at; let’s ask the introspection system about that!

这与我们在类型系统部分中所说的相符，即我们将从 Query 类型开始！请注意，这里的命名只是按照惯例；我们可以将 Query 类型命名为其他任何名称，如果我们指定它是查询的起始类型，它仍然会在这里返回。不过，将其命名为 Query 是一个有用的约定。

¥And that matches what we said in the type system section, that the Query type is where we will start! Note that the naming here was just by convention; we could have named our Query type anything else, and it still would have been returned here had we specified it was the starting type for queries. Naming it Query, though, is a useful convention.

检查一种特定类型通常很有用。我们先来看看 Droid 型：

¥It is often useful to examine one specific type. Let’s take a look at the Droid type:

如果我们想更多地了解 Droid 怎么办？例如，它是一个接口还是一个对象？

¥What if we want to know more about Droid, though? For example, is it an interface or an object?

kind 返回一个 __TypeKind 枚举，其中一个值为 OBJECT。如果我们询问 Character，我们会发现它是一个接口：

¥kind returns a __TypeKind enum, one of whose values is OBJECT. If we asked about Character instead we’d find that it is an interface:

对于一个对象来说，知道哪些字段可用是很有用的，所以让我们向内省系统询问 Droid：

¥It’s useful for an object to know what fields are available, so let’s ask the introspection system about Droid:

这些是我们在 Droid 上定义的字段！

¥Those are our fields that we defined on Droid!

id 看起来有点奇怪，它没有该类型的名称。那是因为它是 “wrapper” 类型的 NON_NULL 类型。如果我们在该字段的类型上查询 ofType，我们会在那里找到 ID 类型，告诉我们这是一个非空 ID。

¥id looks a bit weird there, it has no name for the type. That’s because it’s a “wrapper” type of kind NON_NULL. If we queried for ofType on that field’s type, we would find the ID type there, telling us that this is a non-null ID.

同样，friends 和 appearsIn 都没有名称，因为它们是 LIST 封装类型。我们可以在这些类型上查询 ofType，这将告诉我们这些列表是什么。

¥Similarly, both friends and appearsIn have no name, since they are the LIST wrapper type. We can query for ofType on those types, which will tell us what these are lists of.

让我们以内省系统的一个功能作为结束，该功能对于工具特别有用；让我们向系统索取文档吧！

¥Let’s end with a feature of the introspection system particularly useful for tooling; let’s ask the system for documentation!

因此，我们可以使用内省访问有关类型系统的文档，并创建文档浏览器或丰富的 IDE 体验。

¥So we can access the documentation about the type system using introspection, and create documentation browsers, or rich IDE experiences.

这仅仅触及了内省系统的表面；我们可以查询枚举值、类型实现的接口等等。我们甚至可以对内省系统本身进行内省。该规范在 “内省” 部分详细介绍了该主题，GraphQL.js 中的 introspection 文件包含实现符合规范的 GraphQL 查询自省系统的代码。

¥This has just scratched the surface of the introspection system; we can query for enum values, what interfaces a type implements, and more. We can even introspect on the introspection system itself. The specification goes into more detail about this topic in the “Introspection” section, and the introspection file in GraphQL.js contains code implementing a specification-compliant GraphQL query introspection system.

执行最佳实践