如何設計一個優雅的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

暗號：荊軻刺秦王