2.4 构建Restful API

在目前的企业级开发中，从开发效率的角度来考虑，通常会选择使用前后端分离的开发形式。后端提供API接口，前端负责对接口进行调用，实现数据的返回和显示。前后端交互的一个重要工具是API，而Restful API是API的一种指导性设计思想，能让后端人员设计出更加优雅的API。本节介绍Restful API的概念和构建方式。

2.4.1 Restful架构风格

Restful架构风格是由Roy T. Fielding在其2000年的博士学位论文中首先提出的，它基于HTTP、URI、XML和JSON等标准与协议，是一种支持轻量级、跨平台和跨语言的架构设计，也是一种新的Web服务架构风格（或思想）。

HTTP是Restful架构风格的一个典型体现，因为Restful最关键的特点是资源、统一接口、URI和无状态。

根据Restful的定义，它有以下4个特点：

• 对网络上所有的资源都有一个资源标识符；
• 对资源的操作不会改变标识符；
• 同一资源有多种表现形式，如XML和JSON；
• 所有操作都是无状态的（Stateless）。

在Restful风格中，资源的具体操作类型用HTTP动词表示：

• GET（查询）：从服务器上取出资源（一项或多项）；
• POST（创建）：在服务器上新建一个资源；
• PUT（更新）：在服务器上更新全部的资源（客户端提供改变后的完整资源）；
• PATCH（更新）：更新部分资源（客户端提供需要改变的部分资源）；
• DELETE（删除）：从服务器上删除资源。

在Restful中，请求URI的格式有一套推荐的规则，例如，请求中无动词，均为名词。下面给出请求URI的示例，如表2.2所示。

表2.2 请求URI的示例

在表2.2所示的请求URI的示例中，user通过不同的请求方法向服务器发出不同的请求，继而得到不同的返回值，这很符合Restful的风格。

2.4.2 认识Jersey Restful

Jersey Restful框架是一个产品级别的Java开源框架，它是对JAX-RS（JSR 311和JSR 339）的参考实现。Jersey Restful提供特有的API，其API继承自JAX-RS。它还提供一些功能以进一步简化Restful项目的开发难度，同时可以和Spring Boot进行集成。

Jersey Restful的开发依赖于注解的使用，其作用类似于Spring MVC的注解。Jersey Restful常用的开发注解如表2.3所示。

表2.3 Jersey Restful常用的开发注解

2.4.3 实战：Jersey Restful与Spring Boot集成

2.4.2小节介绍了Jersey Restful，因为在项目开发中使用的是Spring Boot，所以需要把Jersey Restful整合到Spring Boot中。整合分为以下几个步骤：

（1）沿用本章前面创建的Spring Boot项目添加Jersey Restful的依赖。

在pom.xml中添加如下依赖代码：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jersey</artifactId>
</dependency>

这里添加依赖就体现了Spring Boot的便捷性，只需要添加上述依赖，就会自动将Jersey Restful加载到项目中。单击刚在pom.xml中添加的spring-boot-starter-jersey进入依赖详情，可以看到当前项目使用的Jersey版本为2.30.1。

（2）以Java Bean的方式添加Jersey配置文件。在Spring Boot的发展中，官方更加推荐开发者使用Java Bean的方式进行一些必要的配置，从而增加项目的可读性。在此建议读者使用Java Bean的配置方式。在com.onyx.springbootdemo包下新建配置类Jersey- Config，代码如下：

package com.onyx.springbootdemo;
import com.onyx.springbootdemo.resource.UserResource;
import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.stereotype.Component;
import javax.ws.rs.ApplicationPath;

@Component
@ApplicationPath("")
public class JerseyConfig extends ResourceConfig {
    public JerseyConfig(){
        //packages("com.onyx.springbootdemo.resource");
        register(UserResource.class);            //register添加资源类
    }
}

在此配置类中，添加UserResource作为对外提供的接口类，其功能类似于Spring MVC中Controller的功能。

（3）新建com.onyx.springbootdemo.resource包，并在此包下新建UserResource类，将其作为Web请求的入口，代码如下：

package com.onyx.springbootdemo.resource;

import org.springframework.stereotype.Component;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Component
@Path("/users")
public class UserResource {

   @GET
   @Produces(MediaType.APPLICATION_JSON)
   public String get() {
      return "hello cc， i miss you";
   }
}

添加一个/users的GET请求方法的返回，返回值为“hello cc，i miss you”。

（4）运行2.2节中SpringbootDemoApplication的main()方法来启动Spring Boot项目，打开浏览器，然后访问 http://localhost:8080/users ，从而得到返回结果，如图2.6所示。

图2.6 Jersey的访问结果

通过对上面的/users链接的访问，完成Spring Boot与Jersey Restful的整合。如果业务需要复杂的返回，则可以在application.properties中进行配置，之后就能愉快地开发业务代码了。 1p4dtydre2DrYlSpfrdKZmm5DKGs8koSay2qZ2DDV0zQdVExm/NhFXxoeZd9eLhq