Hypertext Application Language（HAL）

標籤：install   調用   部分   proc   text   png   github   tps   link   

Hypertext Application Language（HAL）

HAL，全稱為Hypertext Application Language，它是一種簡單的資料格式，它能以一種簡單、統一的形式，在API中引入超連結特性，使得API的可發現性（discoverable）更強，並具有自描述的特點。使用了HAL的API會更容易地被第三方開源庫所調用，並且使用起來也很方便，開發人員可以像處理普通JSON資料那樣去處理API資料。有關HAL的更多資訊，可以參考官方網站：http://stateless.co/hal_specification.html。

例子

下面就是一個典型的使用HAL的API的響應資料。

12345678910111213141516171819202122232425262728293031323334

{    "_links": {        "self": { "href": "/orders" },        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],        "next": { "href": "/orders?page=2" },        "ea:find": {            "href": "/orders{?id}",            "templated": true        }    },    "currentlyProcessing": 14,    "shippedToday": 20,    "_embedded": {        "ea:order": [{            "_links": {                "self": { "href": "/orders/123" },                "ea:basket": { "href": "/baskets/98712" },                "ea:customer": { "href": "/customers/7809" }            },            "total": 30.00,            "currency": "USD",            "status": "shipped"        }, {            "_links": {                "self": { "href": "/orders/124" },                "ea:basket": { "href": "/baskets/97213" },                "ea:customer": { "href": "/customers/12369" }            },            "total": 20.00,            "currency": "USD",            "status": "processing"        }]    }}

上面的JSON資料中，標註了高亮的幾行其實是真正的資料部分，其它部分就是增加的一些超連結，用以定位與當前資源（對象）相關的其它資源。比如，在_embedded節點下包含了兩個訂單資訊，在訂單資訊的_links節點下，就包含了與該訂單相關的其它資源的訪問連結，例如可以通過訪問/customers/7809連結，就可以獲得第一條訂單的客戶資訊。另外，在HAL中，超連結是可以為模板的，模板連結可以給定一個名稱，並指定templated為true。例如，上面,，子中的curies連結，指定了API文檔的連結模板，那麼，通過訪問http://example.com/docs/rels/find，就可以獲得有關擷取某個銷售訂單詳細資料API的文檔，通過訪問http://example.com/docs/rels/order，就可以獲得有關銷售訂單API的文檔。此外，上面的例子中還包含了擷取下一頁資料的連結（next連結），因此，用戶端只需要調用一次API，就能獲得與其相關的其它API的訪問連結。

.NET Core實現

Java中Spring Data在建立的Data Service API都預設使用了HAL，返回資料格式是application/hal+json或者application/hal+xml（HAL可以有JSON和XML兩種格式，本文只討論JSON格式）。於是，我基於.NET Core實現了HAL的編程模型，通過這個編程模型，今後就能很方便地在.NET Core Web API中啟用HAL的功能。項目的開源地址是：https://github.com/daxnet/hal。我也通過Jenkins持續整合，發布了NuGet包，可以支援.NET Framework 4.6.1以及Net Standard 1.6，這樣，既可以在經典.NET Framework，又可以在.NET Core中使用HAL庫。

在Visual Studio中，在NuGet Package Manager中添加NuGet Feed：https://www.myget.org/F/daxnet-utils/api/v3/index.json

然後，在控制台應用程式（Console Application）項目上選擇Manage NuGet Packages，開啟NuGet，Package source選擇剛剛添加的那個，然後選擇Hal後，點擊Install進行安裝。

安裝完成後，輸入下面代碼：

123456789101112131415161718192021222324252627282930313233

using System;using Hal.Builders; namespace ConsoleApp8{    public class Program    {        public static void Main(string[] args)        {            var builder = new ResourceBuilder();            var resource = builder                .WithState(new { currentlyProcessing = 14, shippedToday = 20 })                .AddSelfLink().WithLinkItem("/orders")                .AddCuriesLink().WithLinkItem("http://example.com/docs/rels/{rel}", "ea", true)                .AddLink("next").WithLinkItem("/orders?page=2")                .AddLink("ea:find").WithLinkItem("/orders{?id}", templated: true)                .AddEmbedded("ea:order")                    .Resource(new ResourceBuilder()                        .WithState(new { total = 30.00F, currency = "USD", status = "shipped" })                        .AddSelfLink().WithLinkItem("/orders/123")                        .AddLink("ea:basket").WithLinkItem("/baskets/98712")                        .AddLink("ea:customer").WithLinkItem("/customers/7809"))                    .Resource(new ResourceBuilder()                        .WithState(new { total = 20.00F, currency = "USD", status = "processing" })                        .AddSelfLink().WithLinkItem("/orders/124")                        .AddLink("ea:basket").WithLinkItem("/baskets/97213")                        .AddLink("ea:customer").WithLinkItem("/customers/12369"))                .Build();             Console.WriteLine(resource);        }    }}

運行一下試試？是否已經輸出了前面例子中的HAL JSON資料（如下）？

這個開發庫的一個亮點就是使用了流暢介面（Fluent API）的編程風格，開發人員能夠非常方便地使用此庫來產生所需的HAL資料。流暢介面的實現結合了裝飾器（Decorator）模式和C#的擴充方法，都定義在Hal.Builders命名空間下，有興趣的讀者可以下載原始碼查看。

附上整個HAL的物件模型類圖：

總結

相信本庫應該是.NET Core下第一個比較完整地實現了HAL規範的開源庫，它發布在MIT許可協議之下，商業友好，歡迎使用並提寶貴意見。在發現Bug後，也歡迎在Issue中提出，或者提交Pull Request。

 分類: .NET Core

Hypertext Application Language（HAL）