爲了介紹使用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裏使用的非常多。
今天先到這。