📣 GraphQL Conf 2023 • 9 月 19-21 日 • 舊金山 • 觀看影片！

graphql/type

graphql/type 模組負責定義 GraphQL 類型和架構。您可以從 graphql/type 模組或根 graphql 模組匯入。例如

import { GraphQLSchema } from "graphql" // ES6
var { GraphQLSchema } = require("graphql") // CommonJS

概觀#

架構

```
class GraphQLSchema
```
GraphQL 伺服器功能的表示。

定義

```
class GraphQLScalarType
```
GraphQL 中的純量類型。
```
class GraphQLObjectType
```
GraphQL 中包含欄位的物件類型。
```
class GraphQLInterfaceType
```
GraphQL 中的介面類型，定義實作將包含的欄位。
```
class GraphQLUnionType
```
GraphQL 中的聯合類型，定義實作清單。
```
class GraphQLEnumType
```
GraphQL 中的列舉類型，定義有效值清單。
```
class GraphQLInputObjectType
```
GraphQL 中的輸入物件類型，表示結構化輸入。
```
class GraphQLList
```
包覆其他類型的類型包裝器，表示這些類型的清單。
```
class GraphQLNonNull
```
包覆其他類型的類型包裝器，表示這些類型的非空版本。

謂詞

```
function isInputType
```
傳回類型是否可用於參數和指令的輸入類型。
```
function isOutputType
```
傳回類型是否可用於欄位的結果輸出類型。

```
函式 isLeafType
```
傳回類型是否可以在回應中成為葉值。
```
function isCompositeType
```
傳回類型是否可以成為選取集的父項脈絡。
```
function isAbstractType
```
傳回類型是否為物件類型的組合。

非修飾詞

```
function getNullableType
```
從類型中移除任何非 null 包裝器。
```
function getNamedType
```
從類型中移除任何非 null 或清單包裝器。

純量

```
var GraphQLInt
```
表示整數的純量類型。
```
var GraphQLFloat
```
表示浮點數的純量類型。
```
var GraphQLString
```
表示字串的純量類型。
```
var GraphQLBoolean
```
表示布林值的純量類型。
```
var GraphQLID
```
表示 ID 的純量類型。

Schema#

GraphQLSchema#

class GraphQLSchema {
  constructor(config: GraphQLSchemaConfig)
}

type GraphQLSchemaConfig = {
  query: GraphQLObjectType;
  mutation?: ?GraphQLObjectType;
}

Schema 是透過提供每種作業類型（查詢和突變（選用））的根類型來建立的。然後將 Schema 定義提供給驗證器和執行器。

範例#

var MyAppSchema = new GraphQLSchema({
  query: MyAppQueryRootType
  mutation: MyAppMutationRootType
});

定義#

GraphQLScalarType#

class GraphQLScalarType<InternalType> {
  constructor(config: GraphQLScalarTypeConfig<InternalType>)
}

type GraphQLScalarTypeConfig<InternalType> = {
  name: string;
  description?: ?string;
  serialize: (value: mixed) => ?InternalType;
  parseValue?: (value: mixed) => ?InternalType;
  parseLiteral?: (valueAST: Value) => ?InternalType;
}

任何要求和輸入值到引數的葉值都是純量（或列舉），並定義為名稱和一系列用於確保有效性的序列化函數。

範例#

var OddType = new GraphQLScalarType({
  name: "Odd",
  serialize: oddValue,
  parseValue: oddValue,
  parseLiteral(ast) {
    if (ast.kind === Kind.INT) {
      return oddValue(parseInt(ast.value, 10))
    }
    return null
  },
})

function oddValue(value) {
  return value % 2 === 1 ? value : null
}

GraphQLObjectType#

class GraphQLObjectType {
  constructor(config: GraphQLObjectTypeConfig)
}

type GraphQLObjectTypeConfig = {
  name: string;
  interfaces?: GraphQLInterfacesThunk | Array<GraphQLInterfaceType>;
  fields: GraphQLFieldConfigMapThunk | GraphQLFieldConfigMap;
  isTypeOf?: (value: any, info?: GraphQLResolveInfo) => boolean;
  description?: ?string
}

type GraphQLInterfacesThunk = () => Array<GraphQLInterfaceType>;

type GraphQLFieldConfigMapThunk = () => GraphQLFieldConfigMap;

// See below about resolver functions.
type GraphQLFieldResolveFn = (
  source?: any,
  args?: {[argName: string]: any},
  context?: any,
  info?: GraphQLResolveInfo
) => any

