摘要：我在工程實(shí)踐中直接使用類作為對(duì)應(yīng)實(shí)體類的。因此我的結(jié)論是，此庫(kù)并不適用于我的工程實(shí)踐。工程實(shí)踐中對(duì)其應(yīng)用方式的考慮在的官方教程中建議針對(duì)每請(qǐng)求創(chuàng)建新的實(shí)例，查詢請(qǐng)求結(jié)束則實(shí)例們的生命周期結(jié)束。

因?yàn)樽约簩?xiě)過(guò)基于react的前端應(yīng)用，因此一看到GraphQL就被深深吸引，真是直擊痛點(diǎn)?。?br>服務(wù)端開(kāi)發(fā)一直是基于java, Spring的，因此開(kāi)始研究如何在現(xiàn)有工程框架下加入graphql的支持。
本文屬于隨筆性質(zhì)，學(xué)到哪里，用到哪里，就寫(xiě)到哪里，觀點(diǎn)為個(gè)人理解，僅供參考。

Schema: 指一個(gè)特定GraphQL類型系統(tǒng)的定義，也指具體的包含類型系統(tǒng)定義的文本文件。在類型定義中，schema {...} 這樣的代碼塊定義的是入口類型，入口類型有三種，即查詢，變更和訂閱。值得說(shuō)明的是，查詢，變更和訂閱也都是普通的類型而已，和其它對(duì)象類型語(yǔ)法上沒(méi)有任何區(qū)別，只不過(guò)它們作為入口類型被定義在schema代碼塊中。

查詢(query)：定義為入口的對(duì)象類型；和變更、訂閱語(yǔ)法上并無(wú)不同，不過(guò)語(yǔ)義上對(duì)應(yīng)的是讀操作。

變更(mutation): 定義和語(yǔ)法同上，但語(yǔ)義上對(duì)應(yīng)增/刪/改操作。

訂閱(subscription): 定義和語(yǔ)法同上，語(yǔ)義上對(duì)應(yīng)的是一個(gè)訂閱操作以及隨后服務(wù)器對(duì)客戶端的0~N次主動(dòng)推送操作。

內(nèi)?。╥ntrospection）: 可以通過(guò)特殊的graphql查詢獲取到整個(gè)類型系統(tǒng)的詳細(xì)定義。這可能帶來(lái)數(shù)據(jù)模型過(guò)度暴露的問(wèn)題，以后會(huì)專門說(shuō)明。

類型(type): 沒(méi)什么好說(shuō)，就是對(duì)象類型，和標(biāo)量類型相對(duì)應(yīng)。

標(biāo)量(scalar): 非對(duì)象的簡(jiǎn)單數(shù)據(jù)類型，比如內(nèi)置的String, Int, ID等。可以自己定義新的標(biāo)量類型，只要為它編寫(xiě)序列化/反序列化方法即可，具體在graphql-java中對(duì)應(yīng)的類是Coercing。

字段(field): 對(duì)象類型的成員，可以是對(duì)象類型或者標(biāo)量類型。和java類里的field不同的是，GraphQL的field都是可以有參數(shù)的，因此有參數(shù)的field也可以理解成java中有特定類型返回值的方法。

接口(interface): 和java里的接口差不多，定義類型的公共字段，java實(shí)現(xiàn)中可以直接對(duì)應(yīng)寫(xiě)一個(gè)interface。有點(diǎn)麻煩的是在每個(gè)interface的實(shí)現(xiàn)類中都必須重復(fù)書(shū)寫(xiě)公共字段。

聯(lián)合(union): 和接口類似，但是不要求任何公共字段。為了方便可以在java實(shí)現(xiàn)中使用無(wú)方法的interface實(shí)現(xiàn)。

片段(fragment): 這是個(gè)查詢時(shí)的概念，和schema定義無(wú)關(guān)，用于預(yù)定義類型上的若干個(gè)字段組合，后面的查詢語(yǔ)句中可以反復(fù)引用，可避免重復(fù)書(shū)寫(xiě)這些字段組合。

