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中有什么區別？知乎嚴振傑回答