48.3. 微调应用程序的响应

48.3.1. 构建响应的基础知识

概述

RESTful 服务通常需要更精确地控制返回到消费者的响应,而在资源方法返回普通 Java 结构时要被允许。JAX-RS Response 类允许资源方法对发送到消费者的返回状态进行一些控制,并在响应中指定 HTTP 消息标头和 Cookie。

响应 对象嵌套了代表消费者返回实体的对象。使用 Response Builder 类作为工厂来实例化响应对象。

ResponseBuilder 类也有许多用于操作响应的元数据的方法。例如,ResonseBuilder 类包含设置 HTTP 标头和缓存控制指令的方法。

响应和响应构建器之间的关系

响应 类具有受保护的构造器,因此无法直接实例化。它们使用由 Response 类包含的 ResponseBuilder 类创建。ResponseBuilder 类是所有信息的拥有者,它们将封装在从它创建的响应中。ResponseBuilder 类也具有负责设置消息上的 HTTP 标头属性的所有方法。

Response 类提供一些方法来轻松设置正确的响应代码并嵌套该实体。各个常见响应状态代码有方法。与包含实体正文或所需元数据的状态对应的方法包括允许直接将信息设置为关联的响应构建器的版本。

ResponseBuilder 类的 build() 方法会返回一个响应对象,其中包含调用方法时在响应构建器中存储的信息。返回响应对象后,响应构建器将返回到干净状态。

获取响应构建器

获取响应构建器的方法有两种:

  • 使用 Response 类的静态方法,如 使用 Response 类获取响应构建器 所示。

    使用 Response 类获取响应构建器

    import javax.ws.rs.core.Response;
    
    Response r = Response.ok().build();

    当获得响应构建器时,您无法访问多个步骤的实例。您必须将所有操作的字符串到一个方法调用中。

  • 使用 Apache CXF 特定 ResponseBuilderImpl 类。此类允许您直接与响应构建器一起使用。但是,它要求您手动设置所有响应构建器信息。

    例 48.1 “使用 ResponseBuilderImpl 类获取响应构建器” 显示如何使用 ResponseBuilderImpl 类重写 使用 Response 类获取响应构建器

    例 48.1. 使用 ResponseBuilderImpl 类获取响应构建器

    import javax.ws.rs.core.Response;
    import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;
    
    ResponseBuilderImpl builder = new ResponseBuilderImpl();
    builder.status(200);
    Response r = builder.build();
    注意

    您也可以简单地将 ResponseBuilder 返回的 Response Builder 方法分配到 ResponseBuilderImpl 对象。

更多信息

有关 Response 类的更多信息,请参阅 Response 类的 Javadoc

有关 ResponseBuilder 类的更多信息,请参阅 ResponseBuilder 类的 Javadoc

如需有关 Apache CXF ResponseBuilderIml 类的更多信息,请参阅 ResponseBuilderImpl Javadoc

48.3.2. 为常见用例创建响应

概述

Response 类提供了处理 RESTful 服务所需的更常见响应的快捷方式方法。这些方法使用提供的值或默认值来处理正确的标头。它们也会在适当时处理填充实体正文。

为成功请求创建响应

当成功处理请求时,应用程序需要发送响应,以确认请求已实现。该响应可以包含实体。

成功完成响应时最常见的响应是 OKOK 响应通常包含与请求对应的实体。Response 类具有超载的 ok() 方法,它将响应状态设置为 200,并将提供的实体添加到已括起的响应构建器中。ok() 方法有五个版本。最常用的变体是:

  • response .ok()- 创建状态 200 和空实体正文的响应。
  • response .ok(java.lang.Object 实体)- 创建具有 200 状态的响应,将提供的对象存储在响应实体正文中,并通过内省对象来确定实体媒体类型。

创建具有 200 响应的响应 演示了创建具有 OK 状态的响应的示例。

创建具有 200 响应的响应

import javax.ws.rs.core.Response;
import demo.jaxrs.server.Customer;
...

Customer customer = new Customer("Jane", 12);

return Response.ok(customer).build();

对于请求者不是预期实体正文,可能更适合发送 204 No Content 状态,而不是 200 OK 状态。Response.noContent() 方法将创建相应的响应对象。

创建具有 204 状态的响应 显示创建具有 204 状态的响应的示例。

创建具有 204 状态的响应

import javax.ws.rs.core.Response;

return Response.noContent().build();

创建重定向响应

Response 类提供了处理三种重定向响应状态的方法。

303 查看其他

当请求的资源需要永久将消费者重定向到新资源以处理请求时,303 See Other status 非常有用。

ResponseseeOther() 方法创建了具有 303 状态的响应,并将新资源 URI 放置到消息的 Location 字段中。seeOther() 方法采用单个参数,它将新 URI 指定为 java.net.URI 对象。

