基于 springMVC 的 RESTful HTTP API 实践（服务端）

时间 2019-11-13

标签基于 springmvc restful http api 实践服务栏目 Spring 繁體版

原文原文链接

理解 REST

REST（Representational State Transfer）,中文翻译叫“表述性状态转移”。是 <span style="color:blue;font-size:15px;font-family:Microsoft YaHei;font-style:oblique;">Roy Thomas Fielding</span> 在他2000年的博士论文中提出的。它与传统的 SOAP Web 服务区别在于，REST关注的是要处理的数据，而 SOAP 主要关注行为和处理。要理解好 REST，根据其首字母拆分出的英文更容易理解。 **表述性（Representational）:**对于 REST 来讲，咱们网络上的一个个URI资源能够用各类形式来表述，例如：XML、JSON或者HTML等。 **状态（State）：**REST 更关注资源的状态而不是对资源采起的行为。 **转移（Transfer）：**在网络传输过程当中，REST 使资源以某种表述性形式从一个应用转移到另外一个应用（如从服务端转移到客户端）。html

具体来讲，REST 中存在行为，它的行为是经过 HTTP 表示操做的方法来定义的即：GET、POST、PUT、DELETE、PATCH；GET用来获取资源，POST用来新建资源（也能够用于更新资源），PUT用来更新资源，DELETE用来删除资源，PATCH用来更新资源。基于 REST 这样的观点，咱们须要避免使用 REST服务、REST Web服务这样的称呼，这些称呼多少都带有一些强调行为的味道。java

使用 RESTful 架构设计使用误区

**RESTful 架构：**是基于 REST 思想的时下比较流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，因此正获得愈来愈多网站的采用。git

在没有足够了解 REST 的时候，咱们很容易错误的将其视为 “基于 URL 的 Web 服务”，即将 REST 和 SOAP 同样，是一种远程过程调用（remote procedure call，RPC）的机制。可是 REST 和 RPC 几乎没有任何关系，RPC 是面向服务的，而 REST 是面向资源的，强调描述应用程序的事物和名词。这样很容易致使的一个结果是咱们在设计 RESTful API 时，在 URI 中使用动词。例如：GET /user/getUser/123。正确写法应该是 GET /user/123。

使用 springMVC 支持 RESTful

在 spring 3.0 之后，spring 这对 springMVC 的一些加强功能对 RESTful 提供了良好的支持。在4.0后的版本中，spring 支持一下方式建立 REST 资源：github

控制器能够处理全部的 HTTP 方法，包含几个主要的 REST 方法：GET、POST、PUT、DELETE、PATCH；
借助 @PathVariable 注解，控制器可以处理参数化的 URL（将变量输入做为 URL 的一部分）；
借助 spring 的视图解析器，资源可以以多种方式进行表述，包括将模型数据渲染为 XML、JSON、Atom、已经 RSS 的 View 实现；
可使用 ContentNegotiatingViewResolver 来选择最适合客户端的表述；
借助 @ResponseBody 注解和各类 HttpMethodConverter 实现，可以替换基于视图的渲染方式；
相似地，@RequestBody 注解以及 HttpMethodConverter 实现能够将传入的 HTTP 数据转化为传入控制器处理方法的 Java 对象；
借助 RestTemplate ，spring 应用可以方便地使用 REST 资源。

建立 RESTful 控制器

代码清单web

package com.pengdh.controller;

import com.pengdh.entity.EmployeeEntity;
import com.pengdh.service.EmployeeService;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

/**
 * @author pengdh
 * @date: 2017-06-27 0:08
 */
@Controller
@RequestMapping("/employs")
public class EmployeeController {

  @Autowired
  private EmployeeService empService;

  @RequestMapping(value = "/list", method = RequestMethod.GET, produces = { "application/json;charset=UTF-8" })
  public List<EmployeeEntity> employs(Integer offset,Integer limit) {
    offset = offset == null ? 0 : offset;
    limit = limit == null ? 20 : limit;
    return empService.queryEmployList(offset,limit);
  }
}

代码的大体过程是当客户端发起对 "/employs" 的 GET 请求时，将调用服务端的 employs 方法，服务端经过注入的 EmployeeService 获取到一个 EmployeeEntity 列表，并将列表以 JSON 的表述形式返回给客户端。spring

