Java RESTful Web Service实战（第2版） 2.1 统一接口

<b>2.1　统一接口</b>

rest服务和rpc服务在接口定义上的区别是：rest使用http协议的通用方法作为统一接口的标准词汇，rest服务所提供的方法信息都在http方法里，而rpc服务所提供的方法信息在soap/http信封里（其封装的格式通常是http或soap），每一个rpc式的web服务都会公布一套符合自己商业逻辑的方法词汇。

阅读指南

本节示例源代码地址：https://github.com/feuyeux/jax-rs2-guide-ii/tree/master/2.simple-service-3。

相关包：com.example.annotation.method。

每一种http请求方法都可以从安全性和幂等性两方面考虑，这对正确理解http请求方法和设计统一接口具有决定性的意义。换句话说，要定义严谨的rest统一接口，就需要真正理解http方法的安全性和幂等性。

安全性是指外系统对该接口的访问，不会使服务器端资源的状态发生改变；幂等性（idempotence）是指外系统对同一rest接口的多次访问，得到的资源状态是相同的。

这里讨论的安全性对应的英文是safety而不是security，系统安全请参考第10章。以下，将从rest统一接口的定义角度，逐个讲述http方法。

<b>2.1.1　get方法</b>

rest使用http的get方法获取服务提供的资源。get方法是只读的，那么它是幂等和安全的吗？答案马上揭晓。

1. 幂等性和安全性

http的get方法用于读取资源。get方法是幂等的，因为读取同一个资源，总是得到相同的数据。get方法也是安全的，因为读取资源不会对其状态做改动。jax-rs2定义了@get注解对资源方法定义，使得该方法用于处理get请求。

值得注意的是，虽然get方法的特性是幂等和安全的，但这不意味着任何一个定义为处理get请求的方法都是幂等和安全的。换句话说，设计不良的api有可能违背get的特性，将一个不该是get的方法定义为之。

举个例子，在系统b中设计一个rest的api，在客户端调用时读取系统a中x类型的数据，然后将a.x与系统b内的y类型数据做比较，如果两个集合的内容、最后更新时间上有不同，需要执行同步数据，即将a.x追加或者更新到b.y中。最后，将同步结果信息返回给向系统b发起请求的客户端，如图2-1所示。

图2-1　请求资源示意图

从图2-1左侧部分乍看上去，这是一个获取同步信息的api，因此这个api的设计应该使用get请求方法。但是，稍作分析后即可知道该场景并不具备使用get的基本条件。因为同步过程中对系统b内的资源有写操作的可能，因此不具备安全性；而写的内容又不是每次相同，因此不具有幂等性。所以，这个例子应该定义的正确的请求方法是post。

2. 资源方法命名

不妨一起探讨一下图2-1中的同步信息的api该如何命名？既然是同步功能，那就以sync一类的字根作为前缀，这样所有的同步api都具有相同的开头，字迹也很工整。遗憾的是，这样的设计并不符合rest风格。笔者的理解是，从字面上看有两个问题。第一，sync字根具有非名词性的含义，从roa角度上看，sync是rpc风格的命名：动词、自定义方法名称。第二，这样命名后，资源名称从一个主语变成了宾语，从roa角度上看，面向的不再是资源，而是要执行的动作。

因此，标准的命名方式应该是单数的同步操作以资源名称命名；批量的同步操作以资源名称的复数名称命名。比如这个api是用于同步设备的，那么命名可以使用device和devices。如果担心与普通查询业务资源地址混淆，可以在资源路径中增加查询或者路径参数，比如device/id=1&amp;source=a_b、device/b/a/等。

3. 抽象层注解资源

jax-rs2的http方法注解可以定义在接口和pojo中，置于接口中的方法名更具抽象性和通用性。示例代码如下。

@path("book")

public interface bookresource {

//关注点1：get注解从抽象类上移到接口

@get

public string getweight();

}

public class ebookresourceimpl implements