304 未修改

304 Not Modified 状态可用于不同的内容,具体取决于请求的性质。它可用于表示请求的资源自以前的 GET 请求以来没有变化。它还可用来表明修改资源的请求不会导致资源被改变。

Response classes notModified() 方法创建了具有 304 状态的响应,并设置 HTTP 消息修改的日期属性。notModified() 方法有三个版本:

  • notModified
  • notModifiedjavax.ws.rs.core.Entitytag
  • notModifiedjava.lang.Stringtag
307 临时重定向

当请求的资源需要将使用者定向到新资源时,307 临时重定向 状态非常有用,但希望消费者继续使用该资源来处理将来的请求。

ResponsetemporaryRedirect() 方法创建了具有 307 状态的响应,并将新资源 URI 放置到消息的 Location 字段中。temporaryRedirect() 方法采用单一参数,它将新 URI 指定为 java.net.URI 对象。

创建具有 304 状态的响应 显示创建具有 304 状态的响应的示例。

创建具有 304 状态的响应

import javax.ws.rs.core.Response;

return Response.notModified().build();

创建对信号错误的响应

Response 类提供了为两个基本处理错误创建响应的方法:

  • serverError- 创建状态为 500 Internal Server Error 的响应。
  • notAcceptablejava.util.List<javax.ws.rs.core.Variant>变体- 创建具有 406 无可接受的状态以及包含可接受资源类型列表的实体正文。

创建具有 500 个状态的响应 显示创建具有 500 状态的响应的示例。

创建具有 500 个状态的响应

import javax.ws.rs.core.Response;

return Response.serverError().build();

48.3.3. 处理更高级的响应

概述

响应 类方法提供了为常见情况创建响应的短差。当您需要解决更复杂的情况,如指定缓存控制指令、添加自定义 HTTP 标头或发送未由 Response 类处理的状态时,您需要使用 ResponseBuilder 类方法来填充响应,然后才能使用 build() 方法来生成响应对象。

“获取响应构建器”一节 所述,您可以使用 Apache CXF ResponseBuilderImpl 类来创建可直接操作的响应构建器实例。

添加自定义标头

使用 ResponseBuilder 类的 header() 方法将自定义标头添加到响应中。header() 方法采用两个参数:

  • name-a 指定标头名称的字符串
  • value- 包含标头中存储数据的 Java 对象

您可以通过重复调用 header() 方法在消息上设置多个标头。

在响应中添加标头 显示向响应中添加标头的代码。

在响应中添加标头

import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.header("username", "joe");
Response r = builder.build();

添加 Cookie

使用 ResponseBuilder 类的 cookie() 方法将自定义标头添加到响应中。Cookie() 方法采用一个或多个 cookies。每个 Cookie 都存储在 javax.ws.rs.core.NewCookie 对象中。NewCookie 类的最简单方法是使用两个参数:

  • name-a 指定 Cookie 名称的字符串
  • value-a 指定 Cookie 值的字符串

您可以通过重复调用 cookie() 方法来设置多个 Cookie。

在响应中添加 Cookie 显示将 Cookie 添加到响应中的代码。

在响应中添加 Cookie

import javax.ws.rs.core.Response;
import javax.ws.rs.core.NewCookie;

NewCookie cookie = new NewCookie("username", "joe");

Response r = Response.ok().cookie(cookie).build();

警告

使用 null 参数列表调用 cookie() 方法将擦除已经与响应关联的 cookie。

设置响应状态

当您想要返回除 Response 类帮助程序方法所支持的其中一个状态以外的状态时,您可以使用 ResponseBuilder 类的 status() 方法来设置响应的状态代码。status() 方法有两个变体。需要一个 int 来指定响应代码。另一个需要 Response.Status 对象来指定响应代码。

Response.Status 类是存储在 Response 类中的枚举者。它含有大多数定义的 HTTP 响应代码的条目。

在响应中添加标头 显示将响应状态设置为 404 Not Found 的代码。

在响应中添加标头

import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(404);
Response r = builder.build();

设置缓存控制指令

ResponseBuilder 类的 cacheControl() 方法允许您设置响应上的缓存控制标头。cacheControl() 方法采用 javax.ws.rs.CacheControl 对象,用于指定响应的缓存控制指令。

CacheControl 类具有与 HTTP 规范支持的所有缓存控制指令对应的方法。如果指令是简单的 on 或 off 值,则 setter 方法采用 布尔值。如果指令需要数字值,如 max-age 指令,则 setter 取一个 int 值。

在响应中添加标头 显示设置 no-store 缓存控制指令的代码。

在响应中添加标头

import javax.ws.rs.core.Response;
import javax.ws.rs.core.CacheControl;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

CacheControl cache = new CacheControl();
cache.setNoCache(true);

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.cacheControl(cache);
Response r = builder.build();