Spring框架學習筆記（9）——API接口設計相關知識及具體編碼實現

最近須要設計一個API服務器，想要把API接口搞得規範一下，就經過網上搜集到了一些資料，如下即是本身的一些理解以及相關的具體實現

本文采用的是spring boot+maven的方案

restful規範

這個規範我在這裏也不打算長篇大論地講解，怎麼說呢，有人喜歡有人討厭，我也不去爭，由於我經驗很少，見解和大佬有所不一樣。

restful規範簡單來講，就是經過一些關鍵字去定義url接口，從而讓url具備更好的可讀性，以下面舉個例子

# 查詢全部用戶
http://localhost:9200/shunbang/api/user/users
# 指定id爲1的用戶
http://localhost:9200/shunbang/api/user/users/1
# 數據太多，只要前10
http://localhost:9200/shunbang/api/user/users?limit=10
# 從第十條數據後開始（不要前十條數據）
http://localhost:9200/shunbang/api/user/users?offset=10

我以爲restful規範起來，url的可讀性較好

restful規範使用的幾種方式

方式	說明
get	從服務器上獲取資源(select)
put	更新服務器上的資源(update)
post	將傳入的資源存儲在服務器上(insert)
delete	刪除服務器上的資源(delete)

url請求協議介紹

方式	說明	例子
application/x-www-form-urlencoded	默認，客戶端經過key-value鍵值對傳遞數據	http://localhost:9200/shunbang/api/user/update?id=1&name=xx
application/json	客戶端經過body發送json數據
application/xml	客戶端經過body發送xml數據
application/octet-stream	客戶端經過body發送Binary數據（二進制文件）
multipart/form-data	客戶端經過body發送一個表單

API文檔生成框架 smart-doc

介紹

這裏，我使用了smart-doc這款框架，能夠無侵入實現API接口的註釋，須要在Controller和實體類中添加註釋

使用

使用此開源庫很簡單，咱們只須要在maven項目中添加插件的依賴便可

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!--指定生成文檔的使用的配置文件,配置文件放在本身的項目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定項目名稱-->
        <projectName>測試</projectName>
        <!--smart-doc實現自動分析依賴樹加載第三方依賴的源碼，若是一些框架依賴庫加載不到致使報錯，這時請使用excludes排除掉-->
        <excludes>
            <!--格式爲：groupId:artifactId;參考以下-->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <!--若是不須要在執行編譯時啓動smart-doc，則將phase註釋掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

以後，在resources文件夾中新建smart-doc.json文件，進行一些配置便可

{
  "outPath": "Q:\\JavaWebProject\\shunbang\\target", //指定文檔的輸出路徑
  "serverUrl": "http://localhost:9200/shunbang", //設置服務器地址,非必須
//  "serverUrl": "http://47.101.148.199:9200/shunbang", //設置服務器地址,非必須
  "isStrict": false, //是否開啓嚴格模式
  "allInOne": true  //是否將文檔合併到一個文件中，通常推薦爲true
}

我這裏沒開啓嚴格模式，如果開啓了嚴格模式，則調用插件的時候就會報錯

以後直接在旁邊的插件找到，選擇對應生成的文檔

以後就能夠在輸出文件夾中找到html文件了

打開網頁，就會有詳細的文檔了

補充

JsonIgnore註解

如果存在某些敏感字段不須要被返回，在實體類的字段中添加JsonIgnore註解(注意：此JsonIgnore註解爲spring boot內置jackson框架自帶)

public class JacksonAnnotation {

    /**
     * 用戶名
     */

    @JsonProperty("name")
    private String username;


    /**
     * 身份證號
     */
    @JsonIgnore
    private String idCard;
}

Fastjson使用 @JSONField(serialize = false),起關鍵做用的是serialize = false

mock註解

smart-doc會在生成的文檔的例子中進行自動隨機賦值，以下圖

若是不想隨機賦值，可使用mock註解指定例子中的數據

ignore註解

這個是smart-doc自帶的註解，寫在實體類字段的註釋上，生成的API文檔就會忽略此字段

更多詳情，請參考官方文檔

具體編碼

spring boot中其實內置了GetMapping、PostMapping、PutMapping、DeleteMapping，分別對應的不一樣的請求方式，若是使用了以上註解，那麼發送url請求的方式也是應該相對應，不然服務器不會進行數據的返回

1.指定id

想要經過http://localhost:9200/shunbang/api/user/users/1查詢指定id用戶信息

使用PathVariable註解

/**
 * 查詢指定id的用戶信息
 *
 * @param id 用戶id
 * @return 用戶信息
 */
@GetMapping("{id}")
public User selectByPk(@PathVariable("id") Integer id) {
    return userMapper.selectOne(new QueryWrapper<User>().eq("user_id", id));
}

2.limit限制

想要經過http://localhost:9200/shunbang/api/user/users?limit=10來得到前幾條記錄，limit此參數是可選的，使用RequestParam註解

當用戶沒有輸入limit參數，則顯示返回全部的數據，有的話則進行數據的限制，offset也是同理，以後便很少說了

/**
 * 查詢全部用戶
 *
 * @return 用戶列表的json
 */
@GetMapping("users")
public List<User> selectAll(@RequestParam(required = false) Integer limit) {
    if (limit == null) {
        return userMapper.selectList(null);
    } else {
        System.out.println(limit);
        return userMapper.selectList(null);
    }
}

3.傳遞實體類

本來我是想要經過http://localhost:9200/shunbang/api/user/update?jsonData=xx這樣傳遞實體類的json數據，以後由後臺接收json數據，並再將json數據轉爲實體類對象，調用update方法，進行表記錄的update

其實，有個方法比上面的方法更簡單，使用RequestBody註解，以後進行put的請求，將json數據直接經過body傳遞

@PutMapping("update")
public boolean updateUser(@RequestBody User user) {
    return user.updateById();
}

Java發送url請求

HttpURLConnection conn =new URL("address").openConnection();
conn.setRequestMethod("PUT"); // 能夠根據須要 提交 GET、POST、DELETE、PUT等http提供的功能
conn.setRequestProperty("Content-Type", " application/json");//設定 請求格式 json，也能夠設定xml格式的

上述是原生的，以後我會在補充使用okhttp框架進行相關的接口申請數據

我是使用的postwoman進行API的測試

參考

smart-doc
SpringBoot RestFul風格API接口開發
Post 方法參數寫在body中和寫在url中有什麼區別？知乎嚴振杰回答