Spring Boot开发RESTFUL接口

一、什么是RESTFUL风格

Restful是英文Representational State Transfer(表象性状态转变)或者表述性状态转移; Rest是web服务的一种架构风格,使用HTTP,URL,XML,JSON,HTML等广泛流行的标准和协议; 轻量级,跨平台,跨语言的架构设计, 是一种设计风格,不是一种标准, 而是一种思想。RESTful是基于http方法的API设计风格,而不是一种新的技术。

二、RESTFUL风格的好处

  • 看URL就知道要什么资源
  • 看HTTP Method就知道针对资源干什么
  • 看Http Status Code就知道结果如何

对接口开发提供了一种可以广泛适用的规范,为前端后端交互减少了接口交流的口舌成本,是约定大于配置的体现。

三、RESTUL风格设计API接口的一些概念

1、RESTful是面向资源的(名词)

REST 通过 URI 暴露资源时,会强调不要在 URI 中出现动词。比如:

不符合REST的接口URI 符合REST接口URI 功能
GET /api/getArticle/{id} GET /api/article/{id} 获取一篇文章
GET /api/getArticles GET /api/articles 获取所有文章
GET /api/addArticle POST /api/article 添加一篇文章
GET /api/editArticle/{id} PUT /api/article/{id} 修改一篇文章
GET /api/deleteArticle/{id} DELETE /api/article/{id} 删除一篇文章

2、用HTTP方法体现对资源的操作(动词)

  • GET : 获取、读取资源
  • POST : 添加资源
  • PUT : 修改资源
  • DELETE : 删除资源

实际上,这四个动词实际上就对应着增删改查四个操作,这就利用了HTTP动词来表示对资源的操作。 

3、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%以上的场景。这三个状态码大家都记得住,而且非常常用,多了就不一定了。

4、Get方法和查询参数不应该改变数据

改变数据的事交给POST、PUT、DELETE

5、使用复数名词

/articles 而不是 /article

6、复杂资源关系的表达

GET /cars/711/drivers/ 返回 使用过编号711汽车的所有司机
GET /cars/711/drivers/4 返回 使用过编号711汽车的4号司机

7、高级用法: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了。

8、资源过滤、排序、选择和分页的表述

9、版本化你的API

强制性增加API版本声明,不要发布无版本的API。如:/api/v1/blog

面向扩展开放,面向修改关闭:也就是说一个版本的接口开发完成测试上线之后,我们一般不会对接口进行修改,如果有新的需求就开发新的接口进行功能扩展。这样做的目的是:当你的新接口上线后,不会影响使用老接口的用户。如果新接口目的是替换老接口,也不要在v1版本原接口上修改,而是开发v2版本接口,并声明v1接口废弃!

四、Spring Boot开发一个RESTFUL接口

1、定义对象

/**
 * 文章
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Article {
    private Long  id;
    private String title; //标题
    private String categoryName;//分类
    private String content;//内容
    private Date createTime;//发布时间
    private List<Reader> authors;//文章读者
}
/**
 * 读者
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Reader {
  private String name;
  private Integer age;
}

@Data都是lombok提供给我们的注解,有利于我们简化代码。@Data注解帮我们定义了一系列常用方法,如:getters、setters、hashcode、equals等。@AllArgsConstructor注解为对象提供全参构造函数。@NoArgsConstructor注解为对象提供无参构造函数。

2、实现Controller

@Slf4j
@RestController
@RequestMapping("/rest")
public class ArticleController {

  //获取一篇Article,使用GET方法,根据id查询一篇文章
  @GetMapping("/article/{id}")
  public ResponseResult getArticle(@PathVariable("id") Long id){

    Article article = new Article(1L,"Spring Boot入门到精通","Java","Spring Boot入门到精通写得不错哦!",new Date(),null);

    log.info("article:" + article);

    return ResponseResult.success(article);
  }


  //增加一篇Article ,使用POST方法(RequestBody方式接收参数)
  @PostMapping("/articles")
  public ResponseResult saveArticle(@RequestBody Article article){
    
    log.info("saveArticle:" + article);
    return ResponseResult.success();
    
  }
  
  //更新一篇Article,使用PUT方法,以id为主键进行更新
  @PutMapping("/articles")
  public ResponseResult updateArticle(@RequestBody Article article){
 
    log.info("updateArticle:" + article);
    return ResponseResult.success();
  }

  //删除一篇Article,使用DELETE方法,参数是id
  @DeleteMapping("/articles/{id}")
  public ResponseResult deleteArticle(@PathVariable("id") Long id){

    log.info("deleteArticle:" + id);
    return ResponseResult.success();
  }

}

因为使用了lombok的@Slf4j注解(类的定义处),就可以直接使用log变量打印日志。不需要写下面的这行代码。

private static final Logger log = LoggerFactory.getLogger(ArticleController .class);

3、定义统一响应结果

下面这个类是用于统一数据响应接口标准的。它的作用是:统一所有开发人员响应前端请求的返回结果格式,减少前后端开发人员沟通成本,是一种RESTful接口标准化的开发约定。

@Data
public class ResponseResult {

  private boolean isok;  //请求是否处理成功
  private int code; //请求响应状态码(200、400、500)
  private String message;  //请求结果描述信息
  private Object data; //请求结果数据(通常用于查询操作)

  private ResponseResult(){}

  //请求成功的响应,不带查询数据(用于删除、修改、新增接口)
  public static ResponseResult success(){
    ResponseResult ajaxResponse = new ResponseResult();
    ajaxResponse.setIsok(true);
    ajaxResponse.setCode(200);
    ajaxResponse.setMessage("请求响应成功!");
    return ajaxResponse;
  }

  //请求成功的响应,带有查询数据(用于数据查询接口)
  public static ResponseResult success(Object obj){
    ResponseResult ajaxResponse = new ResponseResult();
    ajaxResponse.setIsok(true);
    ajaxResponse.setCode(200);
    ajaxResponse.setMessage("请求响应成功!");
    ajaxResponse.setData(obj);
    return ajaxResponse;
  }

  //请求成功的响应,带有查询数据(用于数据查询接口)
  public static ResponseResult success(Object obj, String message){
    ResponseResult ajaxResponse = new ResponseResult();
    ajaxResponse.setIsok(true);
    ajaxResponse.setCode(200);
    ajaxResponse.setMessage(message);
    ajaxResponse.setData(obj);
    return ajaxResponse;
  }


}

五、使用Postman测试RESTFUL接口

1、测试获取一篇文章

2、测试增加一篇文章

3、测试更新一篇文章

4、测试删除一篇文章

 

下载本文源码:springboot-demo

一点教程,一个分享编程知识的公众号。跟着站长一起学习和进步。

通俗易懂,深入浅出,一篇文章只讲一个知识点。

在公交、在地铁、在厕所都可以阅读,随时随地涨姿势。

文章不涉及代码,不烧脑细胞,人人都可以学习。

当你决定关注「一点教程」,你已然超越了90%的程序员!

一点教程二维码