HAL，全稱為Hypertext Application Language，它是一種簡單的數(shù)據(jù)格式，它能以一種簡單、統(tǒng)一的形式，在API中引入超鏈接特性，使得API的可發(fā)現(xiàn)性（discoverable）更強，并具有自描述的特點。使用了HAL的API會更容易地被第三方開源庫所調(diào)用，并且使用起來也很方便，開發(fā)者可以像處理普通JSON數(shù)據(jù)那樣去處理API數(shù)據(jù)。有關HAL的更多信息，可以參考官方網(wǎng)站：http://stateless.co/hal_specification.html。目前，很多RESTful服務開發(fā)框架都支持HAL的Response格式（Content-Type為application/hal+json），比如大名鼎鼎的Spring Data，默認就支持HAL。現(xiàn)在，使用全新的Apworks Core（今后簡稱Apworks）開發(fā)數(shù)據(jù)服務時，默認也提供對HAL的支持。

HAL的啟用和禁用

在上一篇快速開發(fā)文章中，演練部分通過修改Startup.cs文件中的ConfigureServices方法以在ASP.NET Core Web API中啟用Apworks以及Data Service的開發(fā)支持。首先我們回顧一下這段代碼：

public? void? ConfigureServices(IServiceCollection services) { ???? // Add framework services. ???? services.AddMvc(); ???? services.AddApworks() ???????? .WithDataServiceSupport( new? DataServiceConfigurationOptions ???????????? ( new? MongoRepositoryContext ???????????????? ( new? MongoRepositorySettings( "localhost" , "customer-service" )))) ???????? .Configure(); }

?

默認情況下，HAL的支持是啟用的。也就是說，當你運行Data Service時，直接發(fā)起HTTP GET請求，返回的Response已經(jīng)是application/hal+json格式的了：

注意：由于返回的數(shù)據(jù)量并沒有超出一頁的分頁尺寸，所以在_links下僅顯示了一個self的鏈接。如果存在多個分頁，那么_links部分也會出現(xiàn)prev、next、first、last等鏈接。

如果希望禁用HAL的功能，其實非常簡單，在上面的代碼中，在構造DataServiceConfigurationOptions時直接指定useHalSupport參數(shù)為false即可：

public? void? ConfigureServices(IServiceCollection services) { ???? // Add framework services. ???? services.AddMvc(); ???? services.AddApworks() ???????? .WithDataServiceSupport( new? DataServiceConfigurationOptions ???????????? ( new? MongoRepositoryContext ???????????????? ( new? MongoRepositorySettings( "localhost" , "customer-service" )), useHalSupport: false )) ???????? .Configure(); }

于是，得到的返回內(nèi)容就不再是application/hal+json，而是application/json了：

開發(fā)人員在開發(fā)Data Service的時候，可以根據(jù)自己的需求啟用或者禁用HAL的支持。

自定義HAL的返回內(nèi)容

在ASP.NET Core Web API中使用Apworks開發(fā)數(shù)據(jù)服務時，對于HAL的返回內(nèi)容是可以自定義的。當然，這并不會改變HTTP Response的Content-Type，而是針對Response Body，其Json內(nèi)容是可以被自定義的。例如，在上面的例子中，HTTP GET的Response Body中不僅包含所請求的數(shù)據(jù)對象數(shù)組（customers），而且還包含分頁信息，以及一個含有分頁鏈接的_links的對象。在實現(xiàn)Data Service的時候，如果這些返回內(nèi)容不能滿足需求，開發(fā)人員完全可以自定義。

舉個例子，假設我們希望在返回內(nèi)容中包含當前的服務器時間，其開發(fā)過程如下。

首先，新建一個繼承于Apworks.Integration.AspNetCore.DataServices.DataServiceHalBuildConfiguration的類型，取名為ServerTimeHalBuildConfiguration：

using? Apworks.Integration.AspNetCore.DataServices; using? Hal.Builders; using? Microsoft.AspNetCore.Http.Extensions; using? System; namespace? CustomerService { ???? public? class? ServerTimeHalBuildConfiguration : DataServiceHalBuildConfiguration ???? { ???????? protected? override? void? RegisterHalBuilderFactoryForGetAll() ???????? { ???????????? this .RegisterHalBuilderFactory( "*.Get(int, int)" , context => ???????????????? new? ResourceBuilder() ???????????????????? .WithState( new? { ServerTime = DateTime.UtcNow }) ???????????????????? .AddSelfLink().WithLinkItem(context.HttpContext.Request.GetEncodedUrl()) ???????????????????? .AddEmbedded(context.ControllerAction.ControllerName.ToLower()) ???????????????????????? .Resource( new? ResourceBuilder().WithState(context.State)) ???????????? ); ???????? } ???? } }

然后，回到Startup.cs文件中的ConfigureServices方法，在DataServiceConfigurationOptions的構造函數(shù)參數(shù)中，指定halBuildConfigurationFactory參數(shù)，代碼如下：

public? void? ConfigureServices(IServiceCollection services) { ???? // Add framework services. ???? services.AddMvc(); ???? services.AddApworks() ???????? .WithDataServiceSupport( new? DataServiceConfigurationOptions ???????????? ( new? MongoRepositoryContext ???????????????? ( new? MongoRepositorySettings( "localhost" , "customer-service" )), ???????????????? halBuildConfigurationFactory: _ => new? ServerTimeHalBuildConfiguration())) ???????? .Configure(); }

OK，任務完成，測試一下。打開MINGW，執(zhí)行curl?http://localhost:2238/api/customers?-i命令，看看結果如何：

可以看到，我們已經(jīng)在返回的HAL結果中加入了服務器的UTC時間，同時，還是保留了_self的鏈接。不過，分頁的鏈接沒有包含在內(nèi)，這是因為我們通過override重寫了RegisterHalBuilderFactoryForGetAll方法。你可以參考Apworks框架源代碼中的Apworks.Integration.AspNetCore.DataServices.DataServiceHalBuildConfiguration類來了解如何將分頁的鏈接加入到HAL的返回結果中。

大致對上面的代碼做一些介紹：

DataServiceHalBuildConfiguration及其子類主要負責對HAL Resource Builder（Builder模式，[GoF95]）的定義和注冊，它能將某一個HAL的資源構造器（Resource Builder）關聯(lián)到某一個ASP.NET Core Web API的控制器上

RegisterHalBuilderFactory方法會根據(jù)其第一個參數(shù)（ControllerActionSignature）確定一個ASP.NET Core Web API的Controller Action方法，并將第二個參數(shù)所指定的HAL Resource Builder工廠方法委托（Delegate）注冊到由ControllerActionSignature指定的Controller Action方法上

在HalResultFilterAttribute類中，當Controller Action執(zhí)行完成時，會根據(jù)所注冊的Hal Resource Builder Factory來獲取最終的HAL內(nèi)容（通過調(diào)用ResourceBuilder的Build方法），然后將產(chǎn)生的HAL以application/hal+json格式返回

在SupportsHalAttribute類中會根據(jù)是否存在一個IHalBuildConfiguration的Service注冊，來確定是否使用HAL的返回內(nèi)容

DataServiceController類已經(jīng)使用了SupportsHalAttribute，因此，它具有使用HAL功能的能力，那么繼承于它的控制器都會被應用SupportsHalAttribute特性，因此，你開發(fā)的數(shù)據(jù)服務控制器（Data Service Controller）無需關注HAL的功能

最后，在DataServiceConfigurationOptions類的構造函數(shù)中，通過指定useHalSupport以及halBuildConfigurationFactory兩個參數(shù)，來決定是否需要HAL的支持，以及如何產(chǎn)生HAL的結果

事實上，如果你不打算使用DataServiceController來快速開發(fā)數(shù)據(jù)服務，而是希望使用傳統(tǒng)的方式自己開發(fā)自己的RESTful服務，你完全可以使用Apworks.Integration.AspNetCore.Hal命名空間下的類型來使得你的RESTful服務也支持流行的HAL，而且開發(fā)過程非常方便。由此可見，Apworks.Integration.AspNetCore中對HAL的支持并不是專為框架本身的數(shù)據(jù)服務開發(fā)而設計的，它能夠應用于普通的RESTful服務的開發(fā)，數(shù)據(jù)服務只不過是HAL的一個客戶而已。

總結

本文介紹了Apworks數(shù)據(jù)服務開發(fā)中對HAL的支持，可以看到，Apworks框架的設計是：

靈活的：通過不同的配置信息來干預數(shù)據(jù)服務的執(zhí)行過程，同時還支持自定義擴展來定制自己的數(shù)據(jù)服務

通用的：組件的設計盡可能達到通用性，比如HAL的機制，它不僅僅是Apworks數(shù)據(jù)服務的“特供”，它可以被應用在任何由ASP.NET Core Web API所開發(fā)的RESTful服務上

開發(fā)體驗友好的：簡單的API定義使得應用程序快速開發(fā)成為可能，Fluent Interface API（流暢接口）的設計，使得開發(fā)者能夠用更為自然的語言來完成所需要的功能操作，大大提升開發(fā)生產(chǎn)率。在Apworks的整個框架中，會更多地引入流暢接口以便保持較好的開發(fā)者體驗

就HAL這部分來說，它利用了ASP.NET Core中的ResultFilter以及Filter Factory，建議大家可以了解一下HAL以及Data Service的相關代碼，來熟悉ASP.NET Core中Filter的相關內(nèi)容。

值得一提的是，Apworks中對HAL的支持使用的正是我自己開發(fā)的HAL庫，這套庫也是開源的，開源地址是：https://github.com/daxnet/hal，它是為數(shù)較少的完整實現(xiàn)HAL規(guī)范，并支持.NET Core的HAL開發(fā)庫，同樣，它支持流暢接口。

下一講打算介紹一下如何在Apworks數(shù)據(jù)服務中使用Entity Framework Core。敬請期待。

原文地址：http://www.cnblogs.com/daxnet/p/6701119.html

---

.NET社區(qū)新聞，深度好文，微信中搜索dotNET跨平臺或掃描二維碼關注

總結

以上是生活随笔為你收集整理的在ASP.NET Core中使用Apworks开发数据服务：对HAL的支持的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。