GraphQL overview
Get started with GraphQL in .NET Core with Hot Chocolate v13.
前言
GraphQL 本身只是通訊接口，它挑戰的對象是 REST。可惜挑戰時機不太對，現時 Web 通訊協定由 HTTP/1.1 昇級 HTTP/2 的灰色時期。且 REST 的競爭對象不只 GraphQL 其他如 gRPC 等也是強力競爭對手。
GraphQL 與 Swagger 、gRPC、SOAP/Web Service 等有共通點在不同平台有多種實作產品。
GraphQL 有描述語言 SDL: The Schema Definition Language，描述通訊封包 Schema。
GraphQL 通訊封包只有一套，Reqeust 是 SDL；Response 是 JSON。通訊封包只支援文字格式。
GraphQL 本身只是傳輸封包規格而已，在不同平台有多種實作產品且還在持續進化中。在二年前評估階段本人是把它刷下來的。現在再評估一次應該是可用的了，成熟度也已足夠。
GraphQL 的 schema 統合成三大部份，對應的指令也是這三個: query、mutation、subcription。這裡先總結如下:
query: 做的最好也是主要賣點。不得不承認這招查詢辦法真的很不錯用在 Open Data 領域真正好。
mutation: 異動，就是新增/修改/刪除，這一項還好。 現階段不建議採用。除非異動只佔系統功能 10% 不到，就是導入其它異動方案(如 REST)的成本就大於這10%的情境外。
subcription: “訂閱”，其實體並非訂閱而是 Server side streaming 且需有 web socket 支援。這項目也不錯。
GraphQL 的通訊還是以 HTTP/1.1 為主。傳輸封包部份 query 與 mutation 用 HTTP/1.1；而 subcription 用 WebSocket 。在進階應用上可以有條件的搭在 gRPC、Redis 上。
現階段可以用在只有查詢的需求或CQRS 模式中查詢部份的實作方案。若未來 GraphQL 也支援 HTTP/2 的話那可能就不一樣了。
最後這次評估中 GraphQL 實作方案選用 Hot Chocolate v13.8.1 ，其實一開始是另一個但沒有成功換成熱可可後一下就成功了。
補充 on 2024-1-8
優點：
非常適合用於 Open Data 應用。其他就還好。其查詢指令 query 設計部份老實說相當有創意。
也適用於大數據訊息交換/自動同步，使用 subcription 機制。
GraphQL 前端的 query 相當有彈性動態取想取的資訊即可。也可以 Filtering, Pagination & Sorting 。schema 設計良好的話甚至可以 “union” 後端資訊。
GraphQL 前端 schema 欄位是動態的，不過 data type 是強型別。
缺點/不足：
GrqphQL 本身不支援傳檔。官方答案是用 URL 間接下載檔案。當然也可以自己繞一圈把 binary 轉成 BASE64 再傳遞。
GraphQL 後端的實作比較麻煩一些，這可以理解，為了前端高彈性應用後端就要有相應的實作支援。
GraphQL 並不適合大部份是資料 CRUD 異動操作的應用。
多組 mutation 交易一致性問題。GraphQL 語法可以同時動態送出多組 mutation 交易但交易一致性沒有規劃（或根本無法處理）由各個實作體決定。
引言
發現一個 GraphQL 深入淺出的 overview 介紹。看完後將投影片整理如下。
本人將從影片截取投影片並加入個人詮釋。
參考文件
此展示影片來自 Get started with GraphQL in .NET Core。
GraphQL 資源
投影片
來自 Facebook API 實例等等，各類數據的查詢以 RESTful/JSON 指令實作。
GraphQL 查詢語法
GraphQL 查詢語法最主要的特性之一是需指定查詢結果的格式。
下面是最簡單的 GraphQL 查詢語法，意指查詢：我的名字。
左邊是查詢指令；右邊是查詢結果。
左邊查詢指令的規格名為 SDL，與 JSON 很像但不是。（可以看出應該是特殊化 JSON）
右邊查詢結果是紮紮實實的 JSON 格式。
查詢更多數據回來，可以指定多階層物件。可以看出來 SDL 與 JSON 基本的語法可以說是１對１。
再查詢更多數據回來，查詢結果當然也支援多筆/清單/陣列。
比較特別的在：GraphQL 查詢結果１筆與多筆的語法是一樣的。
要分辨的話建議從『名字』下手。比如查詢一位本書叫『book』；查詢多本書叫『books』或『bookList』。 查詢一位朋友數據叫『friend』；查詢全部朋友數據『friends』或『friendList』等等。
進階的查詢可以用 fragment 來組織共用的 type。
GraphQL 讓用戶可以精準地提出他們所需要的資料，而不需要多餘的資料。
何謂 GraphQL
GraphQL 與 RESE 指令比較。除了查詢也可以 CUD 這些動作在 GraphQL 術語叫"Mutation"。
另外也支援 "Subscription" 它其實不是訂閱而是 Server-side streaming。
GraphQL 的 "Subscription" 通訊底層是 web socket。"Query" 的通訊底是 HTTP/1.1。
GraphQL 應用實例畫面
Demo 1 : 基本操作
GraphQL 語法與術語。
Demo2: Fetching data with GraphQL
在 Hot Chocolate 套件系列也可以直接透過 EF(entity framework) 無縫銜接到 DB。下面是相關關鍵原碼截圖。
透過 EF(entity framework) 無縫銜接到 DB 之相關關鍵原碼截圖。
還支援分頁：UsePagging。
分頁 UsePagging 的查詢範例。
不只分頁還有排序 UseSorting 、過濾 UseFiltering 等等，這些機制都是用 Middleware 實作。
Middleware 概述
下圖是過濾 UseFiltering 的查詢範例。
過濾 UseFiltering 若與 ER 銜接則會自動產生查詢語法。
再附上 Middleware 相關關鍵原碼截圖參考。
DataLayer: 組織 GraphQL 數據來源框架
如圖，由想法到實際。
DataLayer 框架
DataLayer 框架 - 實際一些
DataLayer 框架 - 再實際一些
DataLayer 框架 - 實際範例
GraphQL 的資料來源可以是內部直接源生接上 DB。也可以來自現有的 RESTful API。
在 Hot Chocolate 套件系列也可以直接銜接到 RESTful API。
Demo3: Integrating data from REST services
在 Hot Chocolate 套件系列也可以直接銜接到 RESTful API。附上相關關鍵原碼截圖參考。
要額外填寫組態檔 Schema.graphql 。詳情請謨拜 google 大神。
DataLoader --- 進階篇
一般應該是不需要處理 DataLoader 段落的碼，除非有精進查詢 Improves Data Fetching 或更新後端(Mutation) Ensures Consistency 的需求吧？
DataLoader 的位置
DataLoader 框架圖
Subscriptions(訂閱) - Server side streaming
GraphQL Subscriptions 其實是 Server side streaming。
Subscriptions(訂閱)相關關鍵原碼截圖參考。詳情請謨拜 google 大神。
GraphQL Subscriptions 訂閱效果展示
GraphQL Subscriptions 其實是 Server side streaming。
Thank You
(EOF)
Last updated