11條軍規,讓你的介面設計無可挑剔

来源:https://www.cnblogs.com/JavaPub/p/18210860
-Advertisement-
Play Games

作為後端工程師,多數情況都是給別人提供介面,寫的好不好使你得重視起來。 最近我手頭一些活,需要和外部公司對接,我們需要提供一個介面文檔,這樣可以節省雙方時間、也可以防止後續扯皮。這是就要考驗我的介面是否規範化。 1. 介面名稱清晰、明確 顧名思義,介面是做什麼的,是否準確、清晰?讓使用這一眼就能知道 ...


作為後端工程師,多數情況都是給別人提供介面,寫的好不好使你得重視起來。

74076262d8f14d5390e1ba557e0296a0

最近我手頭一些活,需要和外部公司對接,我們需要提供一個介面文檔,這樣可以節省雙方時間、也可以防止後續扯皮。這是就要考驗我的介面是否規範化。

介面設計規範JavaPub

1. 介面名稱清晰、明確

顧名思義,介面是做什麼的,是否準確、清晰?讓使用這一眼就能知道這個介面在做什麼,力求言簡意賅。比如:查詢用戶信息,簡單明瞭。

img

2. 介面路徑規整

介面地址,也就是介面的 URL 路徑。當別人調用你的介面,就是通過 URL 配合請求時參數來調用。比如: /api/user/queryById 。一般來說,介面地址的命名也要可以大概看出介面的作用,比如前面這個介面,它是作用使用:通過用戶id查詢用戶信息

除了介面路徑,還需要指明介面的功能變數名稱或IP。以 http 協議為例、埠是 8080,當我請求 javapub 的用戶中心信息時:

https://javapub.net.cn:8080/api/user/queryById

4677eb13-b696-43be-b530-60766742a4e3

3. 請求方式規範

請求方式常用的有如下幾種:

  • GET(SELECT):從伺服器取出資源,通常用於查詢數據(一項或多項)。
  • POST(CREATE):在伺服器新建一個資源,通常用在新增、修改、刪除操作。
  • PUT(UPDATE):在伺服器更新資源,通常用於更新數據(客戶端提供改變後的完整資源)。
  • PATCH(UPDATE):在伺服器更新資源,通常用於修改部分數據(客戶端提供改變的屬性)。
  • DELETE(DELETE):從伺服器刪除資源,通常用於刪除數據。

這麼多請求方式,多數中小公司只用 GET 和 POST,可能還有些公司只用 POST。但是選擇合適的請求方式可以提升開發效率、並且讓我們的介面更容易復用。

不管用哪種,一定要寫清楚。

eb21c081-f26c-4c8c-9197-4a35573e8b04

4. 介面詳細說明

如果是非常簡單的介面,通過介面名就可以瞭解個大概。如果是一些非常複雜的介面,就一定要添加詳細說明文檔,包括功能描述、請求參數、請求相應參數等信息。

力求言簡意賅,通過入參、做了什麼動作、返回哪些值。

006r3PQBjw1fb5h84baewj306404lmx9

5. 編寫介面請求示例

介面文檔需要提供介面示例,介面實例是為了幫助調用者理解介面的使用方法和調用流程,快速開始調試程式。一般是 CURL 格式的示例。

curl javapub.net.cn

img

6. 引入介面版本管理

隨著功能開發的日趨完善,可能對介面做出修改更新,例如添加、刪除時變更參數,或者修改返回值的格式。這些新變更可能影響用戶的 API 使用體驗,造成現有客戶端無法使用。

https://javapub.net.cn:8080/api/user/v1/queryById

https://javapub.net.cn:8080/api/user/v2/queryById

56d7cbc6-0b2c-4a90-ac37-a8e65c040d47

7. 維護介面文檔版本更新

如果介面發生了變更,介面文檔也要做出相應調整,維護文檔。比如錯誤碼更新、參數類型變更等,要明確記錄。

日期 變更內容 責任人
2028-03-01 創建介面文檔,定義基本數據結構。 JavaPub
2028-05-10 V2.0用戶中心介面更新 王哥

b4fe3684d20e97fa311ca213c8dc7ea9

