API & SDK Design #2, 設計專屬的 SDK

PreviousAPI & SDK Design #1, 資料分頁的處理方式 NextAPI & SDK Design #3, API 的向前相容機制

Last updated 1 year ago

API & SDK Design #2, 設計專屬的 SDK

什麼是 “SDK”?

SDK: Software Development Kit 的縮寫，一樣重點我擺在最後的 “K” (Kit) 上面。 SDK 的意思就是指讓你能順利開發軟體使用的套件。為何會跟 API 扯在一起? 通常 SDK 都是提供 API 的開發者，為了方便其他的開發者使用他的 API 所提供的對應套件 SDK。

在過去都是單機的時代，API 除了早已存在 OS 內的 System API 之外，其他的 API 通常都需要你先在本機上安裝某些套件之後才能使用，以 Microsoft 為例，就會有 XXXX redistributed 套件讓大家下載安裝 (一般使用者)。而如果你是開發者，就會有 XXXX SDK 可以下載安裝。SDK 除了 redistributed 套件的內容之外，還會附上文件，vs template, sample code, 甚至搭配一些配套的工具。

現在雲端時代，就不大一樣了。API 可能已經是泛指某個雲端上提供的 HTTP API / REST API。服務老早就存在那邊，甚至文件也都放在網站上了，所以單純的 “使用者” 不需要安裝任何東西，只要你看的懂文件，熟悉 HttpClient 就可以呼叫使用了。這時 SDK 的存在目的就有點不同了，他可能是為了讓你更方便的使用 API 而包裝的 LIBRARY，當然也可能搭配其他的工具及 sample code 等。

既然 SDK 可能會包含某些 Library, 那麼他就會是跟你使用的 OS, 程式語言，開發平台等等有關聯。舉個例子來說:

Microsoft Azure SDK

Microsoft 在 Azure 上面提供了相當多的 PaaS (Platform As A Service) 的服務，自然也有很多的 API 給所有開發者使用。不過寫過 HttpClient 的人就知道，看完 API DOC 後，你光是要成功的呼叫 API，可能就要寫十幾行 code 了，SDK 裡面附上的 Library 就能讓你簡化這些千篇一律的呼叫動作。其他有些 client 端就能完成的運算或是檢查，效能的最佳化，甚至有些動作可以在 client side 先行 cache 的部分，都有可能在 SDK 就處理掉。

看看 Azure SDK 的吧! 幾種主流的開發環境都有提供了 (.NET, Java, Node.js … 等等)。

Flickr SDK

再看第二個例子 Flickr。Flickr 是廣受使用者歡迎的相片服務，他也提供了完整的 API。在他的 API 下方就有個 “API 開發工具” 專區，放的就是各個平台的 SDK，包含 Flash (Action Script), C, Go, Java, .NET … 等等。這些 SDK 甚至不是由 Flickr 官方維護的，很多連結都是連到 GitHub 上面的 open source project.

YOUR FIRST SDK!

定義搞清楚後，接下來就繼續延續文章的範例程式了。

上次的 Source Code 有兩個 projects, 分別是:

Demo.ApiWeb 提供 API service 的 Web App
Demo.Client.ConsoleApp 呼叫 API 的 console application

(2) 的部分，我只列片段就好，全列實在太長了… @@

/// <summary>
/// 一般寫法，直接呼叫 HttpClient 分多次讀取資料分頁
/// </summary>
static void ListAll_DirectHttpCall()
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:56648");
    
    int current = 0;
    int pagesize = 5;

    do
    {
        Console.WriteLine($"[info] loading data... ({current} ~ {current + pagesize}) ---");
        HttpResponseMessage result = client.GetAsync($"/api/birds?$start={current}&$take={pagesize}").Result;

        var result_objs = JsonConvert.DeserializeObject<Dictionary<string, string>[]>(result.Content.ReadAsStringAsync().Result);


        foreach (var item in result_objs)
        {
            // filter: 調查地點=玉山排雲山莊
            if (item["Location"] != "玉山排雲山莊") continue;
            ShowBirdInfo(item);
        }

        if (result_objs.Length == 0) break;
        if (result_objs.Length < pagesize) break;

        current += pagesize;
    } while (true);
}