须要注意的是这里控制器自己并不关心资源如何表述。控制器以 Java 对象的方式来处理资源。控制器完成了它的工做之后，资源才会被转化成为适合客户端的形式。spring 提供了两种方法将资源的 java 表述形式转化为发送给客户端的表述形式：
内容协商（Content negotiation）：选择一个视图，它可以将模型渲染为呈现给客户端的表述形式；
消息转化器（Message conversion）：经过一个消息转换器将控制器所返回的对象转换为呈现给客户端的表述形式。

对于上述两种方式，第一种方式是经过 ContentNegotiatingViewResolver 做为 ViewResolver 的实现，主要是用于将资源渲染人类用户接口所须要的视图模型，如：HTML、JSP等也能够渲染。也能够针对不是人类客户端产生 JSON 或 XML，可是效果不是很理想，每每会产生一些不是客户端所须要的预期结果。如：客户端但愿获得的响应多是：{"name":"zhangs","age":"20"}。而模型是 key-value 组成的 map ，可能最终的响应是这样的：{"user":{"name":"zhangs","age":"20"}}。基于内容协商的这些限制，这里咱们主要讨论第二种方式：使用 Spring 的消息转换功能来生成资源表述。json

使用 HTTP 消息转换器

这是一种更为直接的方式，消息转换器可以将控制器产生的数据转换为服务于客户端的表述形式。经常使用的一些消息转换器如：Jackson 的 MappingJacksonHttpMessageConverter 实现 JSON 消息和 Java 对象的互相转换； JAXB 库的 Jaxb2RootElementHttpMessageConverter 实现 XML 和 Java 对象的相互转换等。api

经过 @ResponseBody 注解实现响应体中返回资源状态。

正常状况下，当处理方法返回 Java 对象时，这个对象会放在模型中并在视图中渲染使用。可是，若是使用了消息转换功能的话，咱们须要告诉 Spring 跳过正常的模型/视图流程，并使用消息转换器。实现这种方式最简单的方式是在控制器的方法上添加 @ResponseBody 注解。如：restful

@RequestMapping(value = "/list", method = RequestMethod.GET, produces = { "application/json;charset=UTF-8" })
  @ResponseBody
  public List<EmployeeEntity> employs(Integer offset,Integer limit) {
    offset = offset == null ? 0 : offset;
    limit = limit == null ? 20 : limit;
    return empService.queryEmployList(offset,limit);
  }

这里 @ResponseBody 注解会告知 Spring 将 List<EmployeeEntity> 转换成 JSON 这样的表述形式做为资源发送给客户端。网络

使用 @RequestBody 注解实如今请求体中接收资源状态

使用 @RequestBody 注解能够告知 Spring 查找一个消息转换器，未来自客户端的资源表述转换为对象。如：

@RequestMapping(value = "/save", method = RequestMethod.POST, produces = { "application/json;charset=UTF-8" })
  public int saveEmploy(@RequestBody EmployeeEntity employeeEntity) {
    return empService.save(employeeEntity);
  }

使用 @RestController 注解为控制器默认设置消息转换

Spring 4.0 引入了 @RestController 注解，在控制器是用 @RestController 代替 @Controller 的话，Spring 将会为该控制器的全部处理方法应用消息转换功能。咱们没必要在每一个方法都添加 @ResponseBody 注解了。如：

package com.pengdh.controller;

import com.pengdh.entity.EmployeeEntity;
import com.pengdh.service.EmployeeService;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author pengdh
 * @date: 2017-06-27 0:08
 */
@RestController
@RequestMapping("/employs")
public class EmployeeController {

  @Autowired
  private EmployeeService empService;

  @RequestMapping(value = "/list", method = RequestMethod.GET, produces = { "application/json;charset=UTF-8" })
  public List<EmployeeEntity> employs(Integer offset,Integer limit) {
    offset = offset == null ? 0 : offset;
    limit = limit == null ? 20 : limit;
    return empService.queryEmployList(offset,limit);
  }

  @RequestMapping(value = "/save", method = RequestMethod.POST, produces = { "application/json;charset=UTF-8" })
  public int saveEmploy(@RequestBody EmployeeEntity employeeEntity) {
    return empService.save(employeeEntity);
  }
}

为客户端提供其余元数据

使用 ResponseEntity 提供更多响应相关的元数据

能够利用 ResponseEntity 给客户端返回状态码、设置响应头信息等，如给客户端提供返回码:

