此版本仍在开发中,尚不被认为是稳定的。对于最新的稳定版本,请使用 Spring Data REST 4.5.3spring-doc.cadn.net.cn

元数据

本节详细介绍了基于 Spring Data REST 的应用程序提供的各种形式的元数据。spring-doc.cadn.net.cn

应用程序级配置文件语义 (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-doc.cadn.net.cn

Spring Data REST 应用程序的根目录是一个配置文件链接。假设您有一个同时包含两者的应用程序persons和相关addresses,根 文档如下:spring-doc.cadn.net.cn

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

RFC 6906 中定义的配置文件链接是包含应用程序级详细信息的位置。ALPS 草案规范旨在定义特定的配置文件格式, 我们将在本节后面探讨这一点。spring-doc.cadn.net.cn

如果您导航到配置文件链接,则位于localhost:8080/profile,您会看到类似于以下内容的内容:spring-doc.cadn.net.cn

{
  "_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资源,你会看到类似于以下示例的内容:spring-doc.cadn.net.cn

{
  "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 namepersons,这表示(因为它是复数)POST 应该应用于整个集合,而不是单个集合person.
4 typeUNSAFE,因为此作可能会更改系统的状态。
5 rt#person-representation,这表示返回的资源类型将为Person资源。
此 JSON 文档的媒体类型为application/alps+json.这与之前的 JSON 文档不同,后者有 媒体类型为application/hal+json.这些格式是不同的,并受不同的规范约束。

您还可以找到一个profile集合中的链接_links检查集合资源时,如以下示例所示:spring-doc.cadn.net.cn

{
  "_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.spring-doc.cadn.net.cn

超媒体控制类型

ALPS 显示每个超媒体控件的类型。他们包括:spring-doc.cadn.net.cn

表 1.ALPS类型
类型 描述

语义spring-doc.cadn.net.cn

状态元素(例如HTML.SPAN,HTML.INPUT等)。spring-doc.cadn.net.cn

安全spring-doc.cadn.net.cn

触发安全幂等状态转换的超媒体控件 (例如GETHEAD).spring-doc.cadn.net.cn

幂等spring-doc.cadn.net.cn

触发不安全的幂等状态转换的超媒体控件 (例如PUTDELETE).spring-doc.cadn.net.cn

不安全的spring-doc.cadn.net.cn

触发不安全、非幂等状态转换的超媒体控件 (例如POST).spring-doc.cadn.net.cn

在前面显示的表示部分中,来自应用程序的数据位被标记为SEMANTIC.这address田 是一个涉及保险箱的链接GET检索。因此,它被标记为SAFE.超媒体作本身映射到类型上 如上表所示。spring-doc.cadn.net.cn

带投影的 ALPS

如果定义任何投影,它们也会列在 ALPS 元数据中。假设我们还定义了inlineAddressnoAddresses他们 将出现在相关作中。(参见 “投影”,了解这两个投影的定义和讨论。也就是说,GET 将出现在整个集合的作中,而 GET 将出现在单个资源的作中。以下示例显示 的替代版本get-persons款:spring-doc.cadn.net.cn

...
  {
    "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,firstNamelastName. 在投影中呈现的关系会导致内联包含数据字段。
3 noAddresses提供包含firstNamelastName.

有了所有这些信息,客户端不仅可以推断出可用的 RESTful 转换,还可以在某种程度上推断出 与后端交互所需的数据元素。spring-doc.cadn.net.cn

向 ALPS 描述添加自定义详细信息

您可以创建显示在 ALPS 元数据中的自定义消息。为此,请创建rest-messages.properties如下:spring-doc.cadn.net.cn

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如下:spring-doc.cadn.net.cn

...
  {
    "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-doc.cadn.net.cn

Spring MVC(这是 Spring Data REST 应用程序的本质)支持语言环境,这意味着您可以捆绑多个 属性文件。

JSON 架构

JSON Schema 是 Spring Data REST 支持的另一种形式的元数据。根据他们的网站,JSON Schema 具有以下优点:spring-doc.cadn.net.cn

上一节所示,您可以通过从根 URI 导航到profile链接。spring-doc.cadn.net.cn

{
  "_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.spring-doc.cadn.net.cn

在这种情况下,如果您运行curl -H 'Accept:application/schema+json' localhost:8080/profile/persons,您将看到类似于以下内容的输出:spring-doc.cadn.net.cn

{
  "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 属性列表

如果您的资源具有指向其他资源的链接,则有更多详细信息。spring-doc.cadn.net.cn

您还可以找到一个profile集合中的链接_links检查集合资源时,如以下示例所示:spring-doc.cadn.net.cn

{
  "_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/schema+json,它呈现 JSON Schema 表示。spring-doc.cadn.net.cn