這段 code, 其實都在處理呼叫的細節, 而不是針對真正的問題處理。一開始為了準備 HttpClient 呼叫 API 的細節，就花了好幾行做準備。成功呼叫後為了順利解析 JSON 的格式，又定義了 class 來讓 Json library 做反序列化的動作。最後為了有效率的分批取回資料，又搭配了 server paging API + C# yield return, 做了額外的包裝，讓主程式可以用 for-each loop 或是 linq 來使用資料。這一切就花掉了 150 行的 code.

想像一下，如果你的服務實在太紅了，全球有上萬個不同的開發者，都在使用你的 API。那麼上面的這些 code, 是不是每個人都要做一次? 也許每個人做的不大一樣，但是應該也都大同小異吧! 我寫軟體最不能忍受的，就是存在兩份以上的 code 做一樣的事情…。解決方法很單純，不過就是寫個 library, 然後讓大家共用他。

因此，這個 solution, 我就在切出第三個 project, 當作我們的 SDK, 也就是呼叫這個 API 共用的 library. 我做了一些調整，先進行重構，把我想區隔開的邏輯切開，接著把它拆成獨立的 class library project。調整後你的 APP 主程式會長的像這個樣子:

using Demo.SDK;
using System;
using System.Diagnostics;
using System.Linq;

namespace Demo.Client.ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Stopwatch timer = new Stopwatch();
            timer.Start();
            
            // 方法3: 使用 SDK
            ListAll_UseSDK();
            
            Console.WriteLine($"* Total Time: {timer.ElapsedMilliseconds} msec.");
        }
        
        static void ListAll_UseSDK()
        {
            Demo.SDK.Client client = new Demo.SDK.Client(new Uri("http://localhost:56648"));
            foreach(var item in (from x in client.GetBirdInfos() where x.SerialNo == "40250" select x))
            {
                ShowBirdInfo(item);
                break;
            }
        }

        static void ShowBirdInfo(BirdInfo birdinfo)
        {
            Console.WriteLine($"[ID: {birdinfo.BirdId}] -------------------------------------------------------------");
            Console.WriteLine($"        流水號: {birdinfo.SerialNo}");
            Console.WriteLine($"      調查日期: {birdinfo.SurveyDate}");
            Console.WriteLine($"      調查地點: {birdinfo.Location}");
            Console.WriteLine($"     經度/緯度: {birdinfo.WGS84Lon}/{birdinfo.WGS84Lat}");
            Console.WriteLine($"          科名: {birdinfo.FamilyName}");
            Console.WriteLine($"          學名: {birdinfo.ScienceName}");
            Console.WriteLine($"中研院學名代碼: {birdinfo.TaiBNETCode}");
            Console.WriteLine($"        鳥中名: {birdinfo.CommonName}");
            Console.WriteLine($"          數量: {birdinfo.Quantity}");
            Console.WriteLine($"      鳥名代碼: {birdinfo.BirdId}");
            Console.WriteLine($"      調查站碼: {birdinfo.SiteId}");
            Console.WriteLine();
            Console.WriteLine();
        }
    }
}

主程式現在看起來就乾淨多了。程式裡面看到的，都是使用 APP 的人應該要處理的細節，包括從 server 取回資料後的篩選動作 (Linq), 以及篩選出來的資料顯示動作。

至於要連線 SERVER 的過程，全部被濃縮成這一行:

Demo.SDK.Client client = new Demo.SDK.Client(new Uri("http://localhost:56648"));

就好像我們使用 SQL server 一樣，建立好 connection 物件後就可以開始查詢了。至於 SDK project 的部分，來看看 SDK Client:

using Demo.SDK;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace Demo.SDK
{
    public class Client
    {
        private HttpClient _http = null;

        public Client(Uri serviceURL)
        {
            // do init / check
            this._http = new HttpClient();
            this._http.BaseAddress = serviceURL;
        }

        public IEnumerable<BirdInfo> GetBirdInfos()
        {
            int current = 0;
            int pagesize = 5;

            do
            {
                //Console.WriteLine($"--- loading data... ({current} ~ {current + pagesize}) ---");
                HttpResponseMessage result = _http.GetAsync($"/api/birds?$start={current}&$take={pagesize}").Result;

                var result_objs = JsonConvert.DeserializeObject<BirdInfo[]>(result.Content.ReadAsStringAsync().Result);

                foreach (BirdInfo item in result_objs)
                {
                    yield return item;
                }

                if (result_objs.Length == 0) break;
                if (result_objs.Length < pagesize) break;

                current += pagesize;
            } while (true);

            yield break;
        }

        public BirdInfo GetBirdInfo(string serialNo)
        {
            HttpResponseMessage result = _http.GetAsync($"/api/birds/{serialNo}").Result;
            var result_obj = JsonConvert.DeserializeObject<BirdInfo>(result.Content.ReadAsStringAsync().Result);
            return result_obj;
        }
    }
}

我的目的是先讓開發者建立 client 物件後，其餘存取 SERVER 的動作都透過這個 client 來進行，所以 SDK 這個 project 就把 BirdInfo 物件的定義, 還有 HttpClient 使用的細節都封裝了起來，也把 server side paging 的細節用 C# 的 yield return 方式轉譯封裝起來，第一版的 SDK 就完成了。

效果如你所見，使用上不再需要 APP 開發者處理呼叫 API 的細節了。所有想要用我 API 的人，只要拿 SDK 去使用就可以了。當然前提是你也要用 .NET, 如果你用其他語言 (如 Java), 那如上篇文章類似的動作你還是得照做一次。

SDK / API 的更新及維護問題?

問題到這邊就結束了嗎? 如果以第一版來說，的確結束了。接下來我們來看看 API 或是 SDK 改版會面臨的問題。我先用一張圖來描述 APP / SDK / API 三者之間的關係:

這裡面有四個部分，分別是 APP, SDK, API, SERVER。其中由於到目前為止，API 都只是紙上的 “定義”，所以我用虛線表示。

專案

誰負責維護?

更新時間

API

原廠

立即更新

SERVER

原廠

立即更新

SDK

原廠

原廠立即發行，開發者決定何時更新至APP

APP

開發者

開發者決定

好，問題開始浮現出來了。萬一 API 已經不敷使用，或是 API 設計存在問題，需要修正的時候… SERVER 跟 API 是原廠可以立即處理的，沒有問題。如果對應的 SDK 也需要修改，原廠也可以立即發行，沒有問題。

問題在於 APP 開發者啊，如果他沒辦法立即跟上最新版，則會有一段時間，有使用者用的 APP，是用舊版的 SDK，呼叫新版的 API SERVER。會造成什麼結果，其實是無法預期的。既然有這種風險，就該在他真的發生之前想辦法去控制他才對。

我舉個例子，假設這次的修正，是調整 BirdInfo 的一個欄位名稱，把 SerialNo 改成 BirdNo, 我們只改 SERVER，但是不改 SDK，看看會發生什麼事情?

修改前: Demo.ApiWeb/Models/BirdInfo.cs

public class BirdInfo
{
    public string SerialNo { get; set; }
    public string SurveyDate { get; set; }
    public string Location { get; set; }
    // 以下略過
}

修改後: Demo.ApiWeb/Models/BirdInfo.cs

public class BirdInfo
{
    public string BirdlNo { get; set; }
    public string SurveyDate { get; set; }
    public string Location { get; set; }
    // 以下略過
}