@RequestMapping(value = "/{id}", method = RequestMethod.GET, produces = { "application/json;charset=UTF-8" })
  public ResponseEntity<EmployeeEntity> employById(@PathVariable long id) {
    HttpStatus status = null;
    EmployeeEntity employeeEntity = empService.selectById(id);
    if (employeeEntity != null) {
      status = HttpStatus.OK;
    } else {
      status = HttpStatus.NOT_FOUND;
    }
    return new ResponseEntity<EmployeeEntity>(employeeEntity, status);
  }

若是没有 if 判断，当根据 id 找不到对应的信息的时候，返回给客户端的状态码是默认的 HttpStatus.OK；当加上了判断条件后若是没有相应的信息返回则设置返回状态码为 HttpStatus.NOT_FOUND，最后经过 new 一个 ResponseEntity 会将查询信息和状态码一块儿返回到客户端。

另外，ResponseEntity 还包含有 @ResponseBody 的语义，上面示例中并无使用 @ResponseBody 注解，可是 ResponseEntity 的负载部分一样能够渲染到响应体中。

使用控制器异常处理器 @ExceptionHandler 处理异常信息

@ExceptionHandler 能够用到控制器的方法中，处理特定的异常：

建立响应包装类 ResponseResult

package com.pengdh.dto;

import java.io.Serializable;
import org.springframework.http.HttpStatus;

/**
 * 响应结果封装类
 *
 * @author pengdh
 * @date: 2017-06-29 0:34
 */
public class ResponseResult<T> implements Serializable {

  private static final long serialVersionUID = -3371934618173052904L;
  private int code;
  private String desc;
  private T data;

  public ResponseResult() {
  }

  public ResponseResult(int code, String desc) {
    this.code = code;
    this.desc = desc;
  }

  public ResponseResult(int code, T data) {
    this.code = code;
    this.data = data;
  }

  public int getCode() {
    return code;
  }

  public void setCode(HttpStatus code) {
    this.code = code;
  }

  public String getDesc() {
    return desc;
  }

  public void setDesc(String desc) {
    this.desc = desc;
  }

  public T getData() {
    return data;
  }

  public void setData(T data) {
    this.data = data;
  }

  @Override
  public String toString() {
    return "ResponseResult{" +
        "code=" + code +
        ", desc='" + desc + '\'' +
        ", data=" + data +
        '}';
  }
}

建立一个异常类 ResourceNotFound

package com.pengdh.exception;

/**
 * 资源未找到异常
 *
 * @author pengdh
 * @date: 2017-06-29 0:55
 */
public class ResourceNotFound extends RuntimeException {

  private static final long serialVersionUID = 4880328265878141724L;

  public ResourceNotFound() {
    super();
  }

  public ResourceNotFound(String message) {
    super(message);
  }

  public ResourceNotFound(String message, Throwable cause) {
    super(message, cause);
  }
}

控制器 EmployeeController

package com.pengdh.controller;

import com.pengdh.dto.ResponseResult;
import com.pengdh.entity.EmployeeEntity;
import com.pengdh.exception.ResourceNotFound;
import com.pengdh.service.EmployeeService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author pengdh
 * @date: 2017-06-27 0:08
 */
@RestController
@RequestMapping("/employs")
public class EmployeeController {

  @Autowired
  private EmployeeService empService;

  @RequestMapping(value = "/{id}", method = RequestMethod.GET, produces = { "application/json;charset=UTF-8" })
  public ResponseResult<EmployeeEntity> employById(@PathVariable long id) {
    ResponseResult<EmployeeEntity> result = new ResponseResult<EmployeeEntity>();
    HttpStatus status = null;
    EmployeeEntity employeeEntity = empService.selectById(id);
    if (employeeEntity == null) {
      throw new ResourceNotFound(String.valueOf(id));
    }
    result.setCode(HttpStatus.OK);
    result.setData(employeeEntity);
    return result;
  }

  @ExceptionHandler(ResourceNotFound.class)
  public ResponseResult<Object> handlerException(ResourceNotFound e) {
    ResponseResult<Object> result = new ResponseResult<Object>();
    result.setCode(HttpStatus.NOT_FOUND);
    result.setDesc(e.getMessage());
    return result;
  }
}

从控制器代码能够看出，咱们经过 @ExceptionHandler 能将控制器的方法的异常场景分出来单独处理。