使用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，仔細看一下那些和字段在一起的黃色字體的東西：
這些就是類型。
在類型里，有的是常見的類型：例如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里使用的非常多。
?
今天先到這。
總結
以上是生活随笔為你收集整理的使用ASP.NET Core开发GraphQL服务器 -- 极简预备知识(上)的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： .NET和Docker ，比翼双飞
- 下一篇： 使用 dotnet 命令行配合 vsco