如何设计一个优雅的RESTFUL的接口

show me the code and talk to me,作的出来更要说的明白
我是布尔bl，你的支持是我分享的动力！

一 、引入

设计接口是咱们开发人员的平常操做。当咱们把接口交给前端人员时，是否有种拔剑出鞘的错觉。毕竟交付接口，咱们的开发工做就阶段性完成了。不过，若是咱们没有一个接口设计规范的时候，结果会怎样呢？咱们来张图感觉一下。

2、REST

2000年，一个年轻小伙子（Roy Thomas Fielding）在他的博士论文提出了 REST。REST 是一种万维网软件架构风格。为何说是风格不是标准呢？我的理解可能说标准就有点过度了。小伙子作不到。随后这种风格被推广开来，漂洋过海，被大众熟知。在 REST 的基础上，产生了 RESTFUL 。什么是 RESTFUL？简单的说，符合 REST 风格的接口就是 RESTFUL。

3、RESTFUL

接口各类各样。正如一千我的眼里有一千个鲁迅。RESTFUL 接口究竟长什么样子呢？

3.1 HTTP 的方法

HTTP 里面有几个基本的方法。咱们利用这些约定一些规范。

方法	做用
GET	获取数据
POST	插入数据
PUT	更新数据
DELETE	删除数据

从表中，若是咱们能够清楚看到当咱们的接口是关于获取数据，那么咱们使用 GET 方法。
若是咱们能够清楚看到当咱们的接口是关于插入数据，那么咱们使用 POST 方法。
若是咱们能够清楚看到当咱们的接口是关于更新数据，那么咱们使用 PUT 方法。
若是咱们能够清楚看到当咱们的接口是关于删除数据，那么咱们使用 DELECT 方法。

3.2 名词

在上面咱们已经知道接口在何时须要什么方法，那么咱们如今来进入到设计接口的第二步。

咱们看看线上网站的接口是怎么样的。

图中咱们能够看到有个 v1 ，他表明的是版本号，因此咱们在设计接口的时候能够在将版本号写上，用 v一、v二、v3 等表示。

咱们发现他的接口都是名词。因此咱们知道 RESTFUL 接口使用的是名词。好比咱们设计一个获取数据的接口，咱们可这样设计

/v1/list 
复制代码

上面接口是获取全部数据。

当咱们须要列表中的一条数据，咱们能够这样设计

/v1/list/1 
复制代码

上面接口表示获取是列表的1号数据，咱们能够获取2号、3号数据等等，只要改变数字便可。

3.3 组合

结合上面两步，咱们就能够设计出增删改查的 restful 接口了。

接口	方法	做用
/v1/list	GET	获取列表
/v1/list	POST	增长列表
/v1/list	PUT	更新列表
/v1/list	DELETE	删除列表

3.4 应用

如下是源码的demo

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
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;

@SpringBootApplication
@RestController
@Slf4j
public class LsbRestfulApplication {

    public static void main(String[] args) {
        SpringApplication.run(LsbRestfulApplication.class, args);
    }

    /** * 获得全部列表 * @return */
    @RequestMapping(value = "/v1/list",method = RequestMethod.GET)
    public String getList(){
        log.info("获得列表");
        return "获得列表";
    }

    /** * 获得列表中的一条 * @param name * @return */
    @RequestMapping(value = "/v1/list/{name}",method = RequestMethod.GET)
    public String getListone(@PathVariable("name") String name){
        log.info("获得列表"+name);
        return "获得列表"+name;
    }

    /** * 往列表中的增长一条数据 * @return */
    @RequestMapping(value = "/v1/list",method = RequestMethod.POST)
    public String addList(){
        log.info("增长一个列表1");
        return "增长一个列表1";
    }

    /** * 更新列表中的一条数据 * @return */
    @RequestMapping(value = "/v1/list/{name}",method = RequestMethod.PUT)
    public String updateListOne(@PathVariable("name") String name){
        log.info("更新列表"+name);
        return "更新列表"+name;
    }
    
    /** * 删除全部列表 * @return */
    @RequestMapping(value = "/v1/list",method = RequestMethod.DELETE)
    public String delList(){
        log.info("删除一个列表");
        return "删除一个列表";
    }
}
复制代码

4、某同城交友网站

github.com/buerbl

暗号：荆轲刺秦王