GraphQL java工程化实践

由于本身写过基于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订阅