restful接口之Jersy开发

1. Restful风格的API介绍

Restful风格的API是一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

在Restful风格中，用户请求的url使用同一个url而用请求方式：get，post，delete，put...等方式对请求的处理方法进行区分，这样可以在前后台分离式的开发中使得前端开发人员不会对请求的资源地址产生混淆和大量的检查方法名的麻烦，形成一个统一的接口。

在Restful风格中，现有规定如下：

1 GET（SELECT）：从服务器查询，可以在服务器通过请求的参数区分查询的方式。

2 POST（CREATE）：在服务器新建一个资源，调用insert操作。

3 PUT（UPDATE）：在服务器更新资源，调用update操作。

4 PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。(目前jdk7未实现，tomcat7也不行)。

5 DELETE（DELETE）：从服务器删除资源，调用delete语句。

了解这个风格定义以后，我们举个例子：

如果当前url是 http://localhost:8080/User

那么用户只要请求这样同一个URL就可以实现不同的增删改查操作，例如

http://localhost:8080/User?_method=get&id=1001　　这样就可以通过get请求获取到数据库 user 表里面 id=1001 的用户信息

http://localhost:8080/User?_method=post&id=1001&name=zhangsan　　这样可以向数据库 user 表里面插入一条记录

http://localhost:8080/User?_method=put&id=1001&name=lisi　　这样可以将 user表里面 id=1001 的用户名改为lisi

http://localhost:8080/User?_method=delete&id=1001　　这样用于将数据库 user 表里面的id=1001 的信息删除

这样定义的规范我们就可以称之为restful风格的API接口，我们可以通过同一个url来实现各种操作。

2. Jersy介绍

Jersey RESTful WebService框架是一个开源的、产品级别的JAVA框架，支持JAX-RS API并且是一个JAX-RS(JSR 311和 JSR 339)的参考实现

Jersey不仅仅是一个JAX-RS的参考实现，Jersey提供自己的API，其API继承自JAX-RS，提供更多的特性和功能以进一步简化RESTful service和客户端的开发

Maven版本：3.1.0

Jersey版本：1.18

JDK版本：1.7.0_65

1. 常见注解

首先，需要将所有的 REST 请求发送到 Jersey 容器 —— 在应用程序的 web.xml 文件中定义 servlet 调度程序（参见清单 1）。除了声明 Jersey servlet 外，它还定义一个初始化参数，指示包含资源的 Java 包。

清单 1. 在 web.xml 文件中定义 Jersey servlet 调度程度

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

<servlet>

  <servlet-name>Jersey REST Service</servlet-name>

<servlet-class>

  com.sun.jersey.spi.container.servlet.ServletContainer

