重学SpringBoot系列之RestFul接口及常用注解
Posted 大忽悠爱忽悠
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了重学SpringBoot系列之RestFul接口及常用注解相关的知识，希望对你有一定的参考价值。
重学SpringBoot系列之RestFul接口
RESTful接口与http协议状态表述
RestFul风格的好处
API（Application Programming Interface），顾名思义：是一组编程接口规范，客户端与服务端通过请求响应进行数据通信。REST（Representational State Transfer）表述性状态传递，决定了接口的形式与规则。RESTful是基于http方法的API设计风格，而不是一种新的技术.
- 看Url就知道要什么资源
- 看http method就知道针对资源干什么
- 看http status code就知道结果如何
对接口开发提供了一种可以广泛适用的规范，为前端后端交互减少了接口交流的口舌成本，是约定大于配置的体现。通过下面的设计，大家来理解一下这三句话.
当然也不是所有的接口，都能用REST的形式来表述。在实际工作中，灵活运用，我们用RESTful风格的目的是为大家提供统一标准，避免不必要的沟通成本的浪费，形成一种通用的风格。就好比大家都知道：伸出大拇指表示“你很棒“的意思，绝大部分人都明白，因为你了解了这种风格习惯。但是不排除有些地区伸出大拇指表示其他意思，就不适合使用！
RESTful API的设计风格
RESTful是面向资源的（名词）
REST 通过 URI 暴露资源时，会强调不要在 URI 中出现动词。比如：
用HTTP方法体现对资源的操作（动词）
- GET ： 获取、读取资源
- POST ： 添加资源
- PUT ： 修改资源
- DELETE ： 删除资源
实际上，这四个动词实际上就对应着增删改查四个操作，这就利用了HTTP动词来表示对资源的操作。
HTTP状态码
通过HTTP状态码体现动作的结果,不要自定义
200 OK
400 Bad Request
500 Internal Server Error
在 APP 与 API 的交互当中，其结果逃不出这三种状态：
- 所有事情都按预期正确执行完毕 - 成功
- APP 发生了一些错误 – 客户端错误（如：校验用户输入身份证，结果输入的是军官证，就是客户端输入错误）
- API 发生了一些错误 – 服务器端错误（各种编码bug或服务内部自己导致的异常）
这三种状态与上面的状态码是一一对应的。如果你觉得这三种状态，分类处理结果太宽泛，http-status code还有很多。建议还是要遵循KISS(Keep It Stupid and Simple)原则，上面的三种状态码完全可以覆盖99%以上的场景。这三个状态码大家都记得住，而且非常常用，多了就不一定了。
Get方法和查询参数不应该改变数据
改变数据的事交给POST、PUT、DELETE
使用复数名词
/dogs 而不是 /dog
复杂资源关系的表达
GET /cars/711/drivers/ 返回 使用过编号711汽车的所有司机
GET /cars/711/drivers/4 返回 使用过编号711汽车的4号司机
高级用法:HATEOAS
HATEOAS:Hypermedia as the Engine of Application State 超媒体作为应用状态的引擎。
RESTful API最好做到HATEOAS，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。
"link":
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API或者可以调用什么API了。
资源过滤、排序、选择和分页的表述
版本化你的API
强制性增加API版本声明，不要发布无版本的API。如：/api/v1/blog
面向扩展开放，面向修改关闭：也就是说一个版本的接口开发完成测试上线之后，我们一般不会对接口进行修改，如果有新的需求就开发新的接口进行功能扩展。这样做的目的是：当你的新接口上线后，不会影响使用老接口的用户。如果新接口目的是替换老接口，也不要在v1版本原接口上修改，而是开发v2版本接口，并声明v1接口废弃！
HTTP协议的四种传参方式
@RequestBody与@ResponseBody
//注意并不要求@RequestBody与@ResponseBody成对使用。
public @ResponseBody AjaxResponse saveArticle(@RequestBody ArticleVO article)
如上代码所示：
- @RequestBody修饰请求参数，注解用于接收HTTP的body，默认是使用JSON的格式
- @ResponseBody修饰返回值，注解用于在HTTP的body中携带响应数据，默认是使用JSON的格式。如果不加该注解，spring响应字符串类型，是跳转到模板页面或jsp页面的开发模式。说白了：加上这个注解你开发的是一个数据接口，不加这个注解你开发的是一个页面跳转控制器。
在使用@ResponseBody注解之后程序不会再走视图解析器，也就不再做html视图渲染，而是直接将对象以数据的形式（默认JSON）返回给请求发送者。那么我们有一个问题：如果我们想接收或XML数据该怎么办？我们想响应excel的数据格式该怎么办？我们后文来回答这个问题。
@RequestMapping注解
@RequestMapping注解是所有常用注解中，最有看点的一个注解，用于标注HTTP服务端点。它的很多属性对于丰富我们的应用开发方式方法，都有很重要的作用。如：
- value： 应用请求端点，最核心的属性，用于标志请求处理方法的唯一性；
- method： HTTP协议的method类型， 如：GET、POST、PUT、DELETE等；
- consumes： HTTP协议请求内容的数据类型（Content-Type），例如application/json,text/html;
- produces: HTTP协议响应内容的数据类型。下文会详细讲解。
- params： HTTP请求中必须包含某些参数值的时候，才允许被注解标注的方法处理请求。
- headers： HTTP请求中必须包含某些指定的header值，才允许被注解标注的方法处理请求。
@RequestMapping(value = "/article", method = POST)
@PostMapping(value = "/article")
上面代码中两种写法起到的是一样的效果，也就是PostMapping等同于@RequestMapping的method等于POST。同理：@GetMapping、@PutMapping、@DeleteMapping也都是简写的方式。
@RestController与@Controller
@Controller注解是开发中最常使用的注解，它的作用有两层含义：
- 一是告诉Spring，被该注解标注的类是一个Spring的Bean，需要被注入到Spring的上下文环境中。
- 二是该类里面所有被RequestMapping标注的注解都是HTTP服务端点。
@RestController相当于 @Controller和@ResponseBody结合。它有两层含义：
- 一是作为Controller的作用，将控制器类注入到Spring上下文环境，该类RequestMapping标注方法为HTTP服务端点。
- 二是作为ResponseBody的作用，请求响应默认使用的序列化方式是JSON，而不是跳转到jsp或模板页面。
@PathVariable 与@RequestParam
PathVariable用于URI上的参数，如下方法用于删除一篇文章，其中id为文章id。如：我们的请求URL为“/article/1”,那么将匹配DeleteMapping并且PathVariable接收参数id=1。而RequestParam用于接收普通表单方式或者ajax模拟表单提交的参数数据。
@DeleteMapping("/article/id")
public @ResponseBody AjaxResponse deleteArticle(@PathVariable Long id)
@PostMapping("/article")
public @ResponseBody AjaxResponse deleteArticle(@RequestParam Long id)
接收复杂嵌套对象参数
有一些朋友可能还无法理解RequestBody注解存在的真正意义，表单数据提交用RequestParam就好了，为什么还要搞出来一个RequestBody注解呢？RequestBody注解的真正意义在于能够使用对象或者嵌套对象接收前端数据
仔细看上面的代码，是一个self对象里面包含了一个friend对象。这种数据结构使用RequestParam就无法接收了，RequestParam只能接收平面的、一对一的参数。像上文中这种数据结构的参数，就需要我们在java服务端定义两个类，一个类是self，一个类是friend.
@NoArgsConstructor
@Data
public class Self
@JsonProperty("name")
private String name;
@JsonProperty("age")
private Integer age;
@JsonProperty("friend")
private FriendDTO friend;
@NoArgsConstructor
@Data
public static class FriendDTO
@JsonProperty("name")
private String name;
- 注意上面代码中省略了GET、SET方法等必要的java plain model元素。
- 注意成员变量名称一定要和JSON属性名称对应上。
- 注意接收不同类型的参数，使用不同的成员变量类型
@RestController
public class TestController
@GetMapping("/test")
public Object test(@RequestBody Self self )
System.out.println(self);
return self;
Http数据转换的原理
大家现在使用JSON都比较普遍了，其方便易用、表达能力强，是绝大部分数据接口式应用的首选。那么如何响应其他的类型的数据？其中的判别原理又是什么？下面就来给大家介绍一下：
- 当一个HTTP请求到达时是一个InputStream，通过HttpMessageConverter转换为java对象，从而进行参数接收。
- 当对一个HTTP请求进行响应时，我们首先输出的是一个java对象，然后由HttpMessageConverter转换为OutputStream输出。
当我们在Spring Boot应用中集成了jackson的类库之后，如下的一些HttpMessageConverter将会被加载。
| 实现类 | 功能说明 |
|---|---|
| StringHttpMessageConverter | 将请求信息转为字符串 |
| FormHttpMessageConverter | 将表单数据读取到MultiValueMap中 |
| XmlAwareFormHttpMessageConverter | 扩展与FormHttpMessageConverter，如果部分表单属性是XML数据，可用该转换器进行读取 |
| ResourceHttpMessageConverter | 读写org.springframework.core.io.Resource对象 |
| BufferedImageHttpMessageConverter | 读写BufferedImage对象 |
| ByteArrayHttpMessageConverter | 读写二进制数据 |
| SourceHttpMessageConverter | 读写java.xml.transform.Source类型的对象 |
| MarshallingHttpMessageConverter | 通过Spring的org.springframework,xml.Marshaller和Unmarshaller读写XML消息 |
| Jaxb2RootElementHttpMessageConverter | 通过JAXB2读写XML消息，将请求消息转换为标注的XmlRootElement和XmlType连接的类中 |
| MappingJacksonHttpMessageConverter | 利用Jackson开源包的ObjectMapper读写JSON数据 |
| RssChannelHttpMessageConverter | 读写RSS种子消息 |
| AtomFeedHttpMessageConverter | 和RssChannelHttpMessageConverter一样能够读写RSS种子消息 |
根据HTTP协议的Accept和Content-Type属性，以及参数数据类型来判别使用哪一种HttpMessageConverter。当使用RequestBody或ResponseBody时，再结合前端发送的Accept数据类型，会自动判定优先使用MappingJacksonHttpMessageConverter作为数据转换器。但是，不仅JSON可以表达对象数据类型，XML也可以。如果我们希望使用XML格式该怎么告知Spring呢，那就要使用到produces属性了。
@GetMapping(value ="/demo",produces = MediaType.APPLICATION_XML_VALUE)
这里我们明确的告知了返回的数据类型是xml，就会使用Jaxb2RootElementHttpMessageConverter作为默认的数据转换器。当然实现XML数据响应比JSON还会更复杂一些，还需要结合@XmlRootElement、@XmlElement等注解实体类来使用。同理consumes属性你是不是也会用了呢。
自定义HttpMessageConverter
其实绝大多数的数据格式都不需要我们自定义HttpMessageConverter，都有第三方类库可以帮助我们实现(包括下文代码中的Excel格式)。但有的时候，有些数据的输出格式并没有类似于Jackson这种类库帮助我们处理，需要我们自定义数据格式。该怎么做?
下面我们就以Excel数据格式为例，写一个自定义的HTTP类型转换器。实现的效果就是，当我们返回AjaxResponse这种数据类型的话，就自动将AjaxResponse转成Excel数据响应给客户端。
<dependency>
<groupId>org.apache.poi</groupId>
<artifactId>poi-ooxml</artifactId>
<version>3.9</version>
</dependency>
@Service
public class ResponseToXlsConverter extends AbstractHttpMessageConverter<AjaxResponse>
//数据返回给前端的时候，会携带该响应头
private static final MediaType EXCEL_TYPE = MediaType.valueOf("application/vnd.ms-excel");
ResponseToXlsConverter()
super(EXCEL_TYPE);
//处理前端传过来的inputstream，封装为ajaxreponse对象
@Override
protected AjaxResponse readInternal(final Class<? extends AjaxResponse> clazz,
final HttpInputMessage inputMessage)
throws IOException, HttpMessageNotReadableException
return null;
//针对AjaxResponse类型返回值，使用下面的writeInternal方法进行消息类型转换
@Override
protected boolean supports(final Class<?> clazz)
return (AjaxResponse.class == clazz);
//将数据从ajaxResponse中取出，以outputstream流的形式返回给前端
@Override
protected void writeInternal(final AjaxResponse ajaxResponse, final HttpOutputMessage outputMessage)
throws IOException, HttpMessageNotWritableException
final Workbook workbook = new HSSFWorkbook();
final Sheet sheet = workbook.createSheet();
final Row row = sheet.createRow(0);
row.createCell(0).setCellValue(ajaxResponse.getMessage());
row.createCell(1).setCellValue(ajaxResponse.getData().toString());
workbook.write(outputMessage.getBody());
- 实现AbstractHttpMessageConverter接口
- 指定该转换器是针对哪种数据格式的？如上文代码中的"application/vnd.ms-excel"
- 指定该转换器针对那些对象数据类型？如上文代码中的supports函数
- 使用writeInternal对数据进行输出处理，上例中是输出为Excel格式。
常用注解开发一个RESTful接口
开发REST接口
第一步：定义资源（对象）
@NoArgsConstructor
@Data
@Builder
public class Self
@JsonProperty("name")
private String name;
@JsonProperty("age")
private Integer age;
@JsonProperty("friend")
private FriendDTO friend;
@NoArgsConstructor
@Data
@Builder
public static class FriendDTO
@JsonProperty("name")
private String name;
@JsonProperty("createTime")
private LocalDateTime createTime;
- @Builder为我们提供了通过对象属性的链式赋值构建对象的方法，下文中代码会有详细介绍。
- @Data注解帮我们定义了一系列常用方法，如：getters、setters、hashcode、equals等
第二步：HTTP方法与Controller（动作）
我们实现一个简单的RESTful接口
- 增加一个朋友，使用POST方法
- 删除一个朋友，使用DELETE方法，参数是id
- 更新一个朋友，使用PUT方法，以id为主键进行更新
- 获取一个朋友，使用GET方法
下面代码中并未真正的进行数据库操作，为简化操作，只是进行模拟。
@Slf4j
@RestController
@RequestMapping("/rest")
public class ArticleController
//获取self，使用GET方法,根据id查询
//@RequestMapping(value = "/selfs/id",method = RequestMethod.GET)
@GetMapping("/selfs/id")
public AjaxResponse getArticle(@PathVariable("id") Long id)
Self.FriendDTO friendDTO = Self.FriendDTO.builder().name("小朋友").createTime(LocalDateTime.now()).build();
//使用lombok提供的builder构建对象
Self self = Self.builder().age(18).name("大忽悠")
.friend(friendDTO).build();
log.info("self:" + self);
return AjaxResponse.success(self);
//增加selfs ，使用POST方法(RequestBody方式接收参数)
// @RequestMapping(value = "/selfs",method = RequestMethod.POST)
// @PostMapping("/selfs")
// public AjaxResponse saveArticle(@RequestBody Self self,
// @RequestHeader String aaa)
//
// //因为使用了lombok的Slf4j注解，这里可以直接使用log变量打印日志
// log.info("saveArticle:" + self);
// log.info("请求头:" + aaa);
// return AjaxResponse.success();
//
//增加self ，使用POST方法(RequestParam方式接收参数)
@PostMapping("/selfs")
public AjaxResponse saveArticle(@RequestParam String name,
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@RequestParam LocalDateTime createTime)
log.info("saveArticle:" + createTime);
return AjaxResponse.success();
//更新self，使用PUT方法，以id为主键进行更新
//@RequestMapping(value = "/selfs",method = RequestMethod.PUT)
@PutMapping("/selfs")
public AjaxResponse updateArticle(@RequestParam Integer id)
if(id == null)
//article.name是必传参数,通常根据id去修改
//TODO 抛出一个自定义的异常
log.info("updateSlef:" + id);
return AjaxResponse.success();
//删除self，使用DELETE方法，参数是id
//@RequestMapping(value = "/selfs/id",method = RequestMethod.DELETE)
@DeleteMapping("/selfs/id")
public AjaxResponse deleteArticle(@PathVariable("id") Long id)
log.info("deleteSelf:" + id);
return AjaxResponse.success();
因为使用了lombok的@Slf4j注解（类的定义处），就可以直接使用log变量打印日志。不需要写下面的这行代码。
private static final Logger log = LoggerFactory.getLogger(HelloController.class);
统一规范接口响应的数据格式
下面这个类是用于统一数据响应接口标准的。它的作用是：统一所有开发人员响应前端请求的返回结果格式，减少前后端开发人员沟通成本，是一种RESTful接口标准化的开发约定。下面代码只对请求成功的情况进行封装，在后续的异常处理相关的章节会做更加详细的说明。
@Data
public class AjaxResponse
private boolean isok; //请求是否处理成功
private int code; //请求响应状态码（200、400、500）
private String message; //请求结果描述信息
private Object data; //请求结果数据（通常用于查询操作）
private AjaxResponse()
//请求成功的响应，不带查询数据（用于删除、修改、新增接口）
public static AjaxResponse success()
AjaxResponse ajaxResponse = new AjaxResponse();
ajaxResponse.setIsok(true);
ajaxResponse.setCode(200);
ajaxResponse.setMessage("请求响应成功!");
return ajaxResponse;
//请求成功的响应，带有查询数据（用于数据查询接口）
public static AjaxResponse success(Object obj)
AjaxResponse ajaxResponse = new AjaxResponse();
ajaxResponse.setIsok(true);
ajaxResponse.setCode(200);
ajaxResponse.setMessage("请求响应成功!");
ajaxResponse.setData(obj);
return ajaxResponse;
//请求成功的响应，带有查询数据（用于数据查询接口）
public static AjaxResponse success(Object obj,String message)
AjaxResponse ajaxResponse = new AjaxResponse();
ajaxResponse.setIsok(true);
ajaxResponse.setCode(200);
ajaxResponse.setMessage(message);
ajaxResponse.setData(obj);
return ajaxResponse;
获取操作:
//获取self，使用GET方法,根据id查询
//@RequestMapping(value = "/selfs/id",method = RequestMethod.GET)
@GetMapping("/selfs/id")
public AjaxResponse getArticle(@PathVariable("id") Long id)
Self.FriendDTO friendDTO = Self.FriendDTO.builder().name("小朋友").createTime(LocalDateTime.now()).build();
//使用lombok提供的builder构建对象
Self self = Self.builder().age(18).name("大忽悠")
.friend(friendDTO).build();
log.info("self:" + self);
重学SpringBoot系列之Mockito测试