編寫令人愉悅的API介面 一

2021-10-12 17:29:22 字數 3051 閱讀 7201

api介面是服務端與客戶端溝通的橋梁.較好的api設計能減少客戶端與服務端的聯調時間,更加關注於自己本身**的優化與業務層的邏輯.

良好的api介面應該從這下面幾個方向進行優化

準確的api協議

準確的內容型別

統一的返回型別以及異常處理

良好的介面版本控制體系

api介面路徑盡量簡短統一

效能與安全

get: 從伺服器上獲取乙個具體的資源或者乙個資源列表。

post: 在伺服器上建立乙個新的資源。

put: 以整體的方式更新伺服器上的乙個資源。

patch: 只更新伺服器上乙個資源的乙個屬性。

delete: 刪除伺服器上的乙個資源。

head : 獲取乙個資源的元資料,如資料的雜湊值或最後的更新時間。

options : 獲取客戶端能對資源操作的資訊。

其中get,post,put,patch,delete這五種協議在日常crud開發中最為常用

以使用者模組的業務場景分析

//獲取使用者列表(分頁)

public r selectlist(usersearch usersearch)

//獲取單個使用者資訊

public r selectone(@pathvariable("id") string id)

//新增使用者

public r add(@requestbody user user)

//修改使用者

public r upp(@pathvariable("id") string id,@requestbody user user)

//刪除使用者

public r del(@pathvariable("id") string id)

//修改使用者部分屬性(這裡舉例修改使用者姓名)

public r upppart(@pathvariable("id") string id,@partbody string username)

**例項

此傳輸格式時,資料會以鍵值對的形式傳輸

當為post請求時,瀏覽器把form資料封裝到http body中,不可用@requestbody註解修飾接收實體.

multipart/form-data 型別

**例項

**例項

此傳輸格式時,資料主體是序列化後的json字串

當為get請求時,?傳參方式可傳值,引數名為實體內的屬性值,用@requestbody註解修飾,可直接獲取到引數名對應的入參

當為post請求時候,body中,不可用@requestbody註解修飾接收實體

統一返回類是必須的.統一以後客戶端就只需要乙個公共解析類即可.對應的業務模型放在泛型result物件中,客戶端就只需要用對應的解析器解析剩下的部分.

返回類r

@data

public class rimplements serializable

private static final long serialversionuid = 1l;

//標識請求是否成功

private boolean success;

//操作成功或者失敗後,客戶端的提示資訊

private string message;

//http狀態碼或者自定義的異常狀態碼

private integer code;

//當前請求的返回時間

private long timestamp = system.currenttimemillis();

//返回給客戶端的業務主體資料,可為列表或者單個物件

private t result;

}

封裝返回類工具類 resultutil

主要封裝一些常用的成功,失敗或者回參的靜態方法,在控制層返回前端時,只需要返回 resultutil.***() 對應的方法即可

resultutil **例項

錯誤碼及訊息 errorcode

用列舉型別定義errorcode,在程式異常時可直接呼叫 error(integer code, string msg) 返回給客戶端對應的業務異常或者其他系統異常

errorcode **例項

異常攔截類 globalexceptionhandler

定義 globalexceptionhandler 類,用@controlleradvice修飾,可實現統一的異常攔截,**示例中攔截了常見的一些異常型別.

//參照格式

//exceptionhandler 指定需要攔截的異常型別

@exceptionhandler(value = exception.class)

@responsebody

//httpservletrequest 可得到對應的請求引數,exception 物件可得到對應的異常輸出,可記錄在日誌中便於排查,再返回給客戶端相對友好的提示

globalexceptionhandler **例項

業務異常類 busines***ception

定義業務異常類是為了一些比較特殊的情況,此類繼承runtimeexception,在複雜的業務中也可定義多個業務異常型別,業務**現一些邏輯異常就可使用這個業務異常丟擲,比如字效驗密碼錯誤或者某欄位數值超出臨界內等等情況.可與上面的errorcode類結合使用,定義code應該避免一些系統預設的 http狀態碼

busines***ception **例項

Python編寫API介面

要求通過進行訪問,引數a aa b bb c 00 1.編寫url 瀏覽器會自動將?後面識別為引數。urlpatterns url r calc aptest.calc,name calc 2.編寫view 瀏覽器返回json型別結果 import json defcalc request a re...

如何打造乙個令人愉悅的前端開發環境(四)

express 結合 webpack 實現hmr 本篇檔案主要講結合 webpack 和 express 實現前後端熱更新開發,如果你還不太了解webpack推薦閱讀 webpack 官網文件 what 什麼是 webpack dev server webpack dev server 是乙個輕量的...

API介面的編寫(ios為例)

採用.net平台的實現api的方式有很多,剛來公司時用的是一般處理程式字尾為 ashx 或者一面程式 aspx來返回json 然後是mvc的框架返回json,好吧最後終於迎來了web api。拋開.net這個框架,其實api的實質不外乎就是返回你需要的資料資訊 以json格式展示 或者xml格式 而...