Spring框架學習筆記(9)——API介面設計相關知識及具體編碼實現

来源:https://www.cnblogs.com/stars-one/archive/2020/02/13/12305429.html

最近需要設計一個API伺服器,想要把API介面搞得規範一下,就通過網上搜集到了一些資料,以下便是自己的一些理解以及相關的具體實現 本文采用的是spring boot+maven的方案 restful規範 這個規範我在這裡也不打算長篇大論地講解,怎麼說呢,有人喜歡有人討厭,我也不去爭,因為我經驗不多, ...


最近需要設計一個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中其實內置了GetMappingPostMappingPutMappingDeleteMapping,分別對應的不同的請求方式,如果使用了以上註解,那麼發送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中有什麼區別?知乎嚴振傑回答


您的分享是我們最大的動力!

更多相關文章
  • 1、建造者模式介紹: 2、建造者模式角色分析 3、方式一:建造模式的常規用法(有指揮) 4、方式二:用戶可以自定義套餐和選擇預設套餐(沒有指揮者) 5、優點分析: 6、缺點分析: 7、應用場景: 8、建造者模式與抽象工廠模式的比較 ...
  • CAP定理: 在一個分散式系統中,Consistency(數據一致性)、 Availability(服務可用性)、Partition tolerance(分區容錯性),三者不可兼得。 一致性(Consistency) 在分散式系統中的所有數據備份(副本),在同一時刻數據的值是否一致。(等同於所有節點 ...
  • 當你第一次定義Protocol Buffer的消息的時候,你肯定會給消息設定一套規則需求。但是隨著時間的推進,你的業務可能會發生了變化,與此同時,你的Protocol Buffer消息類型的需求也會隨之變化。 也就是說:有一些欄位可能會發生變化,可能會添加一些欄位,也可能會刪除一些欄位。但是可能有很 ...
  • 00.瞭解反射 請從記憶體的角度分析對象創建的過程 1.找到主函數所在的類,該類.class載入到方法區,通過反射調用這個主方法,方法進棧 01.瞭解IDE,類路徑 02.位元組碼對象Class 源代碼部分截圖: 知識點1: 3種獲取Class位元組碼對象的方式及優缺點 知識點2: 通過位元組碼Class創 ...
  • 前言 今天一番在22:30開始準備今日的日更,冒著極大的斷更風險,研究了一個開源項目,批量下載手機壁紙。 因為一番每天都為文章開頭的配圖撓頭,正向從網上批量抓取一些美圖,以充實庫存。 剛好,一番昨日的文章里有這麼一個抓取手機背景圖片的開源項目,於是一番今天嘗試了下。 要知道,一般調試一段未知代碼,一 ...
  • 一、cookie的保存與讀取 1.cookie的保存-FileCookie.Jar from urllib import request,parse from http import cookiejar #創建cookiejar實例 filename = "cookie.txt" cookie = ...
  • JavaSE學習筆記(12) 線程 多線程 併發與並行 併發 :指兩個或多個事件在 同一個時間段內 發生。 並行 :指兩個或多個事件在 同一時刻 發生(同時發生)。 在操作系統中,安裝了多個程式,併發指的是在一段時間內巨集觀上有多個程式同時運行,這在單 CPU 系統中,每一時刻只能有一道程式執行,即微 ...
  • MySQL官方對索引的定義為:索引(Index)是幫助MySQL高效獲取數據的數據結構。 資料庫查詢是資料庫的最主要功能之一,我們都希望查詢數據的速度能儘可能的快,因此資料庫系統的設計者會從查詢演算法的角度進行優化,這篇文章對索引做一個系統的梳理,希望對大家有幫助。 一、MySQL有哪些索引類型 索引 ...
一周排行
  • 微信公眾號dotnet跨平臺2020年初做的一個關於中國.NET開發者調查收到了開發者近 1400 條回覆。這份調查報告涵蓋了開發者工具鏈的所有部分,包括編程語言、應用架構、應用伺服器、運行時平臺、框架技術、框架配置、IDE、.NET/.NET Core 發行版部署模式、構建工具和Kubernete... ...
  • Winform控制項的雙緩衝。控制項的雙緩衝屬性是隱藏的,可以通過反射改變其屬性值。 lv.GetType().GetProperty("DoubleBuffered", BindingFlags.Instance | BindingFlags.NonPublic).SetValue(lv, true, ...
  • 1. 需求 上圖這種包含多選(CheckBox)和單選(RadioButton)的菜單十分常見,可是在WPF中只提供了多選的MenuItem。順便一提,要使MenuItem可以多選,只需要將MenuItem的 屬性設置為True: 不知出於何種考慮,WPF沒有為MenuItem提供單選的功能。為了在 ...
  • gRPC的結構 在我們搭建gRPC通信系統之前,首先需要知道gRPC的結構組成。 首先,需要一個server(伺服器),它用來接收和處理請求,然後返迴響應。 既然有server,那麼肯定有client(客戶端),client的作用就是向server發送請求,具體就是生成一個請求,然後把它發送到ser ...
  • 區別 OpenId: Authentication :認證 Oauth: Aurhorize :授權 輸入賬號密碼,QQ確認輸入了正確的賬號密碼可以登錄 認證 下麵需要勾選的覆選框(獲取昵稱、頭像、性別) 授權 OpenID 當你需要訪問A網站的時候,A網站要求你輸入你的OpenId,即可跳轉到你的 ...
  • 前言 預計是通過三篇來將清楚asp.net core 3.x中的授權:1、基本概念介紹;2、asp.net core 3.x中授權的預設流程;3、擴展。 在完全沒有概念的情況下無論是看官方文檔還是源碼都暈乎乎的,希望本文能幫到你。不過我也是看源碼結合官方文檔看的,可能有些地方理解不對,所以只作為參考 ...
  • 簡介 基於生產者消費者模式,我們可以開發出線程安全的非同步消息隊列。 知識儲備 什麼是生產者消費者模式? 為了方便理解,我們暫時將它理解為垃圾的產生到結束的過程。 簡單來說,多住戶產生垃圾(生產者)將垃圾投遞到全小區唯一一個垃圾桶(單隊列),環衛將垃圾桶中的垃圾進行處理(消費者)。就是一個生產者消費者 ...
  • 很多時候,需要對類中的方法進行一些測試,來判斷是否能按要求輸出預期的結果。 C#提供了快速創建單元測試的方法,但單元測試不僅速度慢不方便,大量的單元測試還會拖慢項目的啟動速度。 所以決定自己搞個方便的測試用例。 控制台一句話調用。 測試用例.註冊並Print(EnumEx.Name); 結果畫面: ...
  • 常成員函數不能改變數據成員的值,例如定義坐標類Coordinate,成員函數changeX():void Coordinate::changeX(){ x = 10;}雖然changeX()沒有參數,但是它隱含一個參數——this指針:void Coordinate::changeX(Coordin... ...
  • 因為新冠肺炎疫情,診所還沒復工。這是在家用手機敲的,代碼顯示有問題。等復工以後在電腦上改,各位先湊和看吧。 支持向量機(Support Vector Machine, SVM)是一種基於統計學習的模式識別的分類方法,主要用於模式識別。所謂支持向量指的是在分割區域邊緣的訓練樣本點,機是指演算法。就是要找 ...
x