type GraphQLResolveInfo = {
  fieldName: string,
  fieldNodes: Array<Field>,
  returnType: GraphQLOutputType,
  parentType: GraphQLCompositeType,
  schema: GraphQLSchema,
  fragments: { [fragmentName: string]: FragmentDefinition },
  rootValue: any,
  operation: OperationDefinition,
  variableValues: { [variableName: string]: any },
}

type GraphQLFieldConfig = {
  type: GraphQLOutputType;
  args?: GraphQLFieldConfigArgumentMap;
  resolve?: GraphQLFieldResolveFn;
  deprecationReason?: string;
  description?: ?string;
}

type GraphQLFieldConfigArgumentMap = {
  [argName: string]: GraphQLArgumentConfig;
};

type GraphQLArgumentConfig = {
  type: GraphQLInputType;
  defaultValue?: any;
  description?: ?string;
}

type GraphQLFieldConfigMap = {
  [fieldName: string]: GraphQLFieldConfig;
};

您定義的大部分 GraphQL 類型都是物件類型。物件類型有名稱，但最重要的是描述其欄位。

當兩個類型需要互相參照，或類型需要在欄位中參照自身時，您可以使用函數表達式（又稱為閉包或 thunk）來提供欄位（延遲）。

請注意，解析器函式會將 source 物件作為第一個參數提供。不過，如果未提供解析器函式，則會使用預設解析器，它會在 source 上尋找與欄位同名的函式。如果找到，則會以 (args, context, info) 呼叫函式。由於它是 source 上的函式，因此該值始終可以使用 this 參照。

範例#

var AddressType = new GraphQLObjectType({
  name: "Address",
  fields: {
    street: { type: GraphQLString },
    number: { type: GraphQLInt },
    formatted: {
      type: GraphQLString,
      resolve(obj) {
        return obj.number + " " + obj.street
      },
    },
  },
})

var PersonType = new GraphQLObjectType({
  name: "Person",
  fields: () => ({
    name: { type: GraphQLString },
    bestFriend: { type: PersonType },
  }),
})

GraphQLInterfaceType#

class GraphQLInterfaceType {
  constructor(config: GraphQLInterfaceTypeConfig)
}

type GraphQLInterfaceTypeConfig = {
  name: string,
  fields: GraphQLFieldConfigMapThunk | GraphQLFieldConfigMap,
  resolveType?: (value: any, info?: GraphQLResolveInfo) => ?GraphQLObjectType,
  description?: ?string
};

當一個欄位可以傳回一組異質類型的其中一個時，會使用 Interface 類型來描述哪些類型是可能的，所有類型中有哪些欄位是共用的，以及一個函式來判斷在解析欄位時實際使用哪個類型。

範例#

var EntityType = new GraphQLInterfaceType({
  name: "Entity",
  fields: {
    name: { type: GraphQLString },
  },
})

GraphQLUnionType#

class GraphQLUnionType {
  constructor(config: GraphQLUnionTypeConfig)
}

type GraphQLUnionTypeConfig = {
  name: string,
  types: GraphQLObjectsThunk | Array<GraphQLObjectType>,
  resolveType?: (value: any, info?: GraphQLResolveInfo) => ?GraphQLObjectType;
  description?: ?string;
};

type GraphQLObjectsThunk = () => Array<GraphQLObjectType>;

當一個欄位可以傳回一組異質類型的其中一個時，會使用 Union 類型來描述哪些類型是可能的，以及提供一個函式來判斷在解析欄位時實際使用哪個類型。

範例#

var PetType = new GraphQLUnionType({
  name: "Pet",
  types: [DogType, CatType],
  resolveType(value) {
    if (value instanceof Dog) {
      return DogType
    }
    if (value instanceof Cat) {
      return CatType
    }
  },
})

GraphQLEnumType#

class GraphQLEnumType {
  constructor(config: GraphQLEnumTypeConfig)
}

type GraphQLEnumTypeConfig = {
  name: string;
  values: GraphQLEnumValueConfigMap;
  description?: ?string;
}

type GraphQLEnumValueConfigMap = {
  [valueName: string]: GraphQLEnumValueConfig;
};

type GraphQLEnumValueConfig = {
  value?: any;
  deprecationReason?: string;
  description?: ?string;
}

type GraphQLEnumValueDefinition = {
  name: string;
  value?: any;
  deprecationReason?: string;
  description?: ?string;
}

請求和輸入值的某些葉值是列舉。GraphQL 會將列舉值序列化為字串，不過在內部，列舉可以用任何類型的類型表示，通常是整數。