內(nèi)聯(lián)片段(inline fragment)：片段還只是個(gè)簡(jiǎn)化查詢的可有可無(wú)的東西，但內(nèi)聯(lián)片段則更重要，對(duì)于返回interface或union類型的字段，需要使用內(nèi)聯(lián)片段來(lái)根據(jù)結(jié)果的實(shí)際類型獲取不同的字段。

別名(alias): 在查詢中可為特定字段的查詢?cè)黾觿e名，用來(lái)在返回的結(jié)果中加以區(qū)分，比如一次查詢了兩個(gè)特定用戶，因?yàn)轭愋拖嗤?，字段也相同，如果不用別名，則無(wú)法在結(jié)果中區(qū)分彼此。

類型擴(kuò)展(extend): 在schema中，可以使用extend給任意類型（包括interface/union）增加字段；這看似自找麻煩的機(jī)制實(shí)際上有很大用處，可以把高權(quán)限角色的特定字段使用extend寫(xiě)在另外的schema文件中，運(yùn)行時(shí)可合并解析，不同角色的用戶使用不同的schema。這樣可以通過(guò)加法來(lái)控制類型系統(tǒng)的可見(jiàn)性，避免內(nèi)省機(jī)制過(guò)度暴露類型系統(tǒng)。

DataLoader: 用于批量查詢，見(jiàn)后文介紹。

Relay: Facebook的另一個(gè)框架，應(yīng)該是基于GraphQL的，解決一些更高層的實(shí)際應(yīng)用問(wèn)題，比如通用的分頁(yè)機(jī)制等。

DataFetcher: 數(shù)據(jù)獲取器，即用以獲取Field實(shí)際值的對(duì)象。

Data Class: 數(shù)據(jù)類，這是graphql-java-tools中的概念，對(duì)應(yīng)schema中的同名對(duì)象類型。

可以在數(shù)據(jù)類上按照約定格式編寫(xiě)DataFetcher方法用于獲取簡(jiǎn)單字段值（比如無(wú)需另外查詢數(shù)據(jù)庫(kù)的字段）。

我在工程實(shí)踐中直接使用數(shù)據(jù)庫(kù)實(shí)體類作為數(shù)據(jù)類。

GraphQLResolver: 這是graphql-java-tools中的接口，帶有一個(gè)數(shù)據(jù)類的類型參數(shù)。

對(duì)該數(shù)據(jù)類定義部分或所有字段值的獲取方法，需要基于約定命名方法。

注意Resolver中的DataFetcher方法的優(yōu)先級(jí)高于DataClass中的方法。

我在工程實(shí)踐中直接使用Dao類作為對(duì)應(yīng)實(shí)體類的GraphQLResolver。

ExecutionInput: graphql-java中用來(lái)包裝一個(gè)完整查詢輸入的類，包括：

query - 查詢字符串;

operationName: 操作名; 可選；可用于在查詢中的多個(gè)操作中僅選擇特定名稱的予以執(zhí)行。

variables: 變量; 可選；一個(gè)Map，用于替換查詢字符串中形如"$value"的變量。

context - 上下文; 可選；任意Object類型，會(huì)被傳遞給DataFetcher；可用于傳遞當(dāng)前登錄用戶等。

root - 根對(duì)象; 可選；任意Object類型，會(huì)被傳遞給DataFetcher，語(yǔ)義上是被查詢的根對(duì)象。

ExecutionStrategy(執(zhí)行策略): 定義查詢的具體執(zhí)行策略。

比如是否異步執(zhí)行，多個(gè)子查詢是依次執(zhí)行，還是用線程池并發(fā)執(zhí)行等。

Instrumentation(攔截器): 比較像Servlet容器中的Filter，在查詢執(zhí)行前后各有一次執(zhí)行機(jī)會(huì)。

可用于對(duì)輸入和結(jié)果進(jìn)行額外處理；

支持鏈?zhǔn)綀?zhí)行；

