GraphQL java工程化实践

rockswang

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

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的,解决一些更高层的实际应用问题,比如通用的分页机制等。

graphql-java特定术语

  • 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写一个也很简单。

批量数据查询(解决N+1问题)

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

  1. BatchedDataFetcher: 用起来挺简单的,普通的DataFetcher是给你一个ID让你返回一个对象,批量版是给你一个ID列表,让你返回对应的对象列表。不过这个不是Facebook推荐的方式,在新版本中会废弃掉。
  2. DataLoader: 这个是Facebook官方推荐的方式,nodejs中的实现是基于js的异步机制延迟查询,把最近一个周期产生的多个查询集中执行(没详细了解,看文档大概如此),java版实现方式则略有不同,下面详细介绍。

关于DataLoader

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

大概原理(个人理解):

  1. 在DataFetcher方法中,并不直接返回实体类T,而是调用DataLoader.load()方法,返回一个CompletionStage<T>,这时并不立即进行实际查询,而是把这些异步阶段对象缓存起来。
  2. 在查询告一段落后(即能够立即获取的Field值都已取得,只剩下异步查询未完成了),graphql-java会通过DataLoaderDispatcherInstrumentation.dispatch方法通知所有当前注册的DataLoader去执行当前积压的所有异步阶段对象,具体就是会使用DataLoader对应的BatchLoader一次性查询一批对象。
  3. 这时候又有一批Field的值已经实际取得,继续按查询的请求向下层展开,如果有新的异步阶段对象产生,就继续步骤2,直到所有异步阶段对象都获得最终值。

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

查询的缓存

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

Cache<String, PreparsedDocumentEntry> 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订阅

阅读 10.4k

玩儿编程
编程也是可以玩儿的!微信公众号“玩儿编程”

To play is Human

1.4k 声望
151 粉丝
0 条评论

To play is Human

1.4k 声望
151 粉丝
文章目录
宣传栏