ETags for REST with Spring – 使用Spring的REST的ETags

最后修改: 2013年 1月 11日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

This article will focus on working with ETags in Spring, integration testing of the REST API and consumption scenarios with curl.

本文将重点介绍在Spring中使用ETags、REST API的集成测试以及使用curl的消费情景。

2. REST and ETags

2.REST和ETags

From the official Spring documentation on ETag support:

来自Spring官方文档的ETag支持。

An ETag (entity tag) is an HTTP response header returned by an HTTP/1.1 compliant web server used to determine change in content at a given URL.

We can use ETags for two things – caching and conditional requests. The ETag value can be thought of as a hash computed out of the bytes of the Response body. Because the service likely uses a cryptographic hash function, even the smallest modification of the body will drastically change the output and thus the value of the ETag. This is only true for strong ETags – the protocol does provide a weak Etag as well.

我们可以将ETag用于两件事–缓存和条件请求。ETag值可以被认为是一个从Response主体的字节中计算出来的哈希值。因为服务可能使用了一个加密的哈希函数，即使对主体进行最小的修改，也会极大地改变输出，从而改变ETag的值。这只适用于强ETag – 该协议确实提供了一个弱ETag，以及。

Using an If-* header turns a standard GET request into a conditional GET. The two If-* headers that are using with ETags are “If-None-Match” and “If-Match” – each with its own semantics as discussed later in this article.

使用If-*头将一个标准的GET请求变成一个有条件的GET。与ETags一起使用的两个If-*头是”If-None-Match“和”If-Match” – 正如本文后面所讨论的，每个都有自己的语义。

3. Client-Server Communication With curl

3.使用curl的客户-服务器通信

We can break down a simple Client-Server communication involving ETags into the steps:

我们可以将涉及ETags的简单的客户-服务器通信分解为以下步骤。

First, the Client makes a REST API call – the Response includes the ETag header that will be stored for further use:

首先，客户端进行REST API调用–响应包括ETag头，该头将被储存起来供进一步使用。

curl -H "Accept: application/json" -i http://localhost:8080/spring-boot-rest/foos/1
HTTP/1.1 200 OK
ETag: "f88dd058fe004909615a64f01be66a7"
Content-Type: application/json;charset=UTF-8
Content-Length: 52

For the next request, the Client will include the If-None-Match request header with the ETag value from the previous step. If the Resource hasn’t changed on the Server, the Response will contain no body and a status code of 304 – Not Modified:

对于下一个请求，客户端将包括If-None-Match请求头和上一步的ETag值。如果资源在服务器上没有改变，响应将包含没有正文和状态代码304 – 未修改。

curl -H "Accept: application/json" -H 'If-None-Match: "f88dd058fe004909615a64f01be66a7"'
 -i http://localhost:8080/spring-boot-rest/foos/1
HTTP/1.1 304 Not Modified
ETag: "f88dd058fe004909615a64f01be66a7"

Now, before retrieving the Resource again, let’s change it by performing an update:

现在，在再次检索资源之前，让我们通过执行更新来改变它。

curl -H "Content-Type: application/json" -i 
  -X PUT --data '{ "id":1, "name":"Transformers2"}' 
    http://localhost:8080/spring-boot-rest/foos/1
HTTP/1.1 200 OK
ETag: "d41d8cd98f00b204e9800998ecf8427e" 
Content-Length: 0

Finally, we send out the last request to retrieve the Foo again. Keep in mind that we’ve updated it since the last time we requested it, so the previous ETag value should no longer work. The response will contain the new data and a new ETag which, again, can be stored for further use:

最后，我们发出最后一个请求，再次检索Foo。请记住，自从我们上次请求后，我们已经更新了它，所以以前的ETag值应该不再有效。响应将包含新的数据和一个新的ETag，这个ETag同样可以被存储起来，以便进一步使用。

curl -H "Accept: application/json" -H 'If-None-Match: "f88dd058fe004909615a64f01be66a7"' -i 
  http://localhost:8080/spring-boot-rest/foos/1
HTTP/1.1 200 OK
ETag: "03cb37ca667706c68c0aad4cb04c3a211"
Content-Type: application/json;charset=UTF-8
Content-Length: 56

And there you have it – ETags in the wild and saving bandwidth.

你有了它–ETags在野外和节省带宽。

4. ETag Support in Spring

4.Spring中的ETag支持

On to the Spring support: using ETag in Spring is extremely easy to set up and completely transparent for the application. We can enable the support by adding a simple Filter in the web.xml:

关于Spring的支持：在Spring中使用ETag是非常容易设置的，对应用程序来说完全透明。我们可以通过在web.xml中添加一个简单的Filter来启用该支持。