需要指出的是DataLoader使用攔截器與核心系統(tǒng)耦合。

GraphqlFieldVisibility: 可以編程控制schema中各個(gè)字段的可見(jiàn)性。

和extend對(duì)應(yīng)，相當(dāng)于用減法來(lái)控制類型系統(tǒng)的可見(jiàn)性。

github上graphql-java名下的庫(kù)不少，如果希望了解各自簡(jiǎn)介的，可以看下awesome-graphql-java這個(gè)項(xiàng)目。
我自己評(píng)估了以下幾個(gè)：

graphql-java: 這個(gè)是核心庫(kù)，完全符合Facebook的spec，可以直接解析schema文件，但是類型綁定需要使用RuntimeWiring來(lái)編程方式添加，用起來(lái)還是比較麻煩的。

graphql-java-annotations: 這是數(shù)據(jù)驅(qū)動(dòng)的流派，使用注解直接在java類型上標(biāo)注GraphQL類型以及DataFetcher等，不用寫(xiě)schema文件。評(píng)估了一陣，個(gè)人感覺(jué)非常麻煩，比如：對(duì)每個(gè)字段都會(huì)創(chuàng)建新的DataFetcher實(shí)例來(lái)進(jìn)行解析，十分低效；要編寫(xiě)很多類來(lái)訪問(wèn)不同字段；過(guò)多的對(duì)象直接創(chuàng)建，難以托管到Spring容器；等等。因此我的結(jié)論是，此庫(kù)并不適用于我的工程實(shí)踐。

graphql-java-tools: 這是Schema驅(qū)動(dòng)的流派，這個(gè)庫(kù)使用Antlr自己重寫(xiě)了Schema解析器，使用GraphQLResolver實(shí)例和Data Class；基于方法名和參數(shù)的約定來(lái)定義DataFetching，使用起來(lái)很方便。這是我最終選定使用的庫(kù)。不太爽的地方有兩點(diǎn)：1) 當(dāng)前版本基于graphql-java 7.0，遲滯于核心庫(kù) 2) 使用Kotlin編寫(xiě)，我在MyEclipse里面無(wú)法正常設(shè)置斷點(diǎn)進(jìn)行跟蹤調(diào)試……

graphql-java-servlet: GraphQL不像傳統(tǒng)的REST，需要寫(xiě)一堆Controller，提供唯一的api接口即可，這個(gè)servlet就是幫你連這個(gè)都包辦的，不過(guò)我沒(méi)有用，自己基于SpringMVC寫(xiě)一個(gè)也很簡(jiǎn)單。

graphql-java提供了兩種批量數(shù)據(jù)查詢的方案:

BatchedDataFetcher: 用起來(lái)挺簡(jiǎn)單的，普通的DataFetcher是給你一個(gè)ID讓你返回一個(gè)對(duì)象，批量版是給你一個(gè)ID列表，讓你返回對(duì)應(yīng)的對(duì)象列表。不過(guò)這個(gè)不是Facebook推薦的方式，在新版本中會(huì)廢棄掉。

DataLoader: 這個(gè)是Facebook官方推薦的方式，nodejs中的實(shí)現(xiàn)是基于js的異步機(jī)制延遲查詢，把最近一個(gè)周期產(chǎn)生的多個(gè)查詢集中執(zhí)行（沒(méi)詳細(xì)了解，看文檔大概如此），java版實(shí)現(xiàn)方式則略有不同，下面詳細(xì)介紹。

graphql-java的dataloader是基于java8中新增的CompletableFeature類（大概相當(dāng)于javascript里面的Promise），實(shí)現(xiàn)異步延遲批量獲取查詢結(jié)果。

大概原理（個(gè)人理解）：

在DataFetcher方法中，并不直接返回實(shí)體類T，而是調(diào)用DataLoader.load()方法，返回一個(gè)CompletionStage，這時(shí)并不立即進(jìn)行實(shí)際查詢，而是把這些異步階段對(duì)象緩存起來(lái)。

