API & SDK Design #1, 資料分頁的處理方式

範例 Data API Service: Server Side Data Paging

這篇的應用範例，我從內政部的政府資料開放平台找了一個範例來當資料庫，示範這樣的 API service 該如何設計，以及能動之後，怎麼樣的設計才是良好的 API service ? 觀察過很多台灣的團隊，往往在這些實作的層面沒有仔細考量，造成維護上的困難。

API 的生態，跟應用軟體的生態不大一樣。很多老闆都會講服務應該快速推出，快速驗證市場需求；這是對的。不過 API 這種東西的訴求就完全不同，它的使用對象不是 End User, 而是 Developer. Developer 在意的不是 UX (User Experience, 使用者經驗), 而是 DX (Developer Experience - 開發者體驗) 啊.. DX 講求的是文件、API、SDK、及你提供的服務在 developer 眼裡看起來是否夠優雅? 效能夠好? 穩定可靠? 這篇我主要就是要探討 DX，因此重點會在 API 的定義跟 SDK 的包裝方式。

前面提到的 data service, 我想會 .NET 的人應該都沒問題吧? 開個 ASP.NET MVC WebAPI 的專案就可以搞定了。這邊我就直接跳到第一版，提供其他的開發人員查詢台灣鳥類生態觀察的資料。不多說，直接看 code:

接下來會有幾篇文章要延續這個範例，code 會不斷的修正。若要參考這篇文章提到的 sample code, 請參考 dev-API 這個分支。不介意的話，請給我個 star 鼓勵一下 :D

DATA FORMAT 說明

為了簡化問題，我沒有使用 database, 也沒使用 entity framework, 直接到政府的開放資料網站, 下載了這份 json 格式的 “特生中心102年繁殖鳥大調查資料集” 資料當作範例。檔案放在 ~/App_Data/birds.json, 我貼兩筆資料給大家看一下格式:

[
  {
    "SerialNo": "40298",
    "SurveyDate": "2013-06-21",
    "Location": "玉山西峰下",
    "WGS84Lon": "120.939592",
    "WGS84Lat": "23.468244",
    "FamilyName": "Paradoxornithidae",
    "ScienceName": "Fulvetta formosana",
    "TaiBNETCode": "425189",
    "CommonName": "灰頭花翼",
    "Quantity": "1",
    "BirdId": "B0364",
    "SiteId": "C37-02-06"
  },
  {
    "SerialNo": "40297",
    "SurveyDate": "2013-06-21",
    "Location": "玉山西峰下",
    "WGS84Lon": "120.939592",
    "WGS84Lat": "23.468244",
    "FamilyName": "Fringillidae",
    "ScienceName": "Pyrrhula erythaca",
    "TaiBNETCode": "380359",
    "CommonName": "灰鷽",
    "Quantity": "1",
    "BirdId": "B0516",
    "SiteId": "C37-02-06"
  }
  // 後面還有 998 筆資料...
]

API CODE (SERVER) 說明

我開了一個 “Azure Web APP” 類型的 ASP.NET Web Application, 其實就是拿掉大部分用不到的 code, 只保留 webapi 需要的部份而已。它的好處除了輕快之外，能夠在一般的 windows server 上面執行，也可以直接當成 Azure 的 API App 丟上雲端 Hosting。實際程式碼我有丟上 GitHub , 請參考 Demo.ApiWeb 這個 project. 其中關鍵的 ApiController: BirdsController.cs 內容如下:

public class BirdsController : ApiController
{
    protected override void Initialize(HttpControllerContext controllerContext)
    {
        BirdInfo.Init(File.ReadAllText(System.Web.HttpContext.Current.Server.MapPath("~/App_Data/birds.json")));
        base.Initialize(controllerContext);
    }

    public void Head()
    {
        System.Web.HttpContext.Current.Response.AddHeader("X-DATAINFO-TOTAL", BirdInfo.Data.Count().ToString());
        return;
    }

    private const int MaxTake = 10;

    public IEnumerable<BirdInfo> Get()
    {
        int start, take;
        if (int.TryParse(this.GetQueryString("$start"), out start) == false) start = 0;
        if (int.TryParse(this.GetQueryString("$take"), out take) == false) take = MaxTake;

        if (take > MaxTake) take = MaxTake;

        System.Web.HttpContext.Current.Response.AddHeader("X-DATAINFO-TOTAL", BirdInfo.Data.Count().ToString());
        System.Web.HttpContext.Current.Response.AddHeader("X-DATAINFO-START", start.ToString());
        System.Web.HttpContext.Current.Response.AddHeader("X-DATAINFO-TAKE", take.ToString());

        IEnumerable<BirdInfo> result = BirdInfo.Data;
        if (start > 0) result = result.Skip(start);
        result = result.Take(take);

        return result;
    }
    
