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規範使用的幾種方式

url請求協議介紹

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