真糟糕，雖然不會有錯誤，但是程式執行結果也不正確了。一筆資料都查不出來…

* Total Time: 1932 msec.
Press any key to continue . . .

這個問題直到 SDK 對應的 BirdInfo 定義也跟著更新後才解決:

[ID: B0443] ----------------------
        流水號: 40250
      調查日期: 2013-06-21
      調查地點: 玉山西峰下
     經度/緯度: 120.937047/23.468776
          科名: Reguliidae
          學名: Regulus goodfellowi
中研院學名代碼: 380442
        鳥中名: 火冠戴菊鳥
          數量: 1
      鳥名代碼: B0443
      調查站碼: C37-02-04


* Total Time: 295 msec.
Press any key to continue . . .

如果這是 real case, 那麼緊急解決線上的問題，到這裡應該告一段落了。不過更新的問題一定會碰到，要徹底解決這問題的話，還是得從架構設計上著手。這過程我抓了兩個關鍵的原因，需要從架構設計面解決:

API 的定義，必須有具體 (code 化) 的表達方式，來確保兩端的定義是一致的
向前相容的問題處理，在 API 定義異動時，sdk 要有能力偵測並且正確的回應

接下來就針對這兩點，我們來看看怎麼持續改進 SDK 的 implementation

API: APP 與 Service 之間簽訂的合同

對比到現實世界，接案子時都會簽合約，雙方約定的事項條列在上面，之後一切按照合約條款進行，這是現實世界的規矩。套用到這邊也一樣，API 的定義也是講一樣的事情。在 .NET 裡面，你可以用 interface, 或是定義 data object 之類的方法讓前後端共用，編譯器就能幫你做完後面的檢查及驗證等等苦工。只要編譯能通過，就代表雙方是符合合約規範的。

後面的例子，我會把 API 定義的部分，再拆成獨立的 project: Demo.Contracts 。將來，除非你的 API 要正式異動，否則就不要去改這個 project. 在板控系統上的紀錄，這個 project 的任何異動，就視同 API 的修訂。在我們團隊實際的運作也是如此，因此這個 project 通常會限定異動的權限，必須是 architect, 或是 team leader, product owner 之類的角色才有權限調整。

原本的架構，調整後變成這樣，前後端都必須依照 contracts 的約定，來進行溝通:

首先，在整個 solution 內新增 Demo.Contracts 這個 class library project, 每個其他的 project 加入 reference. 接著就把需要統一規範的 interface or data contract 搬過來。

第一個要搬移的，就是前面案例碰到的 BirdInfo.cs，分享一下我調整的過程，可以最輕鬆的完成這件事:

由於改專案，我希望同時調整 namespace. 因此我先個別在兩個專案內把 BirdInfo 這 class 的 namespace 改成 Demo.Contracts, 透過 refactory 功能可以自動修正所有使用到他的 code
完成 (1) 之後，再把它搬到 Demo.Contracts project 內，由於 namespace 早就先改好了，所以只要單純的搬移 code
調整 projects 之間的 reference, 原本的 project 都加上 Demo.Contracts 的參考，重新編譯確認無誤後就完成了。

這個過程中，能夠善用 refactory 的話，可以替你節省不少力氣，否則你就要搬完 code, 改完 reference 後，編譯看看有多少 error 再一條一條修改。修正後的 solution 結構，長的像這樣:

SDK client interface: APP 與 SDK 之間簽訂的合同

接下來，很容易被忽略掉的一點，就是 APP 與 SDK 的相容性。還記得前面的表格嗎? SDK 是原廠維護的，而 APP 是開發者維護的。原本 APP 應該直接按照 API 規範來使用 SERVICE 的，所以之間的合約只要處理 API 就夠了。但是 SDK 替 APP 解決了這段問題，因此 APP 開發者真正要面對的規範，就往前提到 APP 與 SDK 之間了。