    // GET api/values/5
    public BirdInfo Get(string id)
    {
        return BirdInfo.Get(id);
    }

    private string GetQueryString(string name)
    {
        foreach(var pair in this.Request.GetQueryNameValuePairs())
        {
            if (pair.Key == name) return pair.Value;
        }

        return null;
    }
}

API 呼叫方式說明

我示範的 API service, 只提供兩個功能，傳回格式統一為 JSON:

URL:
```
~/api/birds?$start={start}&$take={take}
```
列舉所有的資料
:
每次最多傳回 10 筆資料。可用兩個選用的參數指定傳回資料的範圍:
- $start 從第幾筆開始回傳 (預設值 0)
- $take 傳回幾筆 (預設值 10, 最大值 10) 除了傳回 JSON 格式的資料之外，也會在 HTTP response header 標註附加資訊:
- X-DATAINFO-TOTAL: 標示所有的資料共有幾筆
- X-DATAINFO-START: 標示傳回的資料是從第幾筆開始
- X-DATAINFO-TAKE: 標示傳回的資料最大筆數另外，除了 GET 之外，也支援 HEAD 這 verb, 不會傳回資料，但是會傳回 header, 這情況下只會傳回 X-DATAINFO-TOTAL
URL: ~/api/birds/{birdid} 直接傳回指定 ID 的那筆資料: 其實這些功能，用 Entity Framework, 加上 OData 就全搞定了，不過這邊這樣做下去就沒意思了，所以我特地簡化問題，讓大家看看怎麼自己刻出這功能。研究可以，正式上線的系統還是採用 OData 比較合適..

APP CODE 說明 (直接使用 HttpClient)

我寫了一個 Console Application, 請參考 Demo.Client.ConsoleApp 這個 project。從 Server 用上面說明的 API，自己用 HttpClient 按照規格呼叫，寫了一個把全部資料一頁一頁撈回來，自己過濾，只列出觀察地點是 “玉山排雲山莊” 的野生鳥類紀錄資料出來。由於沒有 server side query support, 所以過濾機制是在 client 做的，每次都必須從頭到尾掃描所有的資料。

我從內政部抓來的資料，剛剛好有 1000 筆，client / server 都在我 local pc 上面 (server 用 iis-express) 執行，跑出來約要 3000 msec 左右。先來看 code:

static void Main(string[] args)
{
    Stopwatch timer = new Stopwatch();
    timer.Start();

    // 方法1: 直接用 HttpClient 呼叫 web api
    ListAll_DirectHttpCall();
    
    Console.WriteLine($"* Total Time: {timer.ElapsedMilliseconds} msec.");
}

static Dictionary<string, string> _columns_name = new Dictionary<string, string>()
{
    { "SerialNo",       "流水號" },
    { "SurveyDate",     "調查日期" },
    { "Location",       "調查地點" },
    { "WGS84Lon",       "經度" },
    { "WGS84Lat",       "緯度"},
    { "FamilyName",     "科名"},
    { "ScienceName",    "學名" },
    { "TaiBNETCode",    "中研院學名代碼" },
    { "CommonName",     "鳥中名"},
    { "Quantity",       "數量"},
    { "BirdId",         "鳥名代碼" },
    { "SiteId",         "調查站碼"}
};

/// <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);
}

static void ShowBirdInfo(Dictionary<string, string> birdinfo)
{
    Console.WriteLine("[ID: {0}] -------------------------------------------------------------", birdinfo["BirdId"], birdinfo["CommonName"]);
    foreach (string name in _columns_name.Keys)
    {
        Console.WriteLine(
            "{0}: {1}",
            _columns_name[name].PadLeft(10, '　'),
            birdinfo.ContainsKey(name) ? (birdinfo[name]) : ("<NULL>"));
    }
    Console.WriteLine();
    Console.WriteLine();

}

主程式 ListAll_DirectHttpCall() 中，那個關鍵的 do while loop，共有 20 行，除了花 6 行是印出資料用的之外，其他其實都在處理分頁的動作，以及篩選出符合條件的邏輯。老實說我最討厭這種 code style, 因為不同目的的 code 都被摻在一起了… 我不要做撒尿牛丸啊..

