HAL,全称为Hypertext Application Language,它是一种简单的数据格式,它能以一种简单、统一的形式,在API中引入超链接特性,使得API的可发现性(discoverable)更强,并具有自描述的特点。使用了HAL的API会更容易地被第三方开源库所调用,并且使用起来也很方便,开发者可以像处理普通JSON数据那样去处理API数据。有关HAL的更多信息,可以参考官方网站:http://stateless.co/hal_specification.html

例子

下面就是一个典型的使用HAL的API的响应数据。

{
"_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进行安装。

安装完成后,输入下面代码:

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)开发库的更多相关文章

  1. Hypertext Application Language(HAL)

    Hypertext Application Language(HAL) HAL,全称为Hypertext Application Language,它是一种简单的数据格式,它能以一种简单.统一的形式, ...

  2. 基于EF Core的Code First模式的DotNetCore快速开发框架

    前言 最近接了几个小单子,因为是小单子,项目规模都比较小,业务相对来说,也比较简单.所以在选择架构的时候,考虑到效率方面的因素,就采取了asp.net+entity framework中的code f ...

  3. 发布基于Orchard Core的友浩达科技官网

    2018.9.25 日深圳市友浩达科技有限公司发布基于Orchard Core开发的官网 http://www.weyhd.com/. 本篇文章为你介绍如何基于Orchard Core开发一个公司网站 ...

  4. 基于.NET Core 框架搭建WebApi项目

    一 什么是.NET Core? 随着2014年 Xamarin和微软发起.NET基金会,微软在2014年11月份开放.NET框架源代码.在.NET开源基金会的统一规划下诞生了.NET Core .也就 ...

  5. 将基于 .NET Framework 的 WPF 项目迁移到基于 .NET Core 3

    在 Connect(); 2018 大会上,微软发布了 .NET Core 3 Preview,以及基于 .NET Core 3 的 WPF:同时还发布了 Visual Studio 2019 预览版 ...

  6. 基于.net core 微服务的另类实现

    基于.net core 的微服务,网上很多介绍都是千篇一律基于类似webapi,通过http请求形式进行访问,但这并不符合大家使用习惯.如何像形如[ GetService<IOrderServi ...

  7. C# 嵌入dll 动软代码生成器基础使用 系统缓存全解析 .NET开发中的事务处理大比拼 C#之数据类型学习 【基于EF Core的Code First模式的DotNetCore快速开发框架】完成对DB First代码生成的支持 基于EF Core的Code First模式的DotNetCore快速开发框架 【懒人有道】在asp.net core中实现程序集注入

    C# 嵌入dll   在很多时候我们在生成C#exe文件时,如果在工程里调用了dll文件时,那么如果不加以处理的话在生成的exe文件运行时需要连同这个dll一起转移,相比于一个单独干净的exe,这种形 ...

  8. WPF基于.Net Core

    WPF基于.Net Core 因为最近.net core的热门,所以想实现一下.net core框架下的WPF项目,还是MVVM模式,下面就开始吧,简单做一个计算器吧. 使用VS2019作为开发工具 ...

  9. Azure Front Door(一)为基于.net core 开发的Azure App Service 提供流量转发

    一,引言 之前我们讲解到使用 Azure Traffic Manager.Azure LoadBalancer.Azure Application Gateway,作为项目的负载均衡器来分发流量,转发 ...

随机推荐

  1. GetEnvironmentVariable 获取常用系统变量(转)

    源:GetEnvironmentVariable 获取常用系统变量 //譬如 WINDIR 表示系统目录系统变量, 以这样获: var s:string; begin s:=GetEnvironmen ...

  2. IFieldEdit Interface 接口

    Description The IFieldEdit interface is used when creating new fields. You should not use it to modi ...

  3. Bessie Goes Moo

    Bessie Goes Moo 题目描述 Farmer John and Bessie the cow love to exchange math puzzles in their free time ...

  4. EHCache分布式缓存集群环境配置

    EHCache分布式缓存集群环境配置 ehcache提供三种网络连接策略来实现集群,rmi,jgroup还有jms.同时ehcache可以可以实现多播的方式实现集群,也可以手动指定集群主机序列实现集群 ...

  5. 微信小程序登录

    一. 小程序不支持cookie会话 1. 通过传递与检验3rd_session来保持会话 2. 3rd_session可以执行'`head -n 80 /dev/urandom | tr -dc A- ...

  6. 直流电机驱动PWM频率(转)

    源:直流电机驱动PWM频率 1.没有统一的标准,其实PWM的频率和你的电机感抗和你需要的速度响应时间有很大的关系.一般的电机用14K就足够了.当然自需要简单的调速可以随便选. 如果电机转速比较高,感抗 ...

  7. 安装pip工具

    Python 2.7.9+ and 3.4+ Good news! Python 3.4 (released March 2014) and Python 2.7.9 (released Decemb ...

  8. javascript中的字典

    1.概念 字典是一种以键值对的形式存储的数据结构,就系那个电话本中的名字和电话号码一样.要找到一个电话首先要找到名字,再根据名字找到电话号码.这里的键就是指用来查找的东西,值就是查找得到的结果. Ja ...

  9. python3自动下载优酷视频小程序

    我们一般都在优酷里看一些好玩的视频,有时候看到精彩的就想下载到本地保存起来留作纪念,在win下可以用维棠等软件下载,但苦了用linux的孩子们.尽管chrome和firefox的一些插件可以下载,但有 ...

  10. iOS 架构模式

    参考:http://www.cocoachina.com/ios/20160108/14916.html MVC , MVP , MVVM , VIPER