在查詢告一段落后（即能夠立即獲取的Field值都已取得，只剩下異步查詢未完成了），graphql-java會(huì)通過(guò)DataLoaderDispatcherInstrumentation.dispatch方法通知所有當(dāng)前注冊(cè)的DataLoader去執(zhí)行當(dāng)前積壓的所有異步階段對(duì)象，具體就是會(huì)使用DataLoader對(duì)應(yīng)的BatchLoader一次性查詢一批對(duì)象。

這時(shí)候又有一批Field的值已經(jīng)實(shí)際取得，繼續(xù)按查詢的請(qǐng)求向下層展開(kāi)，如果有新的異步階段對(duì)象產(chǎn)生，就繼續(xù)步驟2，直到所有異步階段對(duì)象都獲得最終值。

工程實(shí)踐中對(duì)其應(yīng)用方式的考慮：
在graphql-java的官方教程中建議針對(duì)每請(qǐng)求創(chuàng)建新的DataLoader實(shí)例，查詢請(qǐng)求結(jié)束則DataLoader實(shí)例們的生命周期結(jié)束。
這個(gè)實(shí)現(xiàn)方式比較簡(jiǎn)單，不用考慮緩存的更新問(wèn)題，也不用考慮多個(gè)不同請(qǐng)求的緩存對(duì)象是否可共用。
舉個(gè)例子，張三和李四并發(fā)查詢張三的信息，他們獲取的"張三"用戶實(shí)例的結(jié)構(gòu)可能是不同的，這種情況這兩個(gè)并發(fā)請(qǐng)求就不能共用緩存，而應(yīng)該各自有獨(dú)立的DataLoader實(shí)例。
不過(guò)在我的工程實(shí)踐中，服務(wù)端內(nèi)存中的數(shù)據(jù)實(shí)體類都是客觀一致的，其結(jié)構(gòu)可見(jiàn)性應(yīng)在更上一層即DataFetcher甚至Schema級(jí)別中進(jìn)行過(guò)濾。
因此我的想法是為每種實(shí)體類維護(hù)單例的DataLoader，和Dao對(duì)象一一對(duì)應(yīng)。
這種情況下，就不能簡(jiǎn)單的使用DataLoader內(nèi)部默認(rèn)的簡(jiǎn)單內(nèi)存緩存了，因?yàn)榇司彺媸遣粫?huì)自動(dòng)定時(shí)清理的。
graphql-java是允許開(kāi)發(fā)者提供自己的緩存實(shí)現(xiàn)的，下一步我會(huì)結(jié)合項(xiàng)目中使用的Spring緩存管理器來(lái)具體實(shí)現(xiàn)。

graphql的查詢本身是有一定語(yǔ)法結(jié)構(gòu)的特殊文本，對(duì)該文本進(jìn)行解析也是有性能開(kāi)銷的，因此graphql-java提供了緩存機(jī)制方便開(kāi)發(fā)者把查詢文本的解析后數(shù)據(jù)結(jié)構(gòu)緩存起來(lái)。
以下代碼引自官方教程，我準(zhǔn)備結(jié)合我們項(xiàng)目里的EhCache來(lái)實(shí)作一下。

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

工程實(shí)踐中使用WebSocket實(shí)現(xiàn)訂閱。
無(wú)論是graphql還是graphql-java都未指定訂閱的具體實(shí)現(xiàn)機(jī)制，但WebSocket是現(xiàn)代瀏覽器普遍支持的，高性能低限制的服務(wù)器推送機(jī)制。
SpringMVC支持WebSocket，同時(shí)支持在低版本瀏覽器中使用Sock.js作為兼容備選方案。
另外，graphql-java體驗(yàn)性支持的Defer數(shù)據(jù)獲取也可基于WebSocket實(shí)現(xiàn)。

基于spring和graphql-java-tools的寵物店例程
簡(jiǎn)單的TODO例程，使用relay的思路解決分頁(yè)問(wèn)題
基于WebSocket實(shí)現(xiàn)GraphQL訂閱