<filter>
   <filter-name>etagFilter</filter-name>
   <filter-class>org.springframework.web.filter.ShallowEtagHeaderFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>etagFilter</filter-name>
   <url-pattern>/foos/*</url-pattern>
</filter-mapping>

We’re mapping the filter on the same URI pattern as the RESTful API itself. The filter itself is the standard implementation of ETag functionality since Spring 3.0.

我们将过滤器映射到与RESTful API本身相同的URI模式上。过滤器本身是Spring 3.0以来ETag功能的标准实现。

The implementation is a shallow one – the application calculates the ETag based on the response, which will save bandwidth but not server performance.

该实现是浅层的–应用程序根据响应计算ETag，这将节省带宽，但不能节省服务器性能。

So, a request that will benefit from the ETag support will still be processed as a standard request, consume any resource that it would normally consume (database connections, etc) and only before having its response returned back to the client will the ETag support kick in.

因此，一个将受益于ETag支持的请求仍将作为一个标准请求被处理，消耗它通常会消耗的任何资源（数据库连接等），只有在将其响应返回给客户端之前，ETag支持才会启动。

At that point the ETag will be calculated out of the Response body and set on the Resource itself; also, if the If-None-Match header was set on the Request, it will be handled as well.

在这一点上，ETag将从响应体中计算出来，并设置在资源本身上；另外，如果If-None-Match头被设置在请求上，它也将被处理。

A deeper implementation of the ETag mechanism could potentially provide much greater benefits – such as serving some requests from the cache and not having to perform the computation at all – but the implementation would most definitely not be as simple, nor as pluggable as the shallow approach described here.

更深层次的ETag机制的实现有可能提供更大的好处–比如从缓存中提供一些请求，而根本不需要进行计算–但这种实现肯定不会像这里描述的浅层方法那样简单，也不会有可插拔性。

4.1. Java Based Configuration

4.1.基于Java的配置

Let’s see how the Java-based configuration would look like by declaring a ShallowEtagHeaderFilter bean in our Spring context:

让我们看看在Spring上下文中声明一个ShallowEtagHeaderFilterbean，基于Java的配置会是怎样的。

@Bean
public ShallowEtagHeaderFilter shallowEtagHeaderFilter() {
    return new ShallowEtagHeaderFilter();
}

Keep in mind that if we need to provide further filter configurations, we can instead declare a FilterRegistrationBean instance:

请记住，如果我们需要提供进一步的过滤器配置，我们可以转而声明一个FilterRegistrationBean实例。

@Bean
public FilterRegistrationBean<ShallowEtagHeaderFilter> shallowEtagHeaderFilter() {
    FilterRegistrationBean<ShallowEtagHeaderFilter> filterRegistrationBean
      = new FilterRegistrationBean<>( new ShallowEtagHeaderFilter());
    filterRegistrationBean.addUrlPatterns("/foos/*");
    filterRegistrationBean.setName("etagFilter");
    return filterRegistrationBean;
}

Finally, if we’re not using Spring Boot we can set up the filter using the AbstractAnnotationConfigDispatcherServletInitializer‘s getServletFilters method.

最后，如果我们不使用Spring Boot，我们可以使用AbstractAnnotationConfigDispatcherServletInitializer的getServletFilters方法设置过滤器。

4.2. Using the ResponseEntity’s eTag() Method

4.2.使用 ResponseEntity 的 eTag() 方法

This method was introduced in Spring framework 4.1, and we can use it to control the ETag value that a single endpoint retrieves.

这个方法是在Spring框架4.1中引入的，我们可以用它来控制单个端点检索的ETag值。

For instance, imagine we’re using versioned entities as an Optimist Locking mechanism to access our database information.

例如，设想我们使用版本化实体作为Optimist Locking机制来访问我们的数据库信息。

We can use the version itself as the ETag to indicate if the entity has been modified:

我们可以用版本本身作为ETag来表示该实体是否被修改过。

@GetMapping(value = "/{id}/custom-etag")
public ResponseEntity<Foo>
  findByIdWithCustomEtag(@PathVariable("id") final Long id) {

    // ...Foo foo = ...

    return ResponseEntity.ok()
      .eTag(Long.toString(foo.getVersion()))
      .body(foo);
}

The service will retrieve the corresponding 304-Not Modified state if the request’s conditional header matches the caching data.

如果请求的条件头与缓存数据匹配，服务将检索相应的304-Not Modified状态。

5. Testing ETags

5.测试ETags

Let’s start simple – we need to verify that the response of a simple request retrieving a single Resource will actually return the “ETag” header:

让我们从简单的开始–我们需要验证检索单个资源的简单请求的响应实际上将返回”ETag”/em>头：。

@Test
public void givenResourceExists_whenRetrievingResource_thenEtagIsAlsoReturned() {
    // Given
    String uriOfResource = createAsUri();

    // When
    Response findOneResponse = RestAssured.given().
      header("Accept", "application/json").get(uriOfResource);

    // Then
    assertNotNull(findOneResponse.getHeader("ETag"));
}

Next, we verify the happy path of the ETag behavior. If the Request to retrieve the Resource from the server uses the correct ETag value, then the server doesn’t retrieve the Resource:

接下来，我们验证ETag行为的快乐路径。如果从服务器检索Resource的请求使用了正确的ETag值，那么服务器就不会检索到该资源。

@Test
public void givenResourceWasRetrieved_whenRetrievingAgainWithEtag_thenNotModifiedReturned() {
    // Given
    String uriOfResource = createAsUri();
    Response findOneResponse = RestAssured.given().
      header("Accept", "application/json").get(uriOfResource);
    String etagValue = findOneResponse.getHeader(HttpHeaders.ETAG);

    // When
    Response secondFindOneResponse= RestAssured.given().
      header("Accept", "application/json").headers("If-None-Match", etagValue)
      .get(uriOfResource);

    // Then
    assertTrue(secondFindOneResponse.getStatusCode() == 304);
}

Step by step:

一步一步来。

  • we create and retrieve a Resource, storing the ETag value
  • send a new retrieve request, this time with the “If-None-Match” header specifying the ETag value previously stored
  • on this second request, the server simply returns a 304 Not Modified, since the Resource itself has indeed not beeing modified between the two retrieval operations

Finally, we verify the case where the Resource is changed between the first and the second retrieval requests:

最后，我们验证了资源在第一次和第二次检索请求之间被改变的情况：。

@Test
public void 
  givenResourceWasRetrievedThenModified_whenRetrievingAgainWithEtag_thenResourceIsReturned() {
    // Given
    String uriOfResource = createAsUri();
    Response findOneResponse = RestAssured.given().
      header("Accept", "application/json").get(uriOfResource);
    String etagValue = findOneResponse.getHeader(HttpHeaders.ETAG);

    existingResource.setName(randomAlphabetic(6));
    update(existingResource);

    // When
    Response secondFindOneResponse= RestAssured.given().
      header("Accept", "application/json").headers("If-None-Match", etagValue)
      .get(uriOfResource);

    // Then
    assertTrue(secondFindOneResponse.getStatusCode() == 200);
}

Step by step:

一步一步来。

  • we first create and retrieve a Resource – and store the ETag value for further use
  • then we update the same Resource
  • send a new GET request, this time with the “If-None-Match” header specifying the ETag that we previously stored
  • on this second request, the server will return a 200 OK along with the full Resource, since the ETag value is no longer correct, as we updated the Resource in the meantime

Finally, the last test – which is not going to work because the functionality has not yet been implemented in Spring – is the support for the If-Match HTTP header:

最后，最后一个测试–因为该功能已经尚未在Spring中实现–是对If-Match HTTP头的支持：。

@Test
public void givenResourceExists_whenRetrievedWithIfMatchIncorrectEtag_then412IsReceived() {
    // Given
    T existingResource = getApi().create(createNewEntity());

    // When
    String uriOfResource = baseUri + "/" + existingResource.getId();
    Response findOneResponse = RestAssured.given().header("Accept", "application/json").
      headers("If-Match", randomAlphabetic(8)).get(uriOfResource);

    // Then
    assertTrue(findOneResponse.getStatusCode() == 412);
}

Step by step:

一步一步来。

  • we create a Resource
  • then retrieve it using the “If-Match” header specifying an incorrect ETag value – this is a conditional GET request
  • the server should return a 412 Precondition Failed

6. ETags Are Big

6.ETags是大的

We have only used ETags for read operations. An RFC exists trying to clarify how implementations should deal with ETags on write operations – this is not standard, but is an interesting read.

我们只在读操作中使用ETags。有一个RFC存在，试图澄清实施者应如何处理写操作中的ETags – 这不是标准，但却是一个有趣的阅读。

There are of course other possible uses of the ETag mechanism, such as for an Optimistic Locking Mechanism as well as dealing with the related “Lost Update Problem”.

当然，ETag机制还有其他可能的用途，例如用于优化锁定机制以及处理相关的 “丢失更新问题”。

There are also several known potential pitfalls and caveats to be aware of when using ETags.

还有几个已知的潜在的陷阱和注意事项，使用ETags时要注意。

7. Conclusion

7.结论

This article only scratched the surface with what’s possible with Spring and ETags.

这篇文章只是对Spring和ETags的可能性做了一个简单的介绍。

For a full implementation of an ETag enabled RESTful service, along with integration tests verifying the ETag behavior, check out the GitHub project.

有关启用 ETag 的 RESTful 服务的完整实现，以及验证 ETag 行为的集成测试，请查看 GitHub 项目。