GraphQL java工程化实践

摘要：我在工程实践中直接使用类作为对应实体类的。因此我的结论是，此库并不适用于我的工程实践。工程实践中对其应用方式的考虑在的官方教程中建议针对每请求创建新的实例，查询请求结束则实例们的生命周期结束。

因为自己写过基于react的前端应用，因此一看到GraphQL就被深深吸引，真是直击痛点啊！
服务端开发一直是基于java, Spring的，因此开始研究如何在现有工程框架下加入graphql的支持。
本文属于随笔性质，学到哪里，用到哪里，就写到哪里，观点为个人理解，仅供参考。

Schema: 指一个特定GraphQL类型系统的定义，也指具体的包含类型系统定义的文本文件。在类型定义中，schema {...} 这样的代码块定义的是入口类型，入口类型有三种，即查询，变更和订阅。值得说明的是，查询，变更和订阅也都是普通的类型而已，和其它对象类型语法上没有任何区别，只不过它们作为入口类型被定义在schema代码块中。

查询(query)：定义为入口的对象类型；和变更、订阅语法上并无不同，不过语义上对应的是读操作。

变更(mutation): 定义和语法同上，但语义上对应增/删/改操作。

订阅(subscription): 定义和语法同上，语义上对应的是一个订阅操作以及随后服务器对客户端的0~N次主动推送操作。

内省（introspection）: 可以通过特殊的graphql查询获取到整个类型系统的详细定义。这可能带来数据模型过度暴露的问题，以后会专门说明。

类型(type): 没什么好说，就是对象类型，和标量类型相对应。

标量(scalar): 非对象的简单数据类型，比如内置的String, Int, ID等。可以自己定义新的标量类型，只要为它编写序列化/反序列化方法即可，具体在graphql-java中对应的类是Coercing。

字段(field): 对象类型的成员，可以是对象类型或者标量类型。和java类里的field不同的是，GraphQL的field都是可以有参数的，因此有参数的field也可以理解成java中有特定类型返回值的方法。

接口(interface): 和java里的接口差不多，定义类型的公共字段，java实现中可以直接对应写一个interface。有点麻烦的是在每个interface的实现类中都必须重复书写公共字段。

联合(union): 和接口类似，但是不要求任何公共字段。为了方便可以在java实现中使用无方法的interface实现。

片段(fragment): 这是个查询时的概念，和schema定义无关，用于预定义类型上的若干个字段组合，后面的查询语句中可以反复引用，可避免重复书写这些字段组合。

内联片段(inline fragment)：片段还只是个简化查询的可有可无的东西，但内联片段则更重要，对于返回interface或union类型的字段，需要使用内联片段来根据结果的实际类型获取不同的字段。

别名(alias): 在查询中可为特定字段的查询增加别名，用来在返回的结果中加以区分，比如一次查询了两个特定用户，因为类型相同，字段也相同，如果不用别名，则无法在结果中区分彼此。

类型扩展(extend): 在schema中，可以使用extend给任意类型（包括interface/union）增加字段；这看似自找麻烦的机制实际上有很大用处，可以把高权限角色的特定字段使用extend写在另外的schema文件中，运行时可合并解析，不同角色的用户使用不同的schema。这样可以通过加法来控制类型系统的可见性，避免内省机制过度暴露类型系统。

DataLoader: 用于批量查询，见后文介绍。

Relay: Facebook的另一个框架，应该是基于GraphQL的，解决一些更高层的实际应用问题，比如通用的分页机制等。

DataFetcher: 数据获取器，即用以获取Field实际值的对象。

Data Class: 数据类，这是graphql-java-tools中的概念，对应schema中的同名对象类型。

可以在数据类上按照约定格式编写DataFetcher方法用于获取简单字段值（比如无需另外查询数据库的字段）。

我在工程实践中直接使用数据库实体类作为数据类。

GraphQLResolver: 这是graphql-java-tools中的接口，带有一个数据类的类型参数。

对该数据类定义部分或所有字段值的获取方法，需要基于约定命名方法。

注意Resolver中的DataFetcher方法的优先级高于DataClass中的方法。

我在工程实践中直接使用Dao类作为对应实体类的GraphQLResolver。

ExecutionInput: graphql-java中用来包装一个完整查询输入的类，包括：

query - 查询字符串;

operationName: 操作名; 可选；可用于在查询中的多个操作中仅选择特定名称的予以执行。

variables: 变量; 可选；一个Map，用于替换查询字符串中形如"$value"的变量。

context - 上下文; 可选；任意Object类型，会被传递给DataFetcher；可用于传递当前登录用户等。

root - 根对象; 可选；任意Object类型，会被传递给DataFetcher，语义上是被查询的根对象。

ExecutionStrategy(执行策略): 定义查询的具体执行策略。

比如是否异步执行，多个子查询是依次执行，还是用线程池并发执行等。

Instrumentation(拦截器): 比较像Servlet容器中的Filter，在查询执行前后各有一次执行机会。

可用于对输入和结果进行额外处理；

支持链式执行；

需要指出的是DataLoader使用拦截器与核心系统耦合。

