為了介紹使用ASP.NET Core構建GraphQL服務器,本文需要介紹一下GraphQL,其實看官網的文檔就行。
什么是GraphQL?
GraphQL 既是一種用於 API 的查詢語言也是一個滿足你數據查詢的運行時。 GraphQL 對你的 API 中的數據提供了一套易於理解的完整描述,使得客戶端能夠准確地獲得它需要的數據,而且沒有任何冗余,也讓 API 更容易地隨着時間推移而演進,還能用於構建強大的開發者工具。
官網地址:https://graphql.org/
中文網址(感覺不是官方的,連HTTPS都不是):http://graphql.cn/
GraphQL來自Facebook,它於2012年開始開發,2015年開源。
GraphQL與編程語言無關,可以使用很多種語言/框架來構建Graph 服務器,包括.NET Core。
像Github,Pinterest,Coursera等公司都在使用GraphQL。
Github的API到目前有4個版本,第三個版本都是用的是REST,而第四個版本使用的是GraphQL。
GraphQL到底是什么?
這就是一個GraphQL查詢的例子。左邊是查詢,右邊是結果。
從這個例子可以看出,查詢是可以嵌套的,所以使用GraphQL的客戶端可以通過一次請求獲得所有需要的數據。
每當對GraphQL服務器進行查詢的時候,這些查詢首先都會依據一個類型系統對其進行驗證。每個GraphQL服務都會在GraphQL schema里定義類型信息。
可以把這個類型系統看作是你的API數據的藍本,它由你定義的一系列對象所支撐。
例如這個User對象:
GraphQL經常被稱作是一個:聲明式數據獲取語言。
GraphQL的設計原則
- 分層結構:GraphQL的查詢是有層次結構的,字段可以內嵌其它字段;查詢和返回數據的結構是一致的。
- 以產品中心:GraphQL是由客戶端所需要的數據所驅動,語言和運行時也支持客戶端。
- 強類型:GraphQL服務器由GraphQL類型系統所支撐。在schema里,每個數據點都有一個特定的類型,針對這個類型還有驗證。
- 客戶端定制查詢:GraphQL服務器提供了可以讓客戶端進行定制查詢的能力。
- 內省(introspective):客戶端可以查詢GraphQL服務器的類型系(schema)。
為什么使用GraphQL?
談起GraphQL,總是離不開REST。
如果您想了解REST in ASP.NET Core,請看我寫的這個系列文章:https://www.cnblogs.com/cgzl/p/9178672.html#rest
REST有幾個問題:
過度獲取:REST里GET請求的查詢結果通常比較大,並且超過了客戶端的需求:
這里我只需要name,height,和mass,但是卻返回了所有的字段。
而使用GraphQL,我只需要查詢我需要的數據:
獲取不足:使用REST時,我想獲取部門和部門的人員,通常我需要先請求查詢部門列表;然后遍歷返回的部門列表,再次發出請求查詢每個部門下的人員,所以是N+1查詢。
而使用GraphQL,我就可以通過一個查詢請求(嵌套的)取得相應的結果。
不靈活:隨着API的演進,REST需要隨時創建新的端點,所以REST API的端點增長速度很快;此外有版本和兼容性需要謹慎考慮。
而GraphQL,典型的結構是只有一個端點。這個單端點就像API網關一樣組織了多個數據源,這樣就會更簡單。
綜上,使用GraphQL的好處是:
- 避免多重REST請求
- 向下兼容,無需考慮版本
- 可以對現有的數據源(例如REST API)進行包裝
- 與開發語言無關
GraphQL查詢
我通過Github的GraphQL Explorer來進行演示,網址是:https://developer.github.com/v4/explorer/
登錄之后,其效果如下:
Github使用了graphiql,graphiql是一個瀏覽器內的IDE,它可以用來瀏覽和查詢GraphQL。
graphiql的網址是:https://github.com/graphql/graphiql。
下一篇文章,我也會在.NET項目里安裝這個graphiql。
graphiql只是用來瀏覽查詢GraphQL的一個瀏覽工具而已,其它比較流行的工具還包括GraphQL Playground 和 GraphQL Voyager等。
第一個查詢
打開Github的GraphiQL以后,自動加載了一個查詢語句,我們點擊運行按鈕,右側就會返回查詢的結果:
在這里,我查詢了瀏覽者 viewer這個字段,當前瀏覽該網頁的就是我自己;在查詢里我還包括了viewer下的login字段,也就是登錄名。
結果以JSON形式返回,其數據包含在data屬性下,結構和查詢結構一致。
如果我還想在查詢中包含瀏覽者的姓名,那就加一個字段即可:
GraphQL的查詢也可以有注釋:
GraphiQL的智能提示
GraphiQL是具有智能提示的功能的。當你輸入一個字母之后,就是這種效果:
如果你什么都不輸入,還想知道有哪些字段,那么就按Alt+空格:
但是在windows上多少還是有些問題的,因為Alt+空格也會彈出瀏覽器的菜單😭。。。。
其實前面那個query關鍵字在這里是可以省略的,點擊prettify之后,就會把query關鍵字去掉;並且如果您的查詢格式比較亂的話,點擊prettify也會對查詢進行格式化:
查詢參數
在GraphQL里,每個字段都可以有自己的參數。
直接看例子。下面這個例子里,我想查詢登錄名為facebook的倉庫所有者:
括號里就是查詢參數,這個參數的作用就是過濾數據,返回login字段等於facebook的倉庫所有者。
再看一個例子,這次我要查詢repository,參數是name,參數值是graphql,點擊查詢:
注意,查詢語句里有紅色波浪線。不出意外,返回的了錯誤。
(所有的錯誤請求的返回結果都是這個格式的)。
錯誤信息里告訴我們要查詢repository這個字段,必須要提供owner這個參數,那么我們就加上這個參數:
這次終於返回了正確的結果。
也可以再添加幾個字段:
GraphQL Schema
上面我介紹了幾個查詢的例子,下面我介紹一下這個查詢的后台工作原理。
上面這些字段的設定是由GraphQL的schema來決定的。
- Schema提供了你的數據中所有使用的對象類型。
- 它制定了所有值的類型。
打開Github的Graphiql,右側有個Docs按鈕,也就是文檔:
每當我們定義了一個schema之后,文檔就會自動生成。
打開Docs,可以看到兩種操作類型:
- Query,查詢,也就是用來獲取數據的。
- Mutation,變化,也就是用來更新數據的。
點擊Query,進去后我們可以在這里看見之前進行的那些查詢:
那么就點擊一下剛才的repository這個查詢:
可以看到這個查詢需要兩個參數:owner和name,類型都是字符串。
再返回到Query,仔細看一下那些和字段在一起的黃色字體的東西:
這些就是類型。
在類型里,有的是常見的類型:例如String,Int,Float,Boolean,ID。
輸入類型和返回類型
當定義schema的時候,我們也會相應的定義所允許的輸入類型,它們可以是參數類型或字段類型。
輸入類型可以是:Int,Float,String,Boolean,Null,Enum,List,Object。
例如:
后邊的嘆號,表示該參數是必須的。
冒號后邊的部分就是返回類型
當我們定義好Schema之后,文檔就生成了,所以GraphQL是自我生成文檔的。
查詢Schema
除了看文檔之外,你可以直接查詢schema,這點在我們不使用graphiql的時候尤其有用。
這個查詢里,我們要查的是__schema字段;然后是它下面的queryType字段,queryType將會返回schema下所有的查詢;然后我再查詢queryType下的name和description,點擊運行,就會看到右邊的結果:name是Query,描述是它是Github GraphQL接口的query root。
這個結果和文檔里的描述是一樣的:
下面再加上fields字段看看:
這個結果的fields字段就包括很多內容了:codeOfConduct,license等等。而這些就是root query所有支持的字段。
查詢Type
除了查詢schema外,另一個有用的查詢就是Type的查詢。
例子,查詢Repository這個類型的相關信息,查詢__type字段,帶着參數name為Repository:
這個查詢結果也和文檔里的一致,我就不貼圖了。
別名
當我使用不同的參數來查詢兩個同樣的字段的時候,會報錯的:
時就應該使用別名了。添加別名只需要在字段前邊加上別名和冒號即可:
這回查詢就沒有錯誤了。
Fragment
上面的例子里,graphql和aspnethome都查詢的是相同的幾個字段。這樣的輸入就有點重復了,這時我們就可以使用Fragment。Fragement是可重用的字段集合,它可以根據需要被包含在查詢里。
上面的例子使用fragement以后就是這樣:
最下面是fragment的定義,使用fragment關鍵字,然后跟着自定義的名稱,它作用於Repository這個類型,大括號里就是需要查詢的字段。
在查詢里使用fragment時需要用三個點"...",它的作用相當於js里的展開操作符,把fragment里面的字段展開到相應的查詢里。
fragment在GraphQL里使用的非常多。
今天先到這。