使用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，請看我寫的這個系列文章：http://www.javashuo.com/article/p-rqwpmfqu-gm.html

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裏使用的很是多。

 

今天先到這。