跳到主要内容
版本:5.1.1

元数据

Doubao 中英对照 Metadata

本节详细介绍基于 Spring Data REST 的应用程序所提供的各种形式的元数据。

应用级配置文件语义(ALPS)​

ALPS 是一种用于定义应用级语义简单描述的数据格式,其复杂度与 HTML 微格式相当。ALPS 文档可用作配置文件,以解释采用应用无关媒体类型(如 HTML、HAL、Collection+JSON、Siren 等)的文档的应用语义。这提高了配置文件文档跨媒体类型的可复用性。

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"
}
}
}

配置文件链接(如 RFC 6906 所定义)是一个用于包含应用级细节的位置。ALPS 草案规范旨在定义一种特定的配置文件格式,我们将在本节稍后探讨它。

如果您导航到 localhost:8080/profile 处的配置文件链接,会看到类似如下的内容:

{
"_links" : {
"self" : {
"href" : "http://localhost:8080/profile"
},
"persons" : {
"href" : "http://localhost:8080/profile/persons"
},
"addresses" : {
"href" : "http://localhost:8080/profile/addresses"
}
}
}
important

在根级别,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 表示。