bookresource {

//关注点2：实现类无须get注解

@override

public string getweight() {

return "150m";

    }

public class gettest extends jerseytest {

protected application configure() {

//关注点3：加载的是实现类而不是接口

return new resourceconfig(ebookresourceimpl.class);

@test

public void testget() {

response response = target("book").request().get();

assert.assertequals("150m",

response.readentity(string.class));

    }

在这段代码中，资源接口bookresource定义了一个get方法getweight()，这个方法使用了http方法注解@get，见关注点1。资源接口bookresource的实现类ebookresourceimpl实现了getweight()方法，但没有再次使用@get注解。也就是说，在接口中抽象地定义了资源的请求方法类型后，其全部实现类都无须再定义。这使得编码更整洁和抽象，见关注点2。最后，需要注意的是，在测试类gettest中注册的是实现类ebookresourceimpl类型而不是接口bookresource类型，见关注点3。

另外，我们一并介绍下head方法和options方法。head方法和get方法相似，只是服务器端的返回值不包括http实体。因此，head方法是安全的和幂等的。jax-rs2定义了@head注解来定义相关资源方法。options方法和get方法相似，是安全的和幂等的。options用于读取资源所支持的（allow）所有http请求方法。jax-rs2定义了@options注解来定义相关资源方法。

<b>2.1.2　put方法</b>

put方法是一种写操作的http请求。rest使用http的put方法更新或添加资源。下面讲解一下put方法的作用和操作时的媒体类型。

1. 更新资源

因为rest只是风格，不是技术规范或标准，所以有些实现rest的细节没有明确的定义，这对实践而言，不可避免会产生某些误解。比如在创建和更新某个资源的时候，开发者比较迷茫的是何时该用http的put方法，何时该使用post方法。为了解决这一问题，我们首先应该知道put方法的特性。put方法是幂等的，即多次插入或者更新同一份数据，在服务器端对资源状态所产生的改变是相同的。put方法不是安全的，有写动作的http方法都不是安全的。

我们知道，由于使用同一份数据向服务器请求更新某一资源，得到的结果应该总是相同的，因此对于更新操作，使用put是没有疑问的。可能读者会想到最后更新时间字段每次提交会不同，但那已经不是同一份数据了。

2. 添加资源

创建操作通常每次得到的结果是不同的，因为服务器端的业务层逻辑通常要求数据的主键字段要么来自于业务平台自增一个逻辑值，要么来自于数据库的主键自增。因此，相同的数据每一次提交到服务器端，都会为数据添加一个新的主键值，也就是创建一个主键值不同的新资源（如果没有业务或者外键冲突）。所以，创建操作通常应当设计为post方法的api。唯有一种场景应当使用put方法来设计api，即客户端在发起创建请求时，在同一份数据中总可以提供唯一的主键值，服务器不会对其进行修改，这样的创建请求确保了幂等性，不应再使用post方法。jax-rs2定义了@put注解来定义相关资源方法，示例代码如下。

//关注点1：put方法

@put

//关注点2：资源方法定义了produces注解和consumes注解

@produces(mediatype.text_plain)

@consumes(mediatype.application_xml)

public string newbook(book book);

public class puttest extends jerseytest {

public static atomiclong clientbooksequence = new atomiclong();

public void testnew() {

final book newbook = new book(clientbooksequence.incrementandget(),

"book-" + system.nanotime());

mediatype contenttypemediatype = mediatype.application_xml_type;

mediatype acceptmediatype = mediatype.text_plain_type;

final entity&lt;book&gt; bookentity = entity.entity(newbook,

contenttypemediatype);

final string lastupdate =

target("book").request(acceptmediatype)

.put(bookentity, string.class);

//关注点3：资源方法定义了produces注解和consumes注解

assert.assertnotnull(lastupdate);

logger.debug(lastupdate);

在这段代码中，资源接口bookresource使用@put注解定义了newbook()方法，即该方法用于处理相对资源路径为"book"的put请求，见关注点1。单元测试类puttest对其功能性进行了验证，对lastupdate使用非空断言，lastupdate是更新方法newbook()的返回实体的值，代表最后更新时间戳，见关注点3。我们注意到，newbook()方法上，同时定义了@produces(mediatype.text_plain)注解和@consumes(mediatype.application_xml)注解，见关注点2，下面我们来介绍一下与关注点2相关的媒体类型知识。

3. 媒体类型

put方法执行写操作的非安全的http方法，需要考虑请求实体媒体类型和响应实体媒体类型。请求实体媒体类型使用http头的content type定义，响应实体媒体类型使用http头的accept定义。

在服务器端，@consumes(mediatype.application_xml)定义了服务器端要消费的媒体类型，即消费客户端请求实体的媒体类型。@produces(mediatype.text_plain)定义了服务器端生产的媒体类型，即服务器产生的响应实体的媒体类型。客户端在提交非安全性http请求方法前，在entity类的实例中，定义该entity实例的媒体类型，即客户端请求实体的媒体类型。request方法用于定义可接受的http方法的返回媒体类型，即服务器的响应实体的媒体类型。

测试资源方法newbook()，将得到如下所示的请求头信息，从中可以看到请求媒体类型。

public final static string text_plain =

"text/plain";

public final static string application_xml

= "application/xml";

public final static mediatype

text_plain_type = new mediatype("text", "plain");

application_xml_type = new mediatype("application", "xml");

1 &gt; put http://localhost:9998/book

1 &gt; accept: text/plain

1 &gt; content-type: application/xml

在这段代码中，javax.ws.rs.core.mediatype类是jax-rs2提供的媒体类型定义类，其中定义了包括示例中使用的mediatype.text_plain，其值为"text/plain"。在mediatype类中，对应的响应实体媒体类型定义为accept: text/plain；mediatype.application_xml值为"application/xml"，对应的请求实体媒体类型定义为content-type: application/xml。

<b>2.1.3　delete方法</b>

delete方法是幂等的，即多次删除同一份数据（通常请求中传递的参数是数据的主键值），在服务器端产生的改变是相同的。jax-rs2定义了@delete注解来定义相关资源方法。下面来看看具体示例。

执行删除的资源方法，其返回值可以定义为void，即该方法没有返回值。之所以在删除资源的场景中可以采用这样的方式定义，是因为删除的前提是对该资源信息已经充分了解，没有必要再将其从服务器上传递回来，示例代码如下。

@delete

public void delete(@queryparam("bookid") final long bookid);

在这段代码中，无返回值的资源方法delete()返回的响应实体为空，http状态码为204。该定义可以参考jersey的源代码中的response类，示例代码如下。

package javax.ws.rs.core;

public abstract class response {

public interface statustype {

public enum status implements statustype {

no_content(204, "no content"),

接下来是删除资源方法的单元测试，示例代码如下。

public class deletetest extends jerseytest

{

final response response

=target("book").queryparam("bookid", "9527")

.request().delete();

int status = response.getstatus();

logger.debug(status);

assert.assertequals(response.status.no_content.getstatuscode(), status);

在这段代码中，对rest请求的测试断言不是针对删除资源的实体，而是响应中http状态码。也就是说，删除资源方法的返回值类型可以定义为void，业务逻辑更关注删除操作的结果状态。

<b>2.1.4　post方法</b>

post方法是一种写操作的http请求。rpc的所有写操作均使用post方法，而rest只使用http的post方法添加资源。

1. 既不幂等也不安全

定义为post的rest接口用于写数据，post方法的特性是既不幂等也不安全。由于请求会改变服务器端资源的状态，因此它是不是安全的；由于每次请求对服务器端资源状态的改变并不是相同的，因此它不是幂等的。

2. 两种分类

rest中使用的post可以称之为post（a），即用于创建、添加资源的http方法。这是相对于rpc式的web服务中对post的使用而言的。

在rpc中使用的post可以称之为post（p），即通过重载的post用于处理某种操作。服务器接收post（p）的请求后，不是直接处理post请求，由于真正的方法信息位于信封头或实体主体里，因此需要先解析出执行方法。

jax-rs2定义了@post注解来定义相关资源方法。示例代码如下。

//关注点1：post方法

@post

@produces(mediatype.application_xml)

public book createbook(book book);

public class posttest extends jerseytest {

public void testcreate() {

final book newbook = new book("book-" + system.nanotime());

mediatype acceptmediatype = mediatype.application_xml_type;

final book book

=target("book").request(acceptmediatype).post(bookentity,

 book.class);

//关注点2：测试post方法的断言

assert.assertnotnull(book.getbookid());

logger.debug("server id="+book.getbookid());

在这段代码中，资源接口bookresource定义了createbook()方法，该方法使用@post注解，表示该方法处理"book"路径下的post请求，见关注点1。在测试方法testcreate()中，关注请求结果实体的主键是否为空。这是因为在post请求提交的添加资源操作中，主键的设置是在服务器端完成的，因此客户端成功请求添加资源后，应关注服务器端返回的实体结果是否有主键信息，见关注点2。

到此，我们完成了对http的基本方法的讲述。除了http协议定义的标准方法，还存在来自其他协议中的http方法。接下来，我们一起探讨这些方法对rest服务的影响。

<b>2.1.5　webdav扩展方法</b>

webdav（web-based

distributed authoring and versioning，基于web的分布式创作与版本控制）是ietf的rfc4918规范（rfc2518规范的替代规范地址是http://tools.ietf.org/html/rfc4918），是对http1.1协议的一组扩展，该协议允许用户以协作方式编辑和管理远程web服务器上的文件。webdav在http方法的基础上，增加了如下方法（详见rfc4918第9章）。

propfind方法：用于从web资源中查询存储为xml格式的属性数据，或者重载为从一个远程系统中查询目录结构的数据。

proppatch方法：用于原子地更改和删除一个资源的多个属性。

mkcol方法：用于创建目录。

copy方法：用于将资源从一个uri资源地址复制到另一个uri资源地址。

move方法：用于将资源从一个uri资源地址移动到另一个uri资源地址。

lock 方法：用于锁定一个资源。webdav支持共享锁和独占锁。

unlock方法：用于解锁一个资源。

虽然webdav对http方法做出了功能性扩展，使之提供更强大服务，但是从roa角度讲，因为webdav在http标准方法的基础上增加了特殊的方法名称，webdav破坏了统一接口的原则。因此，对是否应该在rest式的web服务中支持webdav，业内的观点并不一致。

笔者的观点是如果遵从roa，那么就不使用http标准方法之外的方法。如果业务需求确实超出了标准方法所及，那么可以使用如下注解实现对webdav的支持。jax-rs2规范没有阐述对webdav提供支持的文字，但是jax-rs2定义了@httpmethod注解来定义相关的资源方法。在jersey应用中，可以使用@httpmethod注解定义http标准方法之外的方法名称来支持webdav，示例代码如下。

@target({elementtype.method})

@retention(retentionpolicy.runtime)

@httpmethod(value = "move")

@documented

public @interface move {

这段代码是对@move注解的定义，使用@httpmethod注解定义了名为move的http扩展方法。有了扩展方法注解，我们就可以在资源类中定义新的方法来支持扩展方法的请求了，示例代码如下。

@move

public boolean movebooks(books books);

在这段代码中，资源类bookresource定义了movebooks方法，该方法使用@move注解定义，表示用于处理"book"路径下的move请求。下面我们来看看相关的测试代码。

public class httpmethodtest extends

jerseytest {

resourceconfig resourceconfig = new

resourceconfig(ebookresourceimpl.class);

return resourceconfig;

protected void configureclient(clientconfig clientconfig) {

//关注点1：定义grizzly连接器

clientconfig.connectorprovider(new grizzlyconnectorprovider());

super.configureclient(clientconfig);

public void testwebdav() {

//关注点2：http move请求

final response response =

target("book").request().method("move");

boolean result = response.readentity(boolean.class);

//关注点3：move方法测试断言

assert.assertequals(boolean.true, result);

在这段代码中，测试方法testwebdav()在请求中定义了move请求，见关注点2；断言是针对move方法的返回值，见关注点3；可以看出，使用jersey实现对webdav的支持并不困难。

需要注意的是，jersey默认的连接器只支持http标准方法，因此要使用http的扩展方法就不能直接使用默认的连接器，这里使用了grizzly连接器。对应的代码行是：clientconfig.connectorprovider(new grizzlyconnectorprovider())，即为客户端配置实例提供grizzly连接器，见关注点1。这行代码是jersey2.5+后的写法，jersey2.5之前的写法是clientconfig.connector(new

grizzlyconnector(clientconfig))。从中可以看出，jersey在不断优化中，包括api。这一好处是活跃的社区为用户带来越来越便捷、高效的使用体验，缺点是破坏了向下兼容性。

到此，我们全面掌握了http方法在rest统一接口定义中的作用和实现。明白了rest接口该使用什么样的请求方法非常重要，这决定了其性质。但是这还不够，一个接口如何被请求唯一定位还需要深入掌握rest的资源定位。接下来一节将详述资源定位的细节。