[toc]
GraphQL支持对其 `schema` introspect,使用GraphQL自身查询此 `schema`。
例如对一个普通的应用程序进行查询,这个例子中有一个拥有三个字段的`User Type`
```
type User {
id: String
name: String
birthday: Date
}
```
查询体
~~~
{
__type(name: "User") {
name
fields {
name
type {
name
}
}
}
}
~~~
结果
~~~
{
"__type": {
"name": "User",
"fields": [
{
"name": "id",
"type": { "name": "String" }
},
{
"name": "name",
"type": { "name": "String" }
},
{
"name": "birthday",
"type": { "name": "Date" }
},
]
}
}
~~~
#### 命名规则
在自定义 types 和 字段的相同上下文中使用 GraphQL 内省系统的 类型 和 字段时,需要加上前缀 "__"(两个下划级),这是为了避免和用户定义的 GraphQL types 命名冲突,相反的,GraphQL 类型系统中用户不能定义具有两个前导下划线的类型,字段,参数或其他系统组件。
#### 文档
内省系统的全部类型都提供了类型为 String 的 description 字段 以便 类型 设计者可以发布成文档,GraphQL 服务端使用 Markdown 语法返回 描述字段,因此建议使用 Markdown的 渲染工作显示 description 字段。
#### Deprecation
为了支持向后兼容,GraphQL field 和 enum values 能够指示是否弃用 (isDeprecated : Boolean,php中则是 DeprecationReason : String)
使用GraphQL 内省构建的工具应用通过隐藏信息或面向开发者人员的警告来遵守弃用。
#### Type Name Introspection
当查询针对任意 Object , Interface, or Union,GraphQL通过 meta field __typename : String! 支持 query 内的任意点对 类型名字的自省。它返回当前正在查询的 对象类型 的名字。
它通常用在当查询针对接口或联合类型时标识出可能类型中的真实类型。
这个字段是隐式的并且不会出现在所有定义类型的字段列表中。
#### Schema introspection
可以从 query 操作的 root-level type 访问 meta-fields __schema 和 __type 进而访问Schema 内省系统
__schema : __Schema!
__type(name : String!) : __Type
这些字段是隐式的并且不会出现在查询操作的root-level type 字段列表中。
~~~
type __Schema {
types : [__Type!]!
queryType : __Type!
mutationType : __Type
directives : [__Directive!]!
}
type __Type {
kind : __TypeKind!
name : String
description : String
# OBJECT and INTERFACE only
fields (includeDeprecated : Boolean = false) : [__Field!]
# OBJECT only
interfaces : [__Type!]
#INTERFACE and UNION only
possibleTypes : [__Type!]
ENUM only
enumValues (includeDeprecated : Boolean = false) : [__EnumValue!]
#INPUT_OBJECT only
inputFields : [__InputValue!]
#NON_NULL and LIST only
ofType : __Type
}
type __Field {
name : String!
description : String
args : [__InputValue!]!
type : __Type!
isDeprecated : Boolean!
deprecationReason : String
}
type __InputValue {
name : String!
description : String
type : __Type!
defaultValue : String
}
type __EnumValue {
name : String!
description : String
isDeprecated : Boolean!
deprecationReason : String
}
enum __TypeKind {
SCALAR
OBJECT
INTERFACE
UNION
ENUM
INPUT_OBJECT
LIST
NON_NULL
}
type __Directive {
name : String!
description : String
locations : [__DirectiveLocation!]!
args : [__InputValue!]!
}
enum __DirectiveLocation {
QUERY
MUTATION
FIELD
FRAGMENT_DEFINITION
FRAGMENT_SPREAD
INLINE_FRAGMENT
}
~~~
#### The __Type Type
__Type是 introspection 系统的核心,它表示系统中的 scalars , interfaces , object types , unions , enums 。
__Type 也表示 类型修饰符,用于修饰它引用的类型(ofType:__Type)。这是我们如何表示 list ,non -nullable 类型,以及它们的组合。
#### Type Kinds
这里有几种不同的类型。这些类型在 __TypeKind 枚举列表中。
注 内省机制针对 schema 的定义,所以在 schema 定义中没有验证过的类型不能使用 __type 查看类型信息。例如 实现 interface的类型,如果没有直接在 schema 中引用,这个时候 schema 是不能验证这个类型的,且 client 也不能使用 __type 查看该类型,所以应该将该类型放在 schema 的 types 数组中。