講具體一點，就是 SDK 有任何異動，是否能維持 APP 的相容性? 這邊的相容性，我分成幾個情況來說明:

APP 只要更新 SDK DLL，APP 不需要重新編譯
APP 需要更新 SDK 及重新編譯，不需要改 Code
SDK 大版本更新，APP 需要配合 SDK 重新調整 Code

一樣，我們用同樣的技巧，訂定 SDK contracts, 來解決 APP 跟 SDK 之間的問題。架構圖再調整一下，變成這樣:

Demo.Contracts 我也增加了 SDK Client interface:

namespace Demo.Contracts
{
    public interface ISDKClient
    {
        IEnumerable<BirdInfo> GetBirdInfos();
        BirdInfo GetBirdInfo(string serialNo);
    }
}

原本的 Demo.SDK.Client 配合調整，同時我也改成 Factory Pattern, 控制 SDK Client 產生的過程

namespace Demo.SDK
{
    public class Client : ISDKClient
    {
        private HttpClient _http = null;

        public static ISDKClient Create(Uri serviceURL)
        {
            return new Client(serviceURL);
        }

        private Client(Uri serviceURL)
        {
            // do init / check
            this._http = new HttpClient();
            this._http.BaseAddress = serviceURL;
        }

        public IEnumerable<BirdInfo> GetBirdInfos()
        {
            // 略
        }

        public BirdInfo GetBirdInfo(string serialNo)
        {
            // 略
        }
    }
}

最後 APP 呼叫端的 Code, 只改了取得 client 的部分。原本是:

Demo.SDK.Client client = new Demo.SDK.Client(new Uri("http://localhost:56648"));

// Do something...

修改後變成:

ISDKClient client = Demo.SDK.Client.Create(new Uri("http://localhost:56648"));

// Do something...

一樣，這樣以後就有一樣的效果了。除非這個 interface 內容有任何異動，否則你就再也不需要擔心 interface 異動造成問題了。

結論

到目前為止，整個 API service 的開發及部署架構已經出來了。除了 Demo.Client.ConsoleApp 之外，其他都是原廠的 API service 開發團隊負責的。隨著 API 的版本推進，不斷的 build solution, 不斷的 deployment, 做好 CI / CD 就沒問題了。

SDK 到這邊就結束了嗎? 還沒有… 下一篇要接著來講 API 的版本控制，及如何做好向前相容的版本管理。敬請期待 :D

最後補充一下，這邊說明的作法，我都已不需要太多外加的 framework, 或是套件為主，盡可能的自己實作。原因很簡單，倒不是說要自己發明輪子，而是不經過這樣的過程，你 (尤其是有打算朝架構師發展的朋友) 很難徹底理解為什麼要這樣做的原因。理解之後你可以在適當的領域，挑選適合的 framework 來使用。
之前在 facebook 上面曾經分享過，現在的技術發展太快了，不論做什麼事都有一堆框架 (framework) 可以選擇。年輕的工程師沒有足夠的時間跟經驗，從基礎開始學起，一開始就得面對龐大的框架，往往分不出甚麼是基礎，什麼是 platform / language, 什麼是 framework (舉例來說，javascript engine / dom / jquery / react / vue … 之間的關係你說的清楚嗎?)。當面臨 framework 的世代交替時，換到下一個新的 framework 能留下的經驗跟能力就很有限了，碰到 framework 不足的部分，或是根本都還沒有適合的 framework 時就會束手無策。
我這種年紀的傢伙比較幸運一點，當年還沒這麼多 framework, 我還有機會把基礎學好再來研究 framework, 因此現在看到不同的 framework, 我還能保有選擇跟理解的能力，碰到不足的部分我也有能力找出解法。我希望把這些經驗整理下來，分享給需要的朋友們。

PreviousAPI & SDK Design #1, 資料分頁的處理方式 NextAPI & SDK Design #3, API 的向前相容機制

Last updated 1 year ago