基于请求头的条件操作
本节展示 Spring Data REST 如何使用标准 HTTP 头来提升性能、对操作进行条件化,并助力构建更完善的前端。
ETag、If-Match 与 If-None-Match 请求头
ETag 请求头提供了一种为资源打标签的方式。这既可以防止客户端相互覆盖,也可以减少不必要的调用。
请看以下示例:
示例 1. 一个带有版本号的 POJO
class Sample {
@Version Long version; 1
Sample(Long version) {
this.version = version;
}
}
@Version注解(如果您使用 Spring Data JPA,则用 JPA 的那个;对于所有其他模块,则用 Spring Data 的org.springframework.data.annotation.Version)将该字段标记为版本标记。
上例中的 POJO 在由 Spring Data REST 作为 REST 资源提供时,会带有一个 ETag 请求头,其值为版本字段的值。
如果我们提供如下所示的 If-Match 请求头,就可以对该资源进行条件化的 PUT、PATCH 或 DELETE:
curl -v -X PATCH -H 'If-Match: <value of previous ETag>' ...
只有当资源当前的 ETag 状态与 If-Match 请求头匹配时,才会执行该操作。这一保护机制可防止客户端相互覆盖。两个不同的客户端可以获取同一资源并拥有相同的 ETag。如果其中一个客户端更新了该资源,它会在响应中得到一个新的 ETag。但第一个客户端仍持有旧的请求头。如果该客户端带着 If-Match 请求头尝试更新,更新会失败,因为二者不再匹配。取而代之的是,该客户端会收到一条 HTTP 412 Precondition Failed 响应消息。随后客户端可以按需进行追平。
「version(版本)」一词在不同数据存储中可能具有不同的语义,甚至在您的应用内部也可能具有不同的语义。Spring Data REST 实际上会委托给数据存储的元模型来判断某个字段是否带版本;如果带版本,则仅在 ETag 元素匹配时才允许执行所列的更新。
If-None-Match 请求头提供了另一种方式。If-None-Match 不是用于条件化更新,而是用于条件化查询。请看以下示例:
curl -v -H 'If-None-Match: <value of previous etag>' ...
上述命令(默认情况下)会执行 GET。Spring Data REST 在执行 GET 时会检查 If-None-Match 请求头。如果该请求头与 ETag 匹配,它就断定没有任何变化,于是不发送资源副本,而是返回 HTTP 304 Not Modified 状态码。从语义上讲,它的含义是:「如果所提供的请求头值与服务端版本不匹配,则发送整个资源;否则,不发送任何内容。」
这个 POJO 来自一个基于 ETag 的单元测试,因此它不像应用代码中那样带有 @Entity(JPA)或 @Document(MongoDB)注解。它仅关注带 @Version 的字段如何产生 ETag 请求头。
If-Modified-Since 请求头
If-Modified-Since 请求头提供了一种方式,用于检查资源自上次请求以来是否被更新,从而让应用避免重复发送相同的数据。请看以下示例:
示例 2. 在领域类型中捕获的最后修改日期
@Document
public class Receipt {
public @Id String id;
public @Version Long version;
public @LastModifiedDate Date date; 1
public String saleItem;
public BigDecimal amount;
}
Spring Data Commons 的
@LastModifiedDate注解允许以多种格式捕获此信息(JodaTime 的DateTime、旧版 Java 的Date和Calendar、JDK8 日期/时间类型,以及long/Long)。
借助上例中的日期字段,Spring Data REST 会返回一个类似如下的 Last-Modified 请求头:
Last-Modified: Wed, 24 Jun 2015 20:28:15 GMT
该值可以被捕获并用于后续查询,以在数据未被更新时避免重复获取相同数据,如下例所示:
curl -H "If-Modified-Since: Wed, 24 Jun 2015 20:28:15 GMT" ...
使用上述命令,您是在要求仅当资源自指定时间以来发生变化时才获取它。如果发生了变化,您会得到一个修订后的 Last-Modified 请求头,用于更新客户端。如果没有变化,您会收到 HTTP 304 Not Modified 状态码。
该请求头的格式完全可以直接在后续查询中回传使用。
切勿将请求头值与不同的查询混用。后果可能是灾难性的。仅当您请求完全相同的 URI 和参数时,才使用这些请求头值。
构建更高效的前端
ETag 元素与 If-Match 和 If-None-Match 请求头相结合,可让您构建一个对用户流量套餐和移动设备电池续航更友好的前端。为此:
-
识别需要锁定的实体,并添加版本属性。
HTML5 很好地支持
data-*属性,因此将版本存储在 DOM 中(例如放在data-etag属性里)。 -
识别那些最能从跟踪最新更新中受益的条目。在获取这些资源时,将
Last-Modified值存储在 DOM 中(或许放在data-last-modified里)。 -
在获取资源时,还要将
selfURI 嵌入您的 DOM 节点中(或许放在data-uri或data-self里),以便轻松返回该资源。 -
调整
PUT/PATCH/DELETE操作以使用If-Match,并处理 HTTP412 Precondition Failed状态码。 -
调整
GET操作以使用If-None-Match和If-Modified-Since,并处理 HTTP304 Not Modified状态码。
通过将 ETag 元素和 Last-Modified 值嵌入您的 DOM 中(对于原生移动应用,或许放在别处),您就可以避免反复获取相同内容,从而减少流量和电量消耗。您还可以避免与其他客户端发生冲突,并在需要协调差异时收到提醒。
以这种方式,只需对前端稍作调整并做一些实体级别的修改,后端就能提供具有时效性的详细信息,供您在构建对客户友好的客户端时加以利用。