8. 明確請求頭有哪些

介面文檔,要寫清楚請求頭信息,比如:有許可權校驗的介面請求,在請求頭中 apiKey。還有一些參數是 JSON 的,要設置 application/json

  • Accept:指定客戶端能夠接收的內容類型,如:Accept: text/plain, text/html
  • Authorization:一般存放令牌信息,如:Authorization: Basic QzPhZGRpbjpvcGVuIHNlc2FtZQ==
  • Cookie:存放 Cookie 信息。
  • User-Agent:指定客戶端信息,作為服務端處理時定製化。
  • Accept-Encoding:指定客戶端允許的數據壓縮格式,如 gzip、deflate 等。

image-20240521104426851

9. 介面安全

有些介面參數涉及到隱私和敏感數據、需要參數加密做好脫敏處理和說明。此外,還要做好介面授權訪問,防止出現拖庫、擊穿等P0問題。

image-20240521104647299

10. 介面測試

在編寫介面文檔時,編寫測試案例也要給出測試數據,包括請求參數和返回結果。讓調用者有一個預期,節省溝通成本。

image-20240521105043027

11. 定義錯誤碼

介面文檔,一定要錯誤碼,錯誤碼作為程式重要的參考,讓下游知道什麼時候做什麼動作。比如:當查詢不到用戶信息時,可以提示它跳轉到註冊頁面。

錯誤碼 名稱 說明
1001 參數錯誤 參數不合法
1002 資料庫錯誤 資料庫請求出錯

image-20240521104901378


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

-Advertisement-
Play Games
更多相關文章
  • title: Vue 3 組件基礎與模板語法詳解 date: 2024/5/24 16:31:13 updated: 2024/5/24 16:31:13 categories: 前端開發 tags: Vue3特性 CompositionAPI Teleport Suspense Vue3安裝 組件 ...
  • 貪吃蛇作為一款極其經典且廣受歡迎的小游戲,是早期 Windows 電腦和功能手機(特別是諾基亞手機)流行度極高的小游戲,是當時功能手機時代最具代表性的游戲之一。游戲的基本規則和目標十分簡單,但卻極具吸引力,讓人欲罷不能。本博文我們用 Python 編寫屬於自己的貪吃蛇游戲,一起來體驗一下編程的樂趣與... ...
  • 當開發與Linux環境下MySQL資料庫交互的Java應用程式時,理解MySQL中的大小寫敏感性可以避免潛在的錯誤和問題。本指南深入探討了MySQL中的大小寫敏感設置,比較了5.7和8.0版本,併為Java開發者提供了最佳實踐。 1 理解MySQL中的大小寫敏感性 預設情況下,MySQL在Windo ...
  • 1. Spring6 對 集成MyBatis 開發運用(附有詳細的操作步驟) @目錄1. Spring6 對 集成MyBatis 開發運用(附有詳細的操作步驟)每博一文案2. 大概的實現步驟概述3. 詳細實現操作步驟4. Spring配置文件的 import,導入外部xml 配置5. 總結:6. 最 ...
  • 1 為啥要折騰搭建一個專屬圖床? 技術大佬寫博客都用 md 格式,要在多平臺發佈,圖片就得有外鏈 後續如博客遷移,國內博客網站如掘金,簡書,語雀等都做了防盜鏈,圖片無法遷移 2 為啥選擇CloudFlare R2 跳轉:https://dash.cloudflare.com/ 有白嫖額度 免費 CD ...
  • 實時識別關鍵詞是一種能夠將搜索結果提升至新的高度的API介面。它可以幫助我們更有效地分析文本,並提取出關鍵詞,以便進行進一步的處理和分析。 該介面是挖數據平臺提供的,有三種模式:精確模式、全模式和搜索引擎模式。不同的模式在分詞的方式上有所不同,適用於不同的場景。 首先是精確模式。這種模式會儘量將句子 ...
  • Java JUC&多線程 基礎完整版 目錄Java JUC&多線程 基礎完整版1、 多線程的第一種啟動方式之繼承Thread類2、多線程的第二種啟動方式之實現Runnable介面3、多線程的第三種實現方式之實現Callable介面4、多線的常用成員方法5、線程的優先順序6、守護線程7、線程的讓出8、線 ...
  • 本文介紹基於Python語言,遍歷文件夾並從中找到文件名稱符合我們需求的多個.txt格式文本文件,並從上述每一個文本文件中,找到我們需要的指定數據,最後得到所有文本文件中我們需要的數據的合集的方法~ ...
