48.3. 微调应用程序的响应

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

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

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

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

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

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

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

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

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

有关 Apache CXF ResponseBuilderIml 类的更多信息，请参阅 ResponseBuilderImpl Javadoc。

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

成功处理请求时，应用需要发送响应来确认请求已实现。该响应可能包含实体。

成功完成响应时最常见的响应是 OK。OK 响应通常包含一个与请求对应的实体。Response 类有一个超载的 ok （） 方法，将响应状态设置为 200，并将提供的实体添加到括起的响应构建器中。ok （） 方法有五个版本。最常用的变体有：

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

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 状态的响应的示例。

import javax.ws.rs.core.Response;

return Response.noContent().build();

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

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

import javax.ws.rs.core.Response;

return Response.notModified().build();

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

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

import javax.ws.rs.core.Response;

return Response.serverError().build();

响应 类方法为常见情况创建响应提供了简短的剪切。当您需要处理更复杂的情况，如指定缓存控制指令、添加自定义 HTTP 标头或发送由 Response 类处理的状态时，您需要使用 ResponseBuilder 类方法在使用 build （） 方法生成响应前填充响应。

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

利用 ResponseBuilder 类的 header （） 方法，将自定义标头添加到响应中。header （） 方法采用两个参数：

您可以通过重复调用 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();

利用 ResponseBuilder 类的 cookie （） 方法，将自定义标头添加到响应中。cookie （） 方法采用一个或多个 Cookie。每个 Cookie 存储在 javax.ws.rs.core.NewCookie 对象中。最容易使用的 NewCookie 类的 contructors 取两个参数：

您可以通过重复调用 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();

当您要返回 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();