元数据
本节详细介绍基于 Spring Data REST 的应用程序所提供的各种形式的元数据。
应用级配置文件语义(ALPS)
ALPS 是一种用于定义应用级语义简单描述的数据格式,其复杂度与 HTML 微格式相当。ALPS 文档可用作配置文件,以解释采用应用无关媒体类型(如 HTML、HAL、Collection+JSON、Siren 等)的文档的应用语义。这提高了配置文件文档跨媒体类型的可复用性。
— M. Admundsen / L. Richardson / M. Foster
https://tools.ietf.org/html/draft-amundsen-richardson-foster-alps-00
Spring Data REST 为每个导出的仓库提供一份 ALPS 文档。它包含关于每个仓库的 RESTful 转换和属性两方面的信息。
Spring Data REST 应用的根处有一个配置文件链接。假设您有一个同时包含 persons 及其关联 addresses 的应用,根文档将如下所示:
{
"_links" : {
"persons" : {
"href" : "http://localhost:8080/persons"
},
"addresses" : {
"href" : "http://localhost:8080/addresses"
},
"profile" : {
"href" : "http://localhost:8080/profile"
}
}
}
如果您导航到 localhost:8080/profile 处的配置文件链接,会看到类似如下的内容:
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/profile"
},
"persons" : {
"href" : "http://localhost:8080/profile/persons"
},
"addresses" : {
"href" : "http://localhost:8080/profile/addresses"
}
}
}
在根级别,profile 是单个链接,无法提供多个应用配置文件。这就是为什么您必须导航到 /profile,才能找到指向每个资源元数据的链接。
如果您导航到 /profile/persons 并查看 Person 资源的配置文件数据,会看到类似以下示例的内容:
{
"version" : "1.0",
"descriptors" : [ {
"id" : "person-representation", 1
"descriptors" : [ {
"name" : "firstName",
"type" : "SEMANTIC"
}, {
"name" : "lastName",
"type" : "SEMANTIC"
}, {
"name" : "id",
"type" : "SEMANTIC"
}, {
"name" : "address",
"type" : "SAFE",
"rt" : "http://localhost:8080/profile/addresses#address"
} ]
}, {
"id" : "create-persons", 2
"name" : "persons", 3
"type" : "UNSAFE", 4
"rt" : "#person-representation" 5
}, {
"id" : "get-persons",
"name" : "persons",
"type" : "SAFE",
"rt" : "#person-representation"
}, {
"id" : "delete-person",
"name" : "person",
"type" : "IDEMPOTENT",
"rt" : "#person-representation"
}, {
"id" : "patch-person",
"name" : "person",
"type" : "UNSAFE",
"rt" : "#person-representation"
}, {
"id" : "update-person",
"name" : "person",
"type" : "IDEMPOTENT",
"rt" : "#person-representation"
}, {
"id" : "get-person",
"name" : "person",
"type" : "SAFE",
"rt" : "#person-representation"
} ]
}
以
#person-representation标识的Person资源属性详细列表,列出了各属性的名称。受支持的操作。这一项说明了如何创建新的
Person。name为persons,这表明(因为它是复数)应将 POST 应用于整个集合,而不是单个person。type为UNSAFE,因为该操作会改变系统状态。rt为#person-representation,这表明返回的资源类型将是Person资源。
此 JSON 文档的媒体类型为 application/alps+json。这不同于前一个媒体类型为 application/hal+json 的 JSON 文档。这两种格式不同,并且受不同规范约束。
如下例所示,当您查看集合资源时,还可以在 _links 集合中找到 profile 链接:
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons" 1
},
... other links ...
"profile" : {
"href" : "http://localhost:8080/profile/persons" 2
}
},
...
}
此 HAL 文档表示
Person集合。它有一个指向同一 URI 的 profile 链接,用于元数据。
同样,默认情况下 profile 链接提供 ALPS。但是,如果您使用 Accept 请求头,它也可以提供 application/alps+json。
超媒体控制类型
ALPS 为每个超媒体控制显示类型。它们包括:
表 1. ALPS 类型
| 类型 | 说明 |
|---|---|
| SEMANTIC | 一个状态元素(如 HTML.SPAN、HTML.INPUT 等)。 |
| SAFE | 触发安全、幂等状态转换的超媒体控制(如 GET 或 HEAD)。 |
| IDEMPOTENT | 触发不安全但幂等状态转换的超媒体控制(如 PUT 或 DELETE)。 |
| UNSAFE | 触发不安全、非幂等状态转换的超媒体控制(如 POST)。 |
在前面所示的表示部分中,来自应用的数据片段被标记为 SEMANTIC。address 字段是一个链接,检索它涉及一次安全的 GET。因此,它被标记为 SAFE。超媒体操作本身按上表所示映射到这些类型。
带投影的 ALPS
如果您定义了任何投影,它们也会列在 ALPS 元数据中。假设我们还定义了 inlineAddress 和 noAddresses,它们会出现在相关操作内部。(有关这两个投影的定义和讨论,请参阅「投影」。)也就是说,GET 会出现在整个集合的操作中,GET 会出现在单个资源的操作中。以下示例展示了 get-persons 子节的另一个版本:
...
{
"id" : "get-persons",
"name" : "persons",
"type" : "SAFE",
"rt" : "#person-representation",
"descriptors" : [ { 1
"name" : "projection",
"doc" : {
"value" : "The projection that shall be applied when rendering the response. Acceptable values available in nested descriptors.",
"format" : "TEXT"
},
"type" : "SEMANTIC",
"descriptors" : [ {
"name" : "inlineAddress", 2
"type" : "SEMANTIC",
"descriptors" : [ {
"name" : "address",
"type" : "SEMANTIC"
}, {
"name" : "firstName",
"type" : "SEMANTIC"
}, {
"name" : "lastName",
"type" : "SEMANTIC"
} ]
}, {
"name" : "noAddresses", 3
"type" : "SEMANTIC",
"descriptors" : [ {
"name" : "firstName",
"type" : "SEMANTIC"
}, {
"name" : "lastName",
"type" : "SEMANTIC"
} ]
} ]
} ]
}
...
出现了一个新属性
descriptors,其中包含一个数组,数组有一个条目projection。在
projection.descriptors内部,我们可以看到inLineAddress。它渲染address、firstName和lastName。在投影内部渲染的关系会将数据字段内联包含进来。noAddresses提供一个包含firstName和lastName的子集。
有了所有这些信息,客户端不仅可以推断出可用的 RESTful 转换,还能在一定程度上推断出与后端交互所需的数据元素。
向 ALPS 描述添加自定义详情
您可以创建出现在 ALPS 元数据中的自定义消息。为此,请创建 rest-messages.properties,如下所示:
rest.description.person=A collection of people
rest.description.person.id=primary key used internally to store a person (not for RESTful usage)
rest.description.person.firstName=Person's first name
rest.description.person.lastName=Person's last name
rest.description.person.address=Person's address
这些 rest.description.* 属性定义了为 Person 资源显示的详情。它们会改变 person-representation 的 ALPS 格式,如下所示:
...
{
"id" : "person-representation",
"doc" : {
"value" : "A collection of people", 1
"format" : "TEXT"
},
"descriptors" : [ {
"name" : "firstName",
"doc" : {
"value" : "Person's first name", 2
"format" : "TEXT"
},
"type" : "SEMANTIC"
}, {
"name" : "lastName",
"doc" : {
"value" : "Person's last name", 3
"format" : "TEXT"
},
"type" : "SEMANTIC"
}, {
"name" : "id",
"doc" : {
"value" : "primary key used internally to store a person (not for RESTful usage)", 4
"format" : "TEXT"
},
"type" : "SEMANTIC"
}, {
"name" : "address",
"doc" : {
"value" : "Person's address", 5
"format" : "TEXT"
},
"type" : "SAFE",
"rt" : "http://localhost:8080/profile/addresses#address"
} ]
}
...
rest.description.person的值映射到整个表示。rest.description.person.firstName的值映射到firstName属性。rest.description.person.lastName的值映射到lastName属性。rest.description.person.id的值映射到id属性,这是一个通常不显示的字段。rest.description.person.address的值映射到address属性。
提供这些属性设置会使每个字段都多出一个 doc 属性。
Spring MVC(它是 Spring Data REST 应用程序的核心)支持 locale,这意味着您可以打包多个带有不同消息的属性文件。
JSON Schema
JSON Schema 是 Spring Data REST 支持的另一种元数据形式。根据其网站,JSON Schema 具有以下优点:
-
描述您现有的数据格式
-
清晰、人类和机器可读的文档
-
完整的结构校验,可用于自动化测试和校验客户端提交的数据
如上一节所示,您可以通过从根 URI 导航到 profile 链接来访问这些数据。
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/profile"
},
"persons" : {
"href" : "http://localhost:8080/profile/persons"
},
"addresses" : {
"href" : "http://localhost:8080/profile/addresses"
}
}
}
这些链接与前面所示的相同。要获取 JSON Schema,您可以使用以下 Accept 头调用它们:application/schema+json。
在这种情况下,如果您运行 curl -H 'Accept:application/schema+json' [localhost:8080/profile/persons](http://localhost:8080/profile/persons),会看到类似如下的输出:
{
"title" : "org.springframework.data.rest.webmvc.jpa.Person", 1
"properties" : { 2
"firstName" : {
"readOnly" : false,
"type" : "string"
},
"lastName" : {
"readOnly" : false,
"type" : "string"
},
"siblings" : {
"readOnly" : false,
"type" : "string",
"format" : "uri"
},
"created" : {
"readOnly" : false,
"type" : "string",
"format" : "date-time"
},
"father" : {
"readOnly" : false,
"type" : "string",
"format" : "uri"
},
"weight" : {
"readOnly" : false,
"type" : "integer"
},
"height" : {
"readOnly" : false,
"type" : "integer"
}
},
"descriptors" : { },
"type" : "object",
"$schema" : "https://json-schema.org/draft-04/schema#"
}
被导出的类型
属性列表
如果您的资源包含指向其他资源的链接,则会有更多详情。
如下例所示,当您查看集合资源时,还可以在 _links 集合中找到 profile 链接:
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons" 1
},
... other links ...
"profile" : {
"href" : "http://localhost:8080/profile/persons" 2
}
},
...
}
此 HAL 文档表示
Person集合。它有一个指向同一 URI 的 profile 链接,用于元数据。
同样,profile 链接默认提供 ALPS。如果您为其提供 application/schema+json 的 Accept 请求头,它会渲染 JSON Schema 表示。