</servlet-class>

  <init-param>

    <param-name>com.sun.jersey.config.property.packages</param-name>

    <param-value>sample.hello.resources</param-value>

  </init-param>

  <load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

  <servlet-name>Jersey REST Service</servlet-name>

  <url-pattern>/rest/*</url-pattern>

</servlet-mapping>

现在您将编写一个名为 HelloResource 的资源，它接受 HTTP GET 并响应 “Hello Jersey”。

清单 2. sample.hello.resources 包中的 HelloResource

1

2

3

4

5

6

7

8

@Path("/hello")

public class HelloResource {

    @GET

    @Produces(MediaType.TEXT_PLAIN)

    public String sayHello() {

        return "Hello Jersey";

    }

}

该代码中有几个地方需要强调：

6 资源类（Resource Class）：注意，资源类是一个简单的 Java 对象 (POJO)，可以实现任何接口。这增加了许多好处，比如可重用性和简单。

7 注释（Annotation）：在 javax.ws.rs.* 中定义，是 JAX-RS (JSR 311) 规范的一部分。

8 @Path：定义资源基 URI。由上下文根和主机名组成，资源标识符类似于 http://localhost:8080/Jersey/rest/hello。

9 @GET：这意味着以下方法可以响应 HTTP GET 方法。

10 @Produces：以纯文本方式定义响应内容 MIME 类型。

测试 Hello 应用程序

要测试应用程序，可以打开您的浏览器并输入 URL http://<host>:<port>/<appctx>/rest/hello。您将看到响应 “Hello Jersey”。这非常简单，使用注释处理请求、响应和方法。

以下部分将涉及 JAX-RS 规范的必要部分，使用 Contacts 示例应用程序中的代码片段进行介绍。您可以在源代码包中找到这个高级样例的所有代码（参见 下载）。

资源

资源是组成 RESTful Web 服务的关键部分。您可以使用 HTTP 方法（如 GET、POST、PUT 和 DELETE）操作资源。应用程序中的所有内容都是资源：员工、联系人、组织等。在 JAX-RX 中，资源通过 POJO 实现，使用 @Path 注释组成其标识符。资源可以有子资源。在这种情况下，父资源是资源集合，子资源是成员资源。

在样例 Contacts 应用程序中，您将操作个人联系人和联系人集合。ContactsResource 是 /contacts URI 组成的集合资源，ContactResource 是 /contacts/{contactId} URI 组成的成员资源。下划线 JavaBean 是一个简单的 Contact 类，使用 id、名称和地址作为成员字段。参见清单 3 和清单 4 了解详情。您还可以从本文最后下载完整的代码包（参见 下载）。

清单 3. ContactsResource

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

@Path("/contacts")

public class ContactsResource {

    @Context

    UriInfo uriInfo;

    @Context

    Request request;

    @GET

    @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})

    public List<Contact> getContacts() {

        List<Contact> contacts = >new ArrayList<Contact>();

        contacts.addAll( ContactStore.getStore().values() );

        return contacts;

    }

 

@Path("{contact}")

    public ContactResource getContact(

            @PathParam("contact") String contact) {

        return new ContactResource(uriInfo, request, contact);

    }

}

有几个有趣的地方需要注意。

11 @Context： 使用该注释注入上下文对象，比如 Request、Response、UriInfo、ServletContext 等。

12 @Path("{contact}")：这是 @Path 注释，与根路径 “/contacts” 结合形成子资源的 URI。

13 @PathParam("contact")：该注释将参数注入方法参数的路径，在本例中就是联系人 id。其他可用的注释有 @FormParam、@QueryParam 等。

14 @Produces：响应支持多个 MIME 类型。在本例和上一个示例中，APPLICATION/XML 将是默认的 MIME 类型。

您也许还注意到了，GET 方法返回定制 Java 对象而不是 String（纯文本），正如上一个 Hello World 示例所示。 JAX-RS 规范要求实现支持多个表示形式类型，比如 InputStream、byte[]、JAXB 元素、JAXB 元素集合等等，以及将其序列化为 XML、JSON 或纯文本作为响应的能力。下文我将提供更多有关表示形式技术的信息，尤其是 JAXB 元素表示形式。

清单 4. ContactResource

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

public class ContactResource {

    @Context

    UriInfo uriInfo;

    @Context

    Request request;

    String contact;

     

    public ContactResource(UriInfo uriInfo, Request request,

            String contact) {

        this.uriInfo = uriInfo;

        this.request = request;

        this.contact = contact;

    }

     

    @GET

    @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})

    public Contact getContact() {

        Contact cont = ContactStore.getStore().get(contact);

        if(cont==null)

            throw new NotFoundException("No such Contact.");

        return cont;

    }

}

ContactResource 的代码简单明了。注意以下内容：

15 Representation Type Contact：Contact 是一个简单的 JavaBean，由 @XmlRootElement 注释，这使它可以表示为 XML 或 JSON。

16 ContactStore：这是基于 HashMap 的内存数据存储库，其实现对于本文不重要。

方法

HTTP 方法映射到资源的 CRUD（创建、读取、更新和删除） 操作。尽管您可以做一些小修改，比如让PUT 方法变成创建或更新，但基本的模式如下：

17 HTTP GET：获取/列出/检索单个资源或资源集合。

18 HTTP POST：新建资源。

19 HTTP PUT：更新现有资源或资源集合。

20 HTTP DELETE：删除资源或资源集合。

因为我已经介绍过 GET 方法，我将从 POST 开始说明。就像其他方法一样，我仍然使用 Contact 示例进行说明。

POST

通常通过填写表单创建新联系人。也就是说，HTML 表单将 POST 到服务器，服务器创建并维护新创建的联系人。清单 5 演示了该操作的服务器端逻辑。

清单 5. 接受表单提交（POST）并新建一个联系人

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

@POST

@Produces(MediaType.TEXT_HTML)

@Consumes(MediaType.APPLICATION_FORM_URLENCODED)

public void newContact(

        @FormParam("id") String id,

        @FormParam("name") String name,

        @Context HttpServletResponse servletResponse

) throws IOException {

    Contact c = new Contact(id,name,new ArrayList<Address>());

    ContactStore.getStore().put(id, c);

         

    URI uri = uriInfo.getAbsolutePathBuilder().path(id).build();

    Response.created(uri).build();

         

    servletResponse.sendRedirect("../pages/new_contact.html");

}

注意该示例的以下部分：

21 @Consumes：声明该方法使用 HTML FORM。

22 @FormParam：注入该方法的 HTML 属性确定的表单输入。

23 @Response.created(uri).build()： 构建新的 URI 用于新创建的联系人（/contacts/{id}）并设置响应代码（201/created）。您可以使用 http://localhost:8080/Jersey/rest/contacts/<id> 访问新联系人。

PUT

我使用 PUT 方法更新现有资源。但是，也可以通过更新实现，或者像清单 6 中的代码片段展示的那样创建一个资源。

清单 6. 接受 PUT 请求并创建或更新联系人

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

@PUT

@Consumes(MediaType.APPLICATION_XML)

public Response putContact(JAXBElement<Contact> jaxbContact) {

    Contact c = jaxbContact.getValue();

    return putAndGetResponse(c);

}

 

private Response putAndGetResponse(Contact c) {

    Response res;

    if(ContactStore.getStore().containsKey(c.getId())) {

        res = Response.noContent().build();

    } else {

        res = Response.created(uriInfo.getAbsolutePath()).build();

    }

    ContactStore.getStore().put(c.getId(), c);

    return res;

}

我还在本示例中包含了许多不同的概念，重点强调以下概念：

24 Consume XML：putContact() 方法接受 APPLICATION/XML 请求类型，而这种输入 XML 将使用 JAXB 绑定到 Contact 对象。您将在下一节中找到客户端代码。

25 空响应带有不同的状态码：PUT 请求的响应没有任何内容，但是有不同的状态码。如果数据存储库中存在联系人，我将更新该联系人并返回 204/no content。如果没有新联系人，我将创建一个并返回201/created。

DELETE

实现 DELETE 方法非常简单。示例请查看清单 7。

清单 7. 删除其 ID 确定的联系人

1

2

3

4

5

6

@DELETE

public void deleteContact() {

    Contact c = ContactStore.getStore().remove(contact);

    if(c==null)

        throw new NotFoundException("No such Contact.");

}

表示形式

在上一节中，我介绍了几个表示形式类型。现在我将简要浏览一遍并深入探讨 JAXB 表示形式。其他受支持的表示形式有 byte[]、InputStream、File 等。

26 String：纯文本。

27 Response：一般 HTTP 响应，包含带有不同响应代码的定制内容。

28 Void：带有 204/no content 状态码的空响应。

29 Resource Class：将流程委托给该资源类。

30 POJO：使用 @XmlRootElement 注释的 JavaBean，这让它成为一个 JAXB bean，可以绑定到 XML。

31 POJO 集合：JAXB bean 集合。

JAX-RS 支持使用 JAXB (Java API for XML Binding) 将 JavaBean 绑定到 XML 或 JSON，反之亦然。JavaBean 必须使用 @XmlRootElement 注释。清单 8 使用 Contact bean 作为示例。没有明确@XmlElement 注释的字段将包含一个名称与之相同的 XML 元素。清单 9 显示了用于一个 Contact bean 的序列化 XML 和 JSON 表示形式。联系人集合的表示形式与此相同，默认使用 <Contacts> 作为包装器元素。

清单 8. Contact bean

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

@XmlRootElement

public class Contact {

    private String id;

    private String name;

    private List<Address> addresses;

     

    public Contact() {}

     

    public Contact(String id, String name, List<Address> addresses) {

        this.id = id;

        this.name = name;

        this.addresses = addresses;

    }

 

    @XmlElement(name="address")

    public List<Address> getAddresses() {

        return addresses;

    }

 

    public void setAddresses(List<Address> addresses) {

        this.addresses = addresses;

    }

    // Omit other getters and setters

}

清单 9. 一个 Contact 的表示形式

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

XML representation:

<contact>

  <address>

    <city>Shanghai</city>

    <street>Long Hua Street</street>

  </address>

  <address>

    <city>Shanghai</city>

    <street>Dong Quan Street</street>

  </address>

  <id>huangyim</id>

    <name>Huang Yi Ming</name>

</contact>

 

 

JSON representation:

{"contact":[{"address":[{"city":"Shanghai","street":"Long

            Hua Street"},{"city":"Shanghai","street":"Dong Quan

            Street"}],"id":"huangyim","name":"Huang Yi Ming"}]}