SpringBoot入門實踐(四)-RESTful API 最佳設計

 個人博客：蘭陵笑笑生,歡迎瀏覽博客！

 上一章 SpringBoot入門實踐(三)-工程結構與經常使用註解當中,咱們介紹了SpringBoot的項目的工程結構和一些經常使用的註解。本章簡單的講一講API的設計。

 網上有很是多的關於API設計的介紹，本章內容從本身的實際經驗簡單介紹如何更好的設計API。

API的有什麼關鍵的要求

1 任何客戶端都可以調用，須要一個標準，使得客戶端和服務端達成一致,必須簡單

2 api獨立於客戶端，api的發展，現有的客戶端能夠繼續運行，不須要修改。

RESTful URLS

REST API 是圍繞這資源設計的,資源有一個惟一的標識符，而且使用JSON

使用HTTP 定義資源的操做

1. GET 檢所獲取資源
2. POST 建立資源，固然POST也能夠用來觸發實際上不建立資源的操做
3. PUT 建立或者更新
4. DELETE 移除

SpringBoot與RESTful

 在springBoot當中提供了不少的註解，使用這些註解就很容易的實現RESTful的api

@RequestMapping:

 該註解有6個參數：

• value/path ：路徑名稱
• params ：請求的參數
• method ：方法類型 GET、POST、PUT、DELETE 等
• headers： request 中必須包含某些指定的 header 值，才能讓該方法處理請求。
• consumes : （Content-Type），例如application/json，text/html；

例如請求 表示一個GET請求：

@RequestMapping(path = "/list",method = RequestMethod.GET, consumes ="application/json")
public HttpResponse list() { 
    List<User> user = new ArrayList<>(userMap.values());   
    return HttpResponse.ok().setData(user);
}

@PostMapping

  等價於@RequestMapping(path = "/**",method = RequestMethod.POST)

@GetMapping

  等價於@RequestMapping(path = "/**",method = RequestMethod.GET)

@DeleteMapping

  等價於@RequestMapping(path = "/**",method = RequestMethod.DELETE)

@PutMapping

  等價於@RequestMapping(path = "/**",method = RequestMethod.PUT)

具體的設計

 URL的定義在每一個公司中都不同，這裏簡單給出一些我本身的實際經驗，url路徑定義：

1 url理解簡單

2 api有版本控制， 版本控制能夠快速迭代並避免無效的請求訪問已更新的接入點

http://www.example.com/api/v{version}/模塊名稱/操做名稱

獲取單個用戶

GET /api/v1/user/get/1

或者

GET /api/v1/user/1

分頁或者所有的查詢，輸入的參數是JSON

POST /api/v1/user/list

這個新增和更新通常都是一個api，固然也可使用PUT

POST /api/v1/user/save

刪除用戶資源

DELETE /api/v1/user/delete/12

或者

DELETE /api/v1/user/12

public class User {  
    private Long id; 
    private String userName; 
    private Long age;
    
    ...
        
}

自定義統一返回結果

package com.miroservice.chapter2.common;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.io.Serializable;
import java.util.*;


@JsonInclude(JsonInclude.Include.NON_NULL)
public class HttpResponse implements Serializable { 
    
    private long code;  
    private String message; 
    private Long total;  
    private Object data;  
    private List<Object> table;  
    private String requestid;  
    public static final long CODE_SUCCESS = 200;  
    public static final long CODE_ERROR = 500;  
    public static final long CODE_VALIDATE_FAILED = 404;  
    public static final long CODE_UNAUTHORIZED = 401;  
    public static final long CODE_FORBIDDEN = 403;    
    public HttpResponse() {    
        this(200, (String) null);    } 
    public HttpResponse(long code, String message) {    
        this.code = CODE_SUCCESS;     
        this.code = code;      
        this.message = message;      
        this.requestid = UUID.randomUUID().toString().replaceAll("-", "");  
    }   
    public static HttpResponse error(String message) {   
        return new HttpResponse(500, message);  
    }  
    public HttpResponse setData(Object data) {       
        this.data = data;    
        return this;  
    }  
    public HttpResponse data(Object data) {  
        return this.setData(data);  
    }
    public HttpResponse addListItem(Object item) {   
        if (this.table == null) {       
            this.table = new ArrayList();     
        }     
        this.table.add(item);       
        
        return this;  
    }  
    public HttpResponse setTotal(Long total) {    
        this.total = total;    
        return this;   
    }    
    public HttpResponse setTotal(Integer total) {    
        this.total = (long) total;      
        return this; 
    }   
    public static HttpResponse ok() {  
        return new HttpResponse();  
    }  
    public HttpResponse set(String field, String value) {  
        if (this.data == null || !(this.data instanceof Map)) {    
            this.data = new HashMap();    
        }      
        ((Map) this.data).put(field, value); 
        return this;
    }   
    public long getCode() {   
        return this.code;   
    }   
    public HttpResponse setCode(long code) {    
        this.code = code;      
        return this; 
    }    public String getMessage() {       
        return this.message;  
    }   
    public HttpResponse setMessage(String message) {     
        this.message = message;       
        return this;   
                                               
    }   
    public Long getTotal() {     
        return this.total == null && this.table != null ?     Long.valueOf(String.valueOf(this.table.size())) : this.total;   
    }   
    public Object getData() {  
        return this.data;   
                                 }  
    public List<Object> getTable() {      
        return this.table; 
    }  
    public HttpResponse setTable(List table) {    
        this.table = table;   
        return this;  
    }   
    public HttpResponse table(List table) {    
        return this.setTable(table); 
    }  
    public String getRequestid() {     
        return this.requestid; 
    }  
    public HttpResponse setRequestid(String requestid) {     
        this.requestid = requestid;    
        return this;    }
}

 Controller層

/** 
* 1 api 的設計 一眼明瞭
* 2 有版本
* 3 控制層統一返回自定義的結果 
*/
@RestController
@RequestMapping("/api/v1/user")
public class UserController { 
    static Map<Long, User> userMap = new HashMap<Long, User>();   
    /**   
    * 列表請求 
    * @return 
    */   
   @RequestMapping(method = RequestMethod.GET, consumes = "application/json")                @GetMapping(consumes = "application/json")    
    public HttpResponse list() {     
        List<User> user = new ArrayList<>(userMap.values());     
        return HttpResponse.ok().setData(user);  
    }  
    /**   
    * 保存  
    * @param user   
    * @return  
    */  
    @PostMapping("/save")   
    public HttpResponse save(@RequestBody User user) {      
        userMap.put(user.getId(), user);      
        return HttpResponse.ok();    }  
    /**     
    * 獲取單個用戶  
    * @param id   
    * @return   
    */  
    @GetMapping("/get/{id}") 
    public HttpResponse get(@PathVariable Long id) {   
        final User user = userMap.get(id);    
        return HttpResponse.ok().setData(user);    } 
    /**   
    * 刪除  
    * @param id   
    * @return  
    */  
    @DeleteMapping("/delete/{id}")   
    public HttpResponse delete(@PathVariable Long id) {  
        userMap.remove(id);     
        return HttpResponse.ok(); 
    }
    
}

 以上就是本期的分享，你還能夠關注本博客的#Spring Boot入門實踐系列!#

 參考： #微軟的API實踐#

     #[Spring REST DOC](https://docs.spring.io/spring-restdocs/docs/2.0.3.RELEASE/reference/html5/)#

本文由博客一文多發平臺 OpenWrite 發佈！
個人博客[蘭陵笑笑生] ( http://www.hao127.com.cn/),歡...！