GraphqlFieldVisibility: 可以编程控制schema中各个字段的可见性。

和extend对应，相当于用减法来控制类型系统的可见性。

github上graphql-java名下的库不少，如果希望了解各自简介的，可以看下awesome-graphql-java这个项目。
我自己评估了以下几个：

graphql-java: 这个是核心库，完全符合Facebook的spec，可以直接解析schema文件，但是类型绑定需要使用RuntimeWiring来编程方式添加，用起来还是比较麻烦的。

graphql-java-annotations: 这是数据驱动的流派，使用注解直接在java类型上标注GraphQL类型以及DataFetcher等，不用写schema文件。评估了一阵，个人感觉非常麻烦，比如：对每个字段都会创建新的DataFetcher实例来进行解析，十分低效；要编写很多类来访问不同字段；过多的对象直接创建，难以托管到Spring容器；等等。因此我的结论是，此库并不适用于我的工程实践。

graphql-java-tools: 这是Schema驱动的流派，这个库使用Antlr自己重写了Schema解析器，使用GraphQLResolver实例和Data Class；基于方法名和参数的约定来定义DataFetching，使用起来很方便。这是我最终选定使用的库。不太爽的地方有两点：1) 当前版本基于graphql-java 7.0，迟滞于核心库 2) 使用Kotlin编写，我在MyEclipse里面无法正常设置断点进行跟踪调试……

graphql-java-servlet: GraphQL不像传统的REST，需要写一堆Controller，提供唯一的api接口即可，这个servlet就是帮你连这个都包办的，不过我没有用，自己基于SpringMVC写一个也很简单。

graphql-java提供了两种批量数据查询的方案:

BatchedDataFetcher: 用起来挺简单的，普通的DataFetcher是给你一个ID让你返回一个对象，批量版是给你一个ID列表，让你返回对应的对象列表。不过这个不是Facebook推荐的方式，在新版本中会废弃掉。

DataLoader: 这个是Facebook官方推荐的方式，nodejs中的实现是基于js的异步机制延迟查询，把最近一个周期产生的多个查询集中执行（没详细了解，看文档大概如此），java版实现方式则略有不同，下面详细介绍。

graphql-java的dataloader是基于java8中新增的CompletableFeature类（大概相当于javascript里面的Promise），实现异步延迟批量获取查询结果。

大概原理（个人理解）：

在DataFetcher方法中，并不直接返回实体类T，而是调用DataLoader.load()方法，返回一个CompletionStage，这时并不立即进行实际查询，而是把这些异步阶段对象缓存起来。

在查询告一段落后（即能够立即获取的Field值都已取得，只剩下异步查询未完成了），graphql-java会通过DataLoaderDispatcherInstrumentation.dispatch方法通知所有当前注册的DataLoader去执行当前积压的所有异步阶段对象，具体就是会使用DataLoader对应的BatchLoader一次性查询一批对象。

这时候又有一批Field的值已经实际取得，继续按查询的请求向下层展开，如果有新的异步阶段对象产生，就继续步骤2，直到所有异步阶段对象都获得最终值。

工程实践中对其应用方式的考虑：
在graphql-java的官方教程中建议针对每请求创建新的DataLoader实例，查询请求结束则DataLoader实例们的生命周期结束。
这个实现方式比较简单，不用考虑缓存的更新问题，也不用考虑多个不同请求的缓存对象是否可共用。
举个例子，张三和李四并发查询张三的信息，他们获取的"张三"用户实例的结构可能是不同的，这种情况这两个并发请求就不能共用缓存，而应该各自有独立的DataLoader实例。
不过在我的工程实践中，服务端内存中的数据实体类都是客观一致的，其结构可见性应在更上一层即DataFetcher甚至Schema级别中进行过滤。
因此我的想法是为每种实体类维护单例的DataLoader，和Dao对象一一对应。
这种情况下，就不能简单的使用DataLoader内部默认的简单内存缓存了，因为此缓存是不会自动定时清理的。
graphql-java是允许开发者提供自己的缓存实现的，下一步我会结合项目中使用的Spring缓存管理器来具体实现。

graphql的查询本身是有一定语法结构的特殊文本，对该文本进行解析也是有性能开销的，因此graphql-java提供了缓存机制方便开发者把查询文本的解析后数据结构缓存起来。
以下代码引自官方教程，我准备结合我们项目里的EhCache来实作一下。

Cache cache = Caffeine.newBuilder().maximumSize(10_000).build();
GraphQL graphQL = GraphQL.newGraphQL(StarWarsSchema.starWarsSchema)
        .preparsedDocumentProvider(cache::get)
        .build();

工程实践中使用WebSocket实现订阅。
无论是graphql还是graphql-java都未指定订阅的具体实现机制，但WebSocket是现代浏览器普遍支持的，高性能低限制的服务器推送机制。
SpringMVC支持WebSocket，同时支持在低版本浏览器中使用Sock.js作为兼容备选方案。
另外，graphql-java体验性支持的Defer数据获取也可基于WebSocket实现。

基于spring和graphql-java-tools的宠物店例程
简单的TODO例程，使用relay的思路解决分页问题
基于WebSocket实现GraphQL订阅