|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Data REST 4.5.3！ |
元数据
本节详细介绍了基于 Spring Data REST 的应用程序提供的各种形式的元数据。
应用程序级配置文件语义 （ALPS）
ALPS 是一种数据格式，用于定义应用程序级语义的简单描述，其复杂性类似于 HTML 微格式。ALPS 文档可以用作配置文件，以解释与应用程序无关的媒体类型（如 HTML、HAL、Collection+JSON、Siren 等）的文档的应用程序语义。这提高了配置文件文档跨媒体类型的可重用性。
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"
} ]
}| 1 | 属性的详细列表Person资源，标识为#person-representation，列出名称
属性的。 |
| 2 | 支持的作。这表示如何创建一个新的Person. |
| 3 | 这name是persons，这表示（因为它是复数）POST 应该应用于整个集合，而不是单个集合person. |
| 4 | 这type是UNSAFE，因为此作可能会更改系统的状态。 |
| 5 | 这rt是#person-representation，这表示返回的资源类型将为Person资源。 |
此 JSON 文档的媒体类型为application/alps+json.这与之前的 JSON 文档不同，后者有
媒体类型为application/hal+json.这些格式是不同的，并受不同的规范约束。 |
您还可以找到一个profile集合中的链接_links检查集合资源时，如以下示例所示：
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons" (1)
},
... other links ...
"profile" : {
"href" : "http://localhost:8080/profile/persons" (2)
}
},
...
}| 1 | 此 HAL 文档表示Person收集。 |
| 2 | 它有一个指向元数据相同 URI 的配置文件链接。 |
同样，默认情况下，profile链接提供 ALPS。但是，如果您使用Accept页眉，它可以服务application/alps+json.
超媒体控制类型
ALPS 显示每个超媒体控件的类型。他们包括：
| 类型 | 描述 |
|---|---|
语义 |
状态元素（例如 |
安全 |
触发安全幂等状态转换的超媒体控件 （例如 |
幂等 |
触发不安全的幂等状态转换的超媒体控件 （例如 |
不安全的 |
触发不安全、非幂等状态转换的超媒体控件 （例如 |
在前面显示的表示部分中，来自应用程序的数据位被标记为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"
} ]
} ]
} ]
}
...| 1 | 新属性descriptors，出现，其中包含一个包含一个条目的数组，projection. |
| 2 | 在projection.descriptors，我们可以看到inLineAddress.它渲染address,firstName和lastName.
在投影中呈现的关系会导致内联包含数据字段。 |
| 3 | 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如下：
...
{
"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"
} ]
}
...| 1 | 的值rest.description.person映射到整个表示中。 |
| 2 | 的值rest.description.person.firstName映射到firstName属性。 |
| 3 | 的值rest.description.person.lastName映射到lastName属性。 |
| 4 | 的值rest.description.person.id映射到id属性，通常不显示的字段。 |
| 5 | 的值rest.description.person.address映射到address属性。 |
提供这些属性设置会导致每个字段都有一个额外的doc属性。
| Spring MVC（这是 Spring Data REST 应用程序的本质）支持语言环境，这意味着您可以捆绑多个 属性文件。 |
JSON 架构
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，您将看到类似于以下内容的输出：
{
"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#"
}| 1 | 导出的类型 |
| 2 | 属性列表 |
如果您的资源具有指向其他资源的链接，则有更多详细信息。
您还可以找到一个profile集合中的链接_links检查集合资源时，如以下示例所示：
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons" (1)
},
... other links ...
"profile" : {
"href" : "http://localhost:8080/profile/persons" (2)
}
},
...
}| 1 | 此 HAL 文档表示Person收集。 |
| 2 | 它有一个指向元数据相同 URI 的配置文件链接。 |