內省檢測 · graphql-php

[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 數組中。