Spring Data Rest是运行在Spring Data之上的一套框架,能够非常方便的将Spring Data中的Repository映射成REST接口。其中有一些基本概念看起来有些陌生,在这里做出一些整理。
协议规范HATEOAS与数据格式HAL
Spring Data Rest采用了HATEOAS(Hypermedia as the Engine of Application State)协议规范。HATEOAS是一套REST接口的约束准则,它规定了访问数据的接口命名规范和返回数据应该包含的内容。
HAL(Hypertext Application Language)则规定了数据交换的格式,它规定了诸如General Resource(对应数据库一个单一实体对象),Embedded Resource(可以用于嵌入数据库外键关联的实体对象)和Collection(对应数据库的一个实体集合)等形式,为编写通用库提供了标准。
HATEOAS与HAL相辅相成,HATEOAS规定了程序应该如何“动态”转换,HAL规定了程序如何“静态”显示。
样例说明
HAL非常重要的两个概念是Resource(资源)和Link(链接),Resource就是我们想要获得的数据的内容,而Link则是获取特定数据的索引。
对于初次接触类似REST体系的人来说,可能最大的一道障碍就来自于对这两个概念的陌生。来自于Wikipedia的这段样例,可以帮助进行理解。
{
"_links": {
"self": {
"href": "http://example.com/api/book/hal-cookbook"
}
},
"id": "hal-cookbook",
"name": "HAL Cookbook"
}
这段代码展示了获取一个实体对象的返回数据。先看第一层,有id
name
与_links
三个键。在HAL中,所有以_
开头的键都可以理解为这个协议规定的必须存在的内容。在具体的框架上,这些内容是由框架生成的。所以,_links
键是这个协议的要求字段。从里层对象的键名不难猜出,_links.self.href
存储的,就是这个实体对象本身的link。通过访问这个link,可以得到现在呈现的这个数据,也就是resource。id
和name
是用户自己的数据,按照惯例,id
往往对应着数据库的主键。当然,主键可以是任意名字。
{
"_links": {
"self": {
"href": "http://example.com/api/book/hal-cookbook"
}
},
"_embedded": {
"author": {
"_links": {
"self": {
"href": "http://author-example.com"
}
},
"id": "shahadat",
"name": "Shahadat Hossain Khan"
}
},
"id": "hal-cookbook",
"name": "HAL Cookbook"
}
第二段代码展示了Embedded Resource的格式。与第一组不同的是,多了一个_embedded
字段,里面负载了author
这个数据。书和作者往往是一个外键的关系,这个代码就展示了外键会怎样被显示。事实上,在Spring Data Rest里面,外键默认只会展示对应对象的link,而不会显示完整的数据,这种情况下只会在_links
中多出一个author
字段处在与_links.self
平级的位置。如果想要一同返回完整的数据,数据的内容就会嵌入在_embedded
里面。
{
"_links": {
"self": {
"href": "http://example.com/api/book/hal-cookbook"
},
"next": {
"href": "http://example.com/api/book/hal-case-study"
},
"prev": {
"href": "http://example.com/api/book/json-and-beyond"
},
"first": {
"href": "http://example.com/api/book/catalog"
},
"last": {
"href": "http://example.com/api/book/upcoming-books"
}
},
"_embedded": {
"author": {
"_links": {
"self": {
"href": "http://author-example.com"
}
},
"id": "shahadat",
"name": "Shahadat Hossain Khan"
}
},
"id": "hal-cookbook",
"name": "HAL Cookbook"
}
第三段代码展示了带导航链接的集合资源。所谓导航链接,可以想象成数据库分页时候,前一页、后一页与第一页、最后一页的功能。对于Spring Data Rest,还会有包含页码页号每页记录数的page信息,帮助实现更加完备的分页功能。
- HATEOAS
- HAL