注意：如果在定義中未提供值，則會將列舉值的「名稱」用作其內部值。

範例#

var RGBType = new GraphQLEnumType({
  name: "RGB",
  values: {
    RED: { value: 0 },
    GREEN: { value: 1 },
    BLUE: { value: 2 },
  },
})

GraphQLInputObjectType#

class GraphQLInputObjectType {
  constructor(config: GraphQLInputObjectConfig)
}

type GraphQLInputObjectConfig = {
  name: string;
  fields: GraphQLInputObjectConfigFieldMapThunk | GraphQLInputObjectConfigFieldMap;
  description?: ?string;
}

type GraphQLInputObjectConfigFieldMapThunk = () => GraphQLInputObjectConfigFieldMap;

type GraphQLInputObjectFieldConfig = {
  type: GraphQLInputType;
  defaultValue?: any;
  description?: ?string;
}

type GraphQLInputObjectConfigFieldMap = {
  [fieldName: string]: GraphQLInputObjectFieldConfig;
};

type GraphQLInputObjectField = {
  name: string;
  type: GraphQLInputType;
  defaultValue?: any;
  description?: ?string;
}

type GraphQLInputObjectFieldMap = {
  [fieldName: string]: GraphQLInputObjectField;
};

輸入物件定義一個結構化的欄位集合，可以提供給欄位參數。

使用 NonNull 會確保查詢必須提供一個值

範例#

var GeoPoint = new GraphQLInputObjectType({
  name: "GeoPoint",
  fields: {
    lat: { type: new GraphQLNonNull(GraphQLFloat) },
    lon: { type: new GraphQLNonNull(GraphQLFloat) },
    alt: { type: GraphQLFloat, defaultValue: 0 },
  },
})

GraphQLList#

class GraphQLList {
  constructor(type: GraphQLType)
}

清單是一種類型標記，一個指向另一種類型的包裝類型。清單通常在定義物件類型欄位時建立。

範例#

var PersonType = new GraphQLObjectType({
  name: "Person",
  fields: () => ({
    parents: { type: new GraphQLList(PersonType) },
    children: { type: new GraphQLList(PersonType) },
  }),
})

GraphQLNonNull#

class GraphQLNonNull {
  constructor(type: GraphQLType)
}

非空值是一種類型標記，一個指向另一種類型的包裝類型。非空值類型強制其值永遠不會為空，並確保如果在請求期間發生這種情況，就會引發錯誤。它對於你可以對非空性做出有力保證的欄位很有用，例如資料庫列的 id 欄位通常永遠不會為空。

範例#

var RowType = new GraphQLObjectType({
  name: "Row",
  fields: () => ({
    id: { type: new GraphQLNonNull(String) },
  }),
})

謂詞#

isInputType#

function isInputType(type: ?GraphQLType): boolean

這些類型可以用作參數和指令的輸入類型。

isOutputType#

function isOutputType(type: ?GraphQLType): boolean

這些類型可以用作欄位的結果輸出類型

isLeafType#

function isLeafType(type: ?GraphQLType): boolean

這些類型可以描述可以是葉值值的類型

isCompositeType#

function isCompositeType(type: ?GraphQLType): boolean

這些類型可能會描述選取集的父項脈絡

isAbstractType#

function isAbstractType(type: ?GraphQLType): boolean

這些類型可能會描述物件類型的組合

Un-modifiers#

getNullableType#

function getNullableType(type: ?GraphQLType): ?GraphQLNullableType

如果給定的類型是非可為空類型，這會移除非可為空類型並傳回基礎類型。

getNamedType#

function getNamedType(type: ?GraphQLType): ?GraphQLNamedType

如果給定的類型是非可為空類型或清單，這會重複移除非可為空類型和清單包裝器，並傳回基礎類型。

Scalars#

GraphQLInt#

var GraphQLInt: GraphQLScalarType

表示整數的 GraphQLScalarType。

GraphQLFloat#

var GraphQLFloat: GraphQLScalarType

表示浮點數的 GraphQLScalarType。

GraphQLString#

var GraphQLString: GraphQLScalarType

表示字串的 GraphQLScalarType。

GraphQLBoolean#

var GraphQLBoolean: GraphQLScalarType

表示布林值的 GraphQLScalarType。

GraphQLID#

var GraphQLID: GraphQLScalarType

表示 ID 的 GraphQLScalarType。

繼續閱讀 →graphql/utilities

GraphQL.js 教學

進階指南

建構類型