RESTful風(fēng)格的API接口開發(fā) Spring Cloud

學(xué)習(xí)筆記大佬繞路,小白多篇文章整合總結(jié)篇

簡單背景

網(wǎng)絡(luò)程序正朝著移動設(shè)備的方向發(fā)展谬擦，前后端分離贴妻、APP帚呼，最好的交互交互方式莫過于通過API接口實現(xiàn)认罩。既然要進(jìn)行數(shù)據(jù)交互，那么這接口就得有講究了：既要實用掰担，又要優(yōu)雅好看汇陆！

那么，如何寫一套漂亮的API接口呢带饱？

本次我們先了解一下Spring對API接口開發(fā)的支持毡代，然后我們采用Spring Boot搭建項目，借用Swagger2列出API接口勺疼，便于查閱教寂。

接口返回格式

API接口要求返回的格式是 application/json，我們知道網(wǎng)頁返回的格式一般是 text/html执庐，因此酪耕，Spring Boot為寫接口，提供了兩種實現(xiàn)方式：類注解和方法注解轨淌。

類注解 @RestController

我們只需要在類上寫上注解 @RestController迂烁，那么此Controller返回格式就都是text/json看尼。

/*類注解*/
@RestController
@RequestMapping("/sdust/v1/sdcNode")
public class SdcNodeController {

    @Autowired
    private SdcNodeApp sdcNodeApp;
    ……
}

方法注解 @ResponseBody

我們只需要在某個方法上寫上注解 @ResponseBody，那么該方法返回格式是text/json盟步。如下圖

/*類注解*/
@Controller
@RequestMapping("/sdust/v1/sdcNode")
public class SdcLnodeController {

    @Autowired
    private SdcNodeApp sdcNodeApp;
    @RequestMapping("/lef")
    @ResponseBody
    public String getInfo() {
        return "";
    }
    ……
}

值得提醒的是藏斩，雖然都是都可以，但更推薦使用類注解却盘，會顯得我們的編碼風(fēng)格十分統(tǒng)一狰域，代碼更加緊湊，不至于看起來零散谷炸。

我們來看下 @RestController 的源碼

@Controller
@ResponseBody
public @interface RestController {
……
}

請求方式源碼

@RequestMapping
在``RequestMapping`的源碼中提到北专，這種支持任意請求方式，類似于自適應(yīng)旬陡。

@Mapping
public @interface RequestMapping {
……
}

@GetMapping
客戶端只能用 GET 方式請求拓颓，適用于查詢數(shù)據(jù)

@RequestMapping(method = RequestMethod.GET)
public @interface GetMapping{
……
}

@PostMapping
客戶端只能用 POST方式請求，適用于提交數(shù)據(jù)描孟。

@RequestMapping(method = RequestMethod.POST)
public @interface PostMapping{
……
}

@DeleteMapping
客戶端只能用 DELETE方式請求驶睦，使用于刪除數(shù)據(jù)。

@RequestMapping(method = RequestMethod.DELETE)
public @interface DeleteMapping{
……
}

@PutMapping
客戶端只能用 PUT方式請求匿醒，使用于修改數(shù)據(jù)（但在實際使用中场航，我個人建議還是采用POST方式較為妥當(dāng)）。

@RequestMapping(method = REquestMethod.PUT)
public @interface PutMapping{
……
}

以上請求我是在接口開發(fā)中經(jīng)常使用的廉羔，圖片是注解源碼溉痢。當(dāng)然還有其他一些。關(guān)于請求方式及使用范圍憋他，可以參考 RESTful API

接收參數(shù)

@RequestParam

我們來寫一個示例并說明：

public String getInfo(@RequestParam(name = "param", 
                                        required = false, 
                                        defaultValue = "param dafault value") String param)

name代表提交參數(shù)名孩饼。
required意思是這個參數(shù)是否必需，默認(rèn)true竹挡，沒有該參數(shù)镀娶，無法調(diào)用此方法；這里設(shè)為false揪罕，有無該參數(shù)都可以調(diào)用梯码。
defaultValue如果該參數(shù)值為空，那么就使用默認(rèn)值好啰。

@PathVariable

    @RequestMapping("/get-info/{param}")
    public String getInfo(@PathVariable("param") Object param)

我們可以在請求方法后面直接跟值轩娶，省去了 ？參數(shù)名= 框往。
這種一般配合 @DeleteMapping罢坝、@PutMapping使用。

@RequestHeader

這個使用了獲取提交數(shù)據(jù)的 Headers 的值搅窿。我是用來接收 TOKEN嘁酿。后面會舉例。

數(shù)據(jù)格式

下面我們來了解下男应，Spring Boot 可以支持的數(shù)據(jù)格式闹司。
我一般常用的基本數(shù)據(jù)類型有 int、String沐飘。

而我們在日常中游桩，還可能有 Array、List耐朴、Map……

那么借卧，Spring Boot支持嗎？我們?nèi)绾谓鉀Q筛峭？并且統(tǒng)一化呢铐刘？

JSON！

毫無疑問JSON可以幫助我們解決這個問題影晓，當(dāng)然XML也是可以的镰吵。

在Controller層當(dāng)中使用一些封裝的方法，講實現(xiàn)的內(nèi)容封裝到自己定義的數(shù)據(jù)結(jié)構(gòu)中返回給前端就可以實現(xiàn)通過JSON傳遞數(shù)據(jù)

至于前端方面挂签，先看 Ajax 代碼：

$.ajax({
        headers : {
            Accept: "application/json; charset=utf-8",
            'token' : '9B4BF951093F1F1A40BB2DAAA30B3838'
        },
        url: URI + '/admin/blog/add',
        type: 'POST', 
        async: true,   
        data: {
            ...
        },
        timeout: 3000,   
        dataType: 'json', 
        beforeSend: function(xhr){},
        success: function(data, textStatus, jqXHR){
            console.log(data);
        },
        error: function(xhr, textStatus){
            console.log(xhr);
        },
        complete: function(){}
 })

現(xiàn)在的問題是如何獲取 token的值疤祭？沒錯，就是 @RequestHeader("token")!

如果我們沒在Controller饵婆，那怎么辦

答案是

    String token = request.getHeader("token");
    System.out.println(token);