一周排行
    -Advertisement-
    Play Games
  • 一:背景 1. 講故事 前些天有位朋友找到我,說他們的程式會偶發性的卡死一段時間,然後又好了,讓我幫忙看下怎麼回事?窗體類的程式解決起來相對來說比較簡單,讓朋友用procdump自動抓一個卡死時的dump,拿到dump之後,上 windbg 說話。 二:WinDbg 分析 1. 主線程在做什麼 要想 ...
  • 功能說明 使用ListView時,希望可以在單元格顯示圖片或其他控制項,發現原生的ListView不支持,於是通過拓展,實現ListView可以顯示任意控制項的功能,效果如下: 實現方法 本來想著在單元格裡面實現控制項的自繪的,但是沒找到辦法,最後是通過在單元格的錶面顯示對應控制項的,浮於錶面達到目的。 實 ...
  • 由於.NET Framework 4.0 是比較古老的版本,只有New Relic 7.0以下的版本才會支持.NET Framework 4.0的引用程式。 Technical support for .NET Framework 4.0 or lower 你可以參考這個官方Install New ...
  • 前言 隨著 DEV24.1.3 的發佈,XAF Blazor 中的屬性編輯器(PropertyEditor)也進行了很大的改動,在使用體驗上也更接近 WinForm 了,由於進行了大量的封裝,理解上沒有 WinForm 直觀,所以本文通過對屬性編輯器的原理進行解析,並對比新舊版本中的變化,使大家能夠 ...
  • OPC基金會提供了OPC UA .NET標準庫以及示常式序,但官方文檔過於簡單,光看官方文檔和示常式序很難弄懂OPC UA .NET標準庫怎麼用,花了不少時間摸索才略微弄懂如何使用,以下記錄如何從一個控制台程式開發一個OPC UA伺服器。 安裝Nuget包 安裝OPCFoundation.NetSt ...
  • 今天在技術群里,石頭哥向大家提了個問題:"如何在一個以System身份運行的.NET程式(Windows Services)中,以其它活動的用戶身份啟動可互動式進程(桌面應用程式、控制台程式、等帶有UI和互動式體驗的程式)"? 我以前有過類似的需求,是在GitLab流水線中運行帶有UI的自動化測試程 ...
  • .Net 中提供了一系列的管理對象集合的類型,數組、可變列表、字典等。從類型安全上集合分為兩類,泛型集合 和 非泛型集合,傳統的非泛型集合存儲為Object,需要類型轉。而泛型集合提供了更好的性能、編譯時類型安全,推薦使用。 ...
  • 在以前我做程式的時候,一般在登錄視窗裡面顯示程式名稱,登錄視窗一般設置一張背景圖片,由於程式的名稱一般都是確定的,所以也不存在太大的問題,不過如果客戶定製不同的系統的時候,需要使用Photoshop修改下圖層的文字,再生成圖片,然後替換一下也可以了。不過本著減少客戶使用繁瑣性,也可以使用空白名稱的通... ...
  • 一:背景 1. 講故事 在dump分析的過程中經常會看到很多線程卡在Monitor.Wait方法上,曾經也有不少人問我為什麼用 !syncblk 看不到 Monitor.Wait 上的鎖信息,剛好昨天有時間我就來研究一下。 二:Monitor.Wait 底層怎麼玩的 1. 案例演示 為了方便講述,先 ...
  • 目錄前言學習參考過程總結: 前言 做個自由仔。 學習參考 ChatGpt; https://www.cnblogs.com/zhili/p/DesignPatternSummery.html(大佬的,看了好多次) 過程 原由: 一開始只是想查查鏈式調用原理,以為是要繼承什麼介面,實現什麼方法才可以實 ...