使用ASP.NET Core開發GraphQL服務器 -- 預備知識(上)


為了介紹使用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,仔細看一下那些和字段在一起的黃色字體的東西:

這些就是類型

在類型里,有的是常見的類型:例如StringIntFloatBooleanID

 

輸入類型和返回類型

當定義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里使用的非常多

 

今天先到這。


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM