Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Learn-Introspection #54

Merged
merged 2 commits into from
Aug 4, 2017
Merged

Learn-Introspection #54

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a842fa
翻译自省部分
linonetwo Jul 31, 2017
e7e0d52
修改“我们也可以问 GraphQL” 这句，以及自省改成内省
linonetwo Aug 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 24 additions & 55 deletions site/learn/Learn-Introspection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,19 @@
---
title: Introspection
title: 内省
layout: ../_core/DocsLayout
category: Learn
category: 学习
permalink: /learn/introspection/
next: /learn/best-practices/
---

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!
我们有时候会需要去问 GraphQL Schema 它支持哪些查询。GraphQL 通过内省系统让我们可以做到这点！

For our Star Wars example, the file
在我们的星战例子里，文件
[starWarsIntrospection-test.js](https://github.com/graphql/graphql-js/blob/master/src/__tests__/starWarsIntrospection-test.js)
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 询问哪些类型是可用的。一个查询的根类型总是有 `__schema` 这个字段。现在来试试，查询一下有哪些可用的类型。

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.

```graphql
# { "graphiql": true }
Expand All @@ -39,19 +33,14 @@ are available.

```

Wow, that's a lot of types! What are they? Let's group them:
哇，有好多类型！它们都是什么？我们来总结一下：

- **Query, Character, Human, Episode, Droid** - These are the ones that we
defined in our type system.
- **String, Boolean** - These are built-in scalars that the type system
provided.
- **Query, Character, Human, Episode, Droid** - 这些是我们在类型系统中定义的类型。
- **String, Boolean** - 这些是内建的标量，由类型系统提供。
- **\_\_Schema, \_\_Type, \_\_TypeKind, \_\_Field, \_\_InputValue,
\_\_EnumValue, \_\_Directive** - These all are preceded with a double
underscore, indicating that they are part of the introspection system.
\_\_EnumValue, \_\_Directive** - 这些有着两个下划线的类型是内省系统的一部分。

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!
现在，来试试找到一个可以探索出有哪些可用查询的地方。当我们设计类型系统的时候，我们确定了一个所有查询开始的地方，来问问内省系统它是什么！

```graphql
# { "graphiql": true }
Expand All @@ -64,15 +53,9 @@ would start at; let's ask the introspection system about that!
}
```

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.
这和我们在类型系统那章里说的一样，`Query` 类型是我们开始的地方！注意这里的命名只是一个惯例，我们也可以把 `Query` 取成别的名字，只要我们把它定义为所有查询出发的地方，它也依然会在这里被返回。尽管如此，还是把它命名为 `Query` 吧，这是一个有用的惯例。

It is often useful to examine one specific type. Let's take a look at
the `Droid` type:
有时候也需要检验一个特定的类型。来看看 `Droid` 类型：

```graphql
# { "graphiql": true }
Expand All @@ -83,8 +66,7 @@ the `Droid` type:
}
```

What if we want to know more about Droid, though? For example, is it
an interface or an object?
如果我们想要更了解 `Droid` 呢？例如，它是一个接口还是一个对象？

```graphql
# { "graphiql": true }
Expand All @@ -96,8 +78,7 @@ an interface or an object?
}
```

`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:
`kind` 返回一个枚举类型 `__TypeKind`，其中一个值是 `OBJECT`。如果我们改问 `Character`，我们会发现它是一个接口：

```graphql
# { "graphiql": true }
Expand All @@ -109,8 +90,7 @@ we asked about `Character` instead we'd find that it is an interface:
}
```

It's useful for an object to know what fields are available, so let's
ask the introspection system about `Droid`:
对于一个对象来说，知道它有哪些字段是很有用的，所以来问问内省系统 `Droid` 有哪些字段：

```graphql
# { "graphiql": true }
Expand All @@ -132,16 +112,12 @@ ask the introspection system about `Droid`:

```

Those are our fields that we defined on `Droid`!
这些正是我们为 `Droid` 定义的字段！

`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.
`id` 看起来有点儿奇怪，这个类型没有名字。这是因为它是一个 `NON_NULL` 类型的“包装” 。如果我们请求它的
`ofType` 字段，我们会发现它是 `ID` ，告诉我们这是一个非空的 ID。

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.
相似地，`friends` 和 `appearsIn` 都没有名字，因为它们都是 `LIST` 包装类型。我们可以看看它们的 `ofType`，就能知道它们是装什么东西的列表。

```graphql
# { "graphiql": true }
Expand All @@ -168,8 +144,7 @@ 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!
最后我们来看看内省系统特别适合用来开发工具的特性，我们来向内省系统请求文档！

```graphql
# { "graphiql": true }
Expand All @@ -181,12 +156,6 @@ for tooling; let's ask the system for documentation!
}
```

So we can access the documentation about the type system using introspection,
and create documentation browsers, or rich IDE experiences.
因此我们可以通过内省系统接触到类型系统的文档，并做出文档浏览器，或是提供丰富的 IDE 体验。

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](https://github.com/graphql/graphql-js/blob/master/src/type/introspection.js)
file in GraphQL.js contains code implementing a specification-compliant GraphQL
query introspection system.
这些只是内省系统的浅浅一层。我们还可以查询枚举值、某个类型实现了什么接口等等，我们甚至可以对内省系统内省。关于这个主题的详细说明可以看规范的“Introspection”部分，以及 GraphQL.js 中的 [introspection](https://github.com/graphql/graphql-js/blob/master/src/type/introspection.js) 文件，它包含了符合规范的一个内省系统的实现。