這些年 iCHEF 在前後端與 iOS 使用 GraphQL API 的 分享

自 2017 年第三季，iCHEF 相繼在後端、前端與 iOS 進行 GraphQL 的導入，也接著在許多大大小小的場合分享，相關連結附於文末，依時間排序如 PyCon US 2018、iPlayground 2018、ModernWeb’19、PyCon Japan 2019，以及 PyCon Taiwan 2019 等年度研討會。年初也在 iThome 上分享了一些歷程，還在 GitHub 上開源了在從 REST 轉到 GraphQL 時使用的後端 Python 套件 queryfilter。再為大家整理一次

關於 GraphQL 的大小事：

1. 各種大小公司 Netflix、Airbnb、GitHub、PayPal、IBM、Facebook、Audi 與 BMW 都有採用。影音平台上搜尋 GraphQL 的分享夠多了。也有各種程式語言與套件支援，不然誰要用。
2. 主打取代 REST，畢竟是從過去的血淚累積出來的。(見 3～7 點)
3. 預設開發時需要先訂一個 schema，有點像 REST 中期出來的 Swagger。
4. API 回傳資料是有型別的。
5. API 走 versionless，告別永遠不知為何的 api/v1/。
6. 有彈性的 API call：Client 端可決定要回傳的欄位以及要拉多廣多深的資料，而且一發呵成。
7. 相對持續進化的 Spec，有成立基金會維護。
8. Spec 不管認證與授權，要自己決定怎麼做。(常見解：JWT)
9. 通常效能不會變差，減少的 HTTP request 還能提升效能，會遇到 N+1 常常是程式的寫法問題。

關於 iCHEF 的經驗：

1. 起先是為了一個統一的開發流程，不用每次問現在要用哪一代 REST 的 endpoint 與實作風格，後來新專案就是都走 GrpahQL 路線。
2. 前端與 iOS 主要使用 Apollo 的 GraphQL 套件，後端 Python 用 Graphene 接 Django。
3. 使用分階段導入，從新專案開始，與現存 REST 共存，再一步步進化與替換。
4. Payload 的 log 要自己來刻了，不像以前常靠 Nginx 或 Apache 的 httpd log。
5. API rate limit 也是要手刻，或許另切一個新的 GraphQL URL endpoint 也是個解。不過暫時沒這個需求。
6. GraphQL 的套件有兩種路線，一是寫純文字 spec 再用套件生出 schema，一是手寫 code，用套件做型別轉換、schema 檢查等輔助。有趣的來了，iCHEF 走第三條路線，前後端手寫 code，用到套件 Graphene 寫的 code 生出 spec，iOS 再拿 spec 去餵給套件，未來回頭看可能也是個常見作法？
7. GraphQL 在 2016 前的 spec 不允許 None value，在目前的 Graphene 2.1 版想要清除特定欄位值的時候需要特別處理。
8. Enum 在 query & mutate 時函式庫的自動轉換常常很有限，建議還是都自己轉。

其它常見問題：

1. 如何取得主管同意轉換為 GraphQL？
   一．要符合組織目標與利益：如增進團隊溝通與開發流暢度，進而提升產品品質，更好的團隊擴展性，持續學習與進化的風氣，較能吸引未來或留住目前的工程師。
   二．要可行並可評估：提出一個以現有資源相對可行的規畫，並按步就班地導入，新技術的導入最好不是無路可退的，在較小的單一專案總是容易檢討、改進，或轉進。永遠要有 B 備案。
2. 如何鼓勵工程師轉換與學習 GraphQL？
   一．要符合工程師目標與利益：更好的工程品質－＞更好的生活－＞稍微好一點的人生、更容易的團隊溝通、更有競爭力的技能與知識、更有前景或至少更有趣的公司。
   二．要可行並可評估：API 再少也不要一次全轉。這個決定應該是一個相對多數或至少半數以上可接受的共識決，認真溝通不可少。要轉的話要給一定的合理時程，轉成功了、人也走了，才是得不償失。
   // 題外話 //
   沒人想學習新東西的話應該不是技術問題了，可能要回到人、錢、團隊以及組織文化那邊看看。如果團隊文化能圍繞在學習、分享並持續成長的風格上，對整個組織與個人都會更容易正向地合作並進化。基本上工程師在其能力範圍內，總是想要好一點的生活，然而所謂【足夠的工程品質】對每個人來說都不大相同，至少要試訂出一個可評估的標準，才會有討論的基準。
3. 多媒體或檔案上傳要怎麼用 GraphQL 做到？一解雖然是 base64 後包進 JSON，不過建議沒特殊需求的話，使用現有的 HTTP POST 簡單直接又方便，沒有 100% GraphQL 不會怎麼樣的。

細節歡迎來討論，後端工程師總是會出現在每個月辦公室樓下舉辦的 Taipei.py — Python 聚會、iOS 工程師常在 Swift 聚會 、前端與 QE 也常在相關社群裡出現，你找得到他們的。當然直接進辦公室來聊也相當歡迎，我們也徵設計師呢。

參考：

• 【Win back lovely API — GraphQL in Python】in PyCon US 2018、【GraphQL with Graphene and Django, Laughters and Tears】in PyCon TW 2019 and poster session in PyCon Japan 2019, by Keith Yang
• 【從 RESTful API 到 GraphQL】by 丁沛堯, in iPlayground 2018
• 【在 iCHEF 以 Apollo + React 導入 GraphQL 的經驗】by 張登皓, in ModernWeb’19
• iCHEF/queryfilter on GitHub
• 【顛覆傳統REST網頁設計架構，GraphQL讓前後端API說同樣的語言】, iThome, 2019–01–23
• REST Swagger
• Json Web Tokens (JWT)