Java bytea schema对应_graphql-java使用手册: part2 创建Schema
创建Schema
Schema的主要用途是定义所有可供查询的字段(field)，它们最终组合成一套完整的GraphQL
API.
“graphql-java”提供两种方法来定义Schema。用java代码来定义、用GraphQL
SDL(即IDL)来定义。
注意：SDL(IDL)现在还不是 官方 graphql 规范. 本GraphQL实现，是基于
已有的JS参考实现
来开发的。但JS参考实现中的很多代码也是基于SDL(IDL)语法的，所以你可以认为这语法是可以长期使用的.
如果你不确认用“java代码”还是用“GraphQL
SDL(即IDL)”来定义你的Schema，那么我们建议你用SDL(IDL)
SDL example:
type Foo {
bar: String
}
java代码例子：
GraphQLObjectType fooType = newObject()
.name("Foo")
.field(newFieldDefinition()
.name("bar")
.type(GraphQLString))
.build();
DataFetcher 与 TypeResolver
对象 DataFetcher
作用是获取字段(field)对应的数据；另外，在修改(mutation)操作时，可以更新数据
每个字段都有自己的 DataFetcher. 如果未为字段指定DataFetcher,
那么自动使用默认的 PropertyDataFetcher .
PropertyDataFetcher 从 Map 和 Java Beans 中获取数据.
所以，当Schema中的field名，与Map中的key值，或 Source Object 中的 java
bean 字段名相同时，不需要为field指定 DataFetcher.
对象 TypeResolver 帮助 graphql-java 判断数据的实际类型(type). 所以
Interface 和 Union 均需要指定关联的 TypeResolver(类型识别器) .
例如，你有一个 Interface 叫 MagicUserType
它有可能是以下的具体类型(Type) Wizard, Witch and Necromancer.
Type resolver(类型识别器) 的作用是在运行时识别出 GraphqlObjectType
的具体类型(Type)。后期具体类型下的field相关的 data
fetcher被调用并获取数据.
new TypeResolver() {
@Override
public GraphQLObjectType getType(TypeResolutionEnvironment env) {
Object javaObject = env.getObject();
if (javaObject instanceof Wizard) {
return (GraphQLObjectType) env.getSchema().getType("WizardType");
} else if (javaObject instanceof Witch) {
return (GraphQLObjectType) env.getSchema().getType("WitchType");
} else {
return (GraphQLObjectType) env.getSchema().getType("NecromancerType");
}
}
};
用 SDL 创建 Schema
当使用SDL方法来开发时，你需要同时编写对应的 DataFetcher 和
TypeResolver。
很大的 Schema IDL 文件很难查看。
schema {
query: QueryType
}
type QueryType {
hero(episode: Episode): Character
human(id : String) : Human
droid(id: ID!): Droid
}
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
interface Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
homePlanet: String
}
type Droid implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
primaryFunction: String
}
由于Schema中只是指定了静态的字段和类型，你还需要把它绑定到java方法中。以让Schema可以运行起来
这里的绑定，包括 DataFetcher , TypeResolvers 与自定义 Scalar.
用下页的Builder方法，就可以绑定Schema和Java程序
RuntimeWiring buildRuntimeWiring() {
return RuntimeWiring.newRuntimeWiring()
.scalar(CustomScalar)
// this uses builder function lambda syntax
.type("QueryType", typeWiring -> typeWiring
.dataFetcher("hero", new StaticDataFetcher(StarWarsData.getArtoo()))
.dataFetcher("human", StarWarsData.getHumanDataFetcher())
.dataFetcher("droid", StarWarsData.getDroidDataFetcher())
)
.type("Human", typeWiring -> typeWiring
.dataFetcher("friends", StarWarsData.getFriendsDataFetcher())
)
// you can use builder syntax if you don't like the lambda syntax
.type("Droid", typeWiring -> typeWiring
.dataFetcher("friends", StarWarsData.getFriendsDataFetcher())
)
// or full builder syntax if that takes your fancy
.type(
newTypeWiring("Character")
.typeResolver(StarWarsData.getCharacterTypeResolver())
.build()
)
.build();
}
最后，你可以通过整合静态 Schema 和 绑定(wiring)，而生成一个可以执行的
Schema。
SchemaParser schemaParser = new SchemaParser();
SchemaGenerator schemaGenerator = new SchemaGenerator();
File schemaFile = loadSchema("starWarsSchema.graphqls");
TypeDefinitionRegistry typeRegistry = schemaParser.parse(schemaFile);
RuntimeWiring wiring = buildRuntimeWiring();
GraphQLSchema graphQLSchema = schemaGenerator.makeExecutableSchema(typeRegistry, wiring);
除了上面的 builder 风格, TypeResolver s 与 DataFetcher s 也可以通过
WiringFactory 接口绑定在一起。通过程序去分析 SDL
，就可以允许更自由的绑定。你可以 通过分析 SDL 声明, 或其它 SDL
定义去决定你的运行时逻辑。
RuntimeWiring buildDynamicRuntimeWiring() {
WiringFactory dynamicWiringFactory = new WiringFactory() {
@Override
public boolean providesTypeResolver(TypeDefinitionRegistry registry, InterfaceTypeDefinition definition) {
return getDirective(definition,"specialMarker") != null;
}
@Override
public boolean providesTypeResolver(TypeDefinitionRegistry registry, UnionTypeDefinition definition) {
return getDirective(definition,"specialMarker") != null;
}
@Override
public TypeResolver getTypeResolver(TypeDefinitionRegistry registry, InterfaceTypeDefinition definition) {
Directive directive = getDirective(definition,"specialMarker");
return createTypeResolver(definition,directive);
}
@Override
public TypeResolver getTypeResolver(TypeDefinitionRegistry registry, UnionTypeDefinition definition) {
Directive directive = getDirective(definition,"specialMarker");
return createTypeResolver(definition,directive);
}
@Override
public boolean providesDataFetcher(TypeDefinitionRegistry registry, FieldDefinition definition) {
return getDirective(definition,"dataFetcher") != null;
}
@Override
public DataFetcher getDataFetcher(TypeDefinitionRegistry registry, FieldDefinition definition) {
Directive directive = getDirective(definition, "dataFetcher");
return createDataFetcher(definition,directive);
}
};
return RuntimeWiring.newRuntimeWiring()
.wiringFactory(dynamicWiringFactory).build();
}
用代码方式创建 schema
如果用程序方式来定义 Schema，在创建类型(type)的时候，你需要提供
DataFetcher and TypeResolver 。
如:
DataFetcher fooDataFetcher = environment -> {
// environment.getSource() is the value of the surrounding
// object. In this case described by objectType
Foo value = perhapsFromDatabase(); // Perhaps getting from a DB or whatever
return value;
}
GraphQLObjectType objectType = newObject()
.name("ObjectType")
.field(newFieldDefinition()
.name("foo")
.type(GraphQLString)
.dataFetcher(fooDataFetcher))
.build();
类型(Types)
GraphQL 类型系统支持以下类型
Scalar
Object
Interface
Union
InputObject
Enum
Scalar
graphql-java 支持以下基本数据类型( Scalars)。
GraphQLString
GraphQLBoolean
GraphQLInt
GraphQLFloat
GraphQLID
GraphQLLong
GraphQLShort
GraphQLByte
GraphQLFloat
GraphQLBigDecimal
GraphQLBigInteger
Object
SDL Example:
type SimpsonCharacter {
name: String
mainCharacter: Boolean
}
Java 例子：
GraphQLObjectType simpsonCharacter = newObject()
.name("SimpsonCharacter")
.description("A Simpson character")
.field(newFieldDefinition()
.name("name")
.description("The name of the character.")
.type(GraphQLString))
.field(newFieldDefinition()
.name("mainCharacter")
.description("One of the main Simpson characters?")
.type(GraphQLBoolean))
.build();
Interface
Interfaces 是抽象的 类型( types)定义.
SDL Example:
interface ComicCharacter {
name: String;
}
Java 例子：
GraphQLInterfaceType comicCharacter = newInterface()
.name("ComicCharacter")
.description("An abstract comic character.")
.field(newFieldDefinition()
.name("name")
.description("The name of the character.")
.type(GraphQLString))
.build();
Union
SDL Example:
interface Cat {
name: String;
lives: Int;
}
interface Dog {
name: String;
bonesOwned: int;
}
union Pet = Cat | Dog
Java 例子：
GraphQLUnionType PetType = newUnionType()
.name("Pet")
.possibleType(CatType)
.possibleType(DogType)
.typeResolver(new TypeResolver() {
@Override
public GraphQLObjectType getType(TypeResolutionEnvironment env) {
if (env.getObject() instanceof Cat) {
return CatType;
}
if (env.getObject() instanceof Dog) {
return DogType;
}
return null;
}
})
.build();
Enum
SDL Example:
enum Color {
RED
GREEN
BLUE
}
Java 例子：
GraphQLEnumType colorEnum = newEnum()
.name("Color")
.description("Supported colors.")
.value("RED")
.value("GREEN")
.value("BLUE")
.build();
ObjectInputType
SDL Example:
input Character {
name: String
}
Java 例子：
GraphQLInputObjectType inputObjectType = newInputObject()
.name("inputObjectType")
.field(newInputObjectField()
.name("field")
.type(GraphQLString))
.build();
类型引用 (Type References) (递归类型recursive types)
GraphQL 支持递归类型：如 Person(人)
可以包含很多朋友【译注：当然这些也是人类型的】
为了方便声明这种情况， graphql-java 有一个 GraphQLTypeReference 类。
在实际的 Schema 创建时，GraphQLTypeReference 会变为实际的类型。
例如：
GraphQLObjectType person = newObject()
.name("Person")
.field(newFieldDefinition()
.name("friends")
.type(new GraphQLList(new GraphQLTypeReference("Person"))))
.build();
如果用SDL(ID L)来定义 Schema ，不需要特殊的处理。
Schema IDL的模块化
很大的 Schema IDL 文件很难查看。所以我们有两种方法可以模块化 Schema。
方法一是合并多个 Schema IDL 文件到一个逻辑单元( logic
unit)。下面的例子是，在 Schema 生成前，合并多个独立的文件。
SchemaParser schemaParser = new SchemaParser();
SchemaGenerator schemaGenerator = new SchemaGenerator();
File schemaFile1 = loadSchema("starWarsSchemaPart1.graphqls");
File schemaFile2 = loadSchema("starWarsSchemaPart2.graphqls");
File schemaFile3 = loadSchema("starWarsSchemaPart3.graphqls");
TypeDefinitionRegistry typeRegistry = new TypeDefinitionRegistry();
// each registry is merged into the main registry
typeRegistry.merge(schemaParser.parse(schemaFile1));
typeRegistry.merge(schemaParser.parse(schemaFile2));
typeRegistry.merge(schemaParser.parse(schemaFile3));
GraphQLSchema graphQLSchema = schemaGenerator.makeExecutableSchema(typeRegistry, buildRuntimeWiring());
Graphql IDL 还有其它方法去做模块化。你可以使用 type extensions
去为现有类型增加字段和 interface。
例如，一开始，你有这样一个文件：
type Human {
id: ID!
name: String!
}
你的系统的其它模块可以扩展这个类型：
extend type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
}
你可以按你的需要去扩展。它们会以被发现的顺序组合起来。重复的字段会被合并(但重定义一个字段的类型是不允许的)。
extend type Human {
homePlanet: String
}
完成合并后的 Human 类型会是这样的：
type Human implements Character {
id: ID!
name: String!
friends: [Character]
appearsIn: [Episode]!
homePlanet: String
}
这在顶层查询中特别有用。你可以用 extension types 去为顶层 “query”
增加字段每个团队可以提供自己的字段集，进而合成完整的查询。
schema {
query: CombinedQueryFromMultipleTeams
}
type CombinedQueryFromMultipleTeams {
createdTimestamp: String
}
# maybe the invoicing system team puts in this set of attributes
extend type CombinedQueryFromMultipleTeams {
invoicing: Invoicing
}
# and the billing system team puts in this set of attributes
extend type CombinedQueryFromMultipleTeams {
billing: Billing
}
# and so and so forth
extend type CombinedQueryFromMultipleTeams {
auditing: Auditing
}
Subscription(订阅)的支持
订阅功能还未在规范中： graphql-java 现在只支持简单的实现 ，你可以用
GraphQLSchema.Builder.subscription(...) 在 Schema
中定义订阅。这使你可以处理订阅请求。
subscription foo {
# normal graphql query
}