APP CODE 說明 (使用 C# yield return)

不知還有沒有讀者記得我好幾年前寫的 “C# yield, how it work?” 的文章? Orz, 看看日期已經有八年了… 我一直覺的 C# 很多語法甜頭是很實用的，yield return 就是我最愛用的一個，不但可以解決多執行緒的一些困難，這次連這種遠端 server paging 的問題也能妥善處理.. 上述的主程式 ListAll_DirectHttpCall() 我換個方式重寫一次，來看看改寫過的 code:

static void ListAll_UseYield()
{
    // filter: 調查地點=玉山排雲山莊
    foreach (var item in (from x in GetBirdsData() where x["Location"] == "玉山排雲山莊" select x))
    {
        ShowBirdInfo(item);
    }
}

static IEnumerable<Dictionary<string, string>> GetBirdsData()
{
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri("http://localhost:56648");

    int current = 0;
    int pagesize = 5;

    do
    {
        Console.WriteLine($"--- 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)
        {
            //Console.WriteLine("ID: {0}", item["BirdId"]);
            yield return item;
        }

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

        current += pagesize;
    } while (true);

    yield break;
}

眼尖的讀者朋友們，看出差異了嗎? 用行數來看，其實沒省多少… 不過藉由 yield return, 我能夠很漂亮的實作 iterator patterns, 把物件巡覽及物件處理的邏輯清楚的切開..，GetBirdsData() 就只要專心負責取回所有的資料。然而資料該怎麼處理? 就留給主程式 ListAll_UseYield() 就可以了。

主程式很簡短，只有一個 Linq Query, 查出符合條件的資料，然後用 for-each loop 印出來。乾淨又漂亮的 code，解決了同樣的問題。

改善過的 code, 一眼望去，看起來好像是先把所有資料傳回來，再去一筆一筆過濾? 事實上不是這樣，它依然是按照我們的期望，一次讀 5 筆，讀完了也處理完了還有需要，才繼續讀後面五筆，直到完成為止。為了確認執行的順序，我做了幾個實驗:

結果觀察 - 觀察 API 呼叫與資料處理的交錯執行狀況

上述的 code 可以看到，在 GetBirdsData() 內每呼叫一次 server API, 就會印一次 “— loading data …”, 然而前端查到一筆符合的資料，就會印出一筆。我節錄這個 console app 的輸出結果給大家參考:

--- loading data... (75 ~ 80) ---
--- loading data... (80 ~ 85) ---
--- loading data... (85 ~ 90) ---
--- loading data... (90 ~ 95) ---
--- loading data... (95 ~ 100) ---
[ID: B0368] -------------------------------------------------------------
[ID: B0368] -------------------------------------------------------------
--- loading data... (100 ~ 105) ---
[ID: B0364] -------------------------------------------------------------
[ID: B0443] -------------------------------------------------------------
[ID: B0425] -------------------------------------------------------------
[ID: B0404] -------------------------------------------------------------
[ID: B0404] -------------------------------------------------------------
--- loading data... (105 ~ 110) ---
[ID: B0386] -------------------------------------------------------------
[ID: B0511] -------------------------------------------------------------
[ID: B0405] -------------------------------------------------------------
[ID: B0443] -------------------------------------------------------------
[ID: B0368] -------------------------------------------------------------
--- loading data... (110 ~ 115) ---
[ID: B0368] -------------------------------------------------------------
[ID: B0386] -------------------------------------------------------------
[ID: B0405] -------------------------------------------------------------
[ID: B0425] -------------------------------------------------------------
[ID: B0405] -------------------------------------------------------------
--- loading data... (115 ~ 120) ---
[ID: B0386] -------------------------------------------------------------
[ID: B0404] -------------------------------------------------------------
[ID: B0443] -------------------------------------------------------------
[ID: B0425] -------------------------------------------------------------
[ID: B0404] -------------------------------------------------------------
--- loading data... (120 ~ 125) ---

為了節省篇幅，我只節錄部分 (75 ~ 125 的資料區間)，同時我把顯示資料內容的部分都拿掉了，只顯示資料的 ID。仔細看看這段 LOG:

--- loading data... (95 ~ 100) ---
[ID: B0368] -------------------------------------------------------------
[ID: B0368] -------------------------------------------------------------
--- loading data... (100 ~ 105) ---

我們可以看到，呼叫 API 跟處理資料，真的是交錯進行的。GetBirdsData() 查詢到 95 ~ 100 筆的時候，這五筆資料就立即傳回 for-each loop 處理了，結果其中有兩筆資料符合，被列印了出來。之後處理完畢，接著又繼續 loading 後面五筆 100 ~ 105 的資料..

結果觀察 - 中斷迴圈，資料載入狀況觀察

如果我程式調整一下，只搜尋到我要的那一筆之後就離開 for-each loop，那它會聰明的立即停止後續的 server API 呼叫嗎?

主程式改成這樣再測試一次看看:

static void ListAll_UseYield()
{
    // filter: ID = B0368，找到之後離開 for-each loop
    foreach (var item in (from x in GetBirdsData() where x["SerialNo"] == "40250" select x).Take(1))
    {
        ShowBirdInfo(item);
    }
}

執行的結果:

--- loading data... (0 ~ 5) ---
--- loading data... (5 ~ 10) ---
--- loading data... (10 ~ 15) ---
--- loading data... (15 ~ 20) ---
--- loading data... (20 ~ 25) ---
--- loading data... (25 ~ 30) ---
--- loading data... (30 ~ 35) ---
--- loading data... (35 ~ 40) ---
--- loading data... (40 ~ 45) ---
--- loading data... (45 ~ 50) ---
[ID: B0443] -------------------------------------------------------------
* Total Time: 266 msec.
Press any key to continue . . .

看起來的確很精確的，逐頁讀取資料，逐頁過濾後，我用 Linq 要求只取前面 1 筆 ( .Take(1) )，真的後面的 API 就不會再呼叫了。這是否是因為我 Linq Query 下的好的關係? 如果我 Query 一樣是查詢所有資料，但是是用 C# code, 在適當時間 break for-each loop, 結果是否會不同?

很簡單，實驗一下就知道了:

static void ListAll_UseYield()
{
    // filter: ID = B0368，找到之後離開 for-each loop
    foreach (var item in (from x in GetBirdsData() where x["SerialNo"] == "40250" select x))
    {
        ShowBirdInfo(item);
        break;
    }
}

結果跟上一段一模一樣，也是達成目的後就退出，沒有絲毫多於的浪費:

--- loading data... (0 ~ 5) ---
--- loading data... (5 ~ 10) ---
--- loading data... (10 ~ 15) ---
--- loading data... (15 ~ 20) ---
--- loading data... (20 ~ 25) ---
--- loading data... (25 ~ 30) ---
--- loading data... (30 ~ 35) ---
--- loading data... (35 ~ 40) ---
--- loading data... (40 ~ 45) ---
--- loading data... (45 ~ 50) ---
[ID: B0443] -------------------------------------------------------------
* Total Time: 271 msec.
Press any key to continue . . .

yield return 應用小結

這邊的案例，我覺得是 C# yield return 的應用上，很經典的一個使用案例。這也是我刻意不用 Microsoft OData 那套做法的目的。通通都包起來的話，各位可能永遠都不曉得原來 C# 的 yield return 這麼好用。而且雖然 OData 是個標準，但是我相信你也不是每次都能用的到的。有太多 data api, 並沒有按照 OData 的規範去實作，很多例子就像這次 sample code 一樣，API 有提供分頁功能，但是沒有按照 OData 標準來進行，於是你得像這樣自己實作..

其實這次的實作，原理已經跟 Microsoft 對 OData 的作法很類似了。有差異的部份是，Microsoft 在 Server 端用的是 IQueryable interface, 而不是 IEnumerable interface. 兩者的差別是，一個可以取得 QueryProvider, 直接給它更明確的查詢條件，而 IEnumerable 則很單純，只能單向的巡覽資料而已，不會有甚麼建立索引，或是查詢最佳化的機會。

我找兩篇文章給大家參考一下，有這兩個 interface 能力上的差別:

IEnumerable與IQuerya搞搞就懂
關於IQueryable特性的小實驗 - 黑暗執行緒

看的出來，實作 IEnumerable interface, 就只能 looping 掃描每一筆資料 (類似 SQL table scan)。而前端的 Linq, Microsoft 也有特別處理，能夠把 Linq Query 的條件，透過 OData 定義的參數送到後端，直接在 server side query 就過濾掉不必要的資料，連傳遞到前端都不用了，效率更佳! 因此要是你的使用環境能配合，有機會使用 OData, 不用考慮了, 用就對了!

Previous實做基礎技術 API & SDK Design NextAPI & SDK Design #2, 設計專屬的 SDK

Last updated 5 months ago