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
  • PasteSpider是什麼? 一款使用.net編寫的開源的Linux容器部署助手,支持一鍵發佈,平滑升級,自動伸縮, Key-Value配置,項目網關,環境隔離,運行報表,差量升級,私有倉庫,集群部署,版本管理等! 30分鐘上手,讓開發也可以很容易的學會在linux上部署你得項目! [從需求角度介 ...
  • SQLSugar是什麼 **1. 輕量級ORM框架,專為.NET CORE開發人員設計,它提供了簡單、高效的方式來處理資料庫操作,使開發人員能夠更輕鬆地與資料庫進行交互 2. 簡化資料庫操作和數據訪問,允許開發人員在C#代碼中直接操作資料庫,而不需要編寫複雜的SQL語句 3. 支持多種資料庫,包括但 ...
  • 在C#中,經常會有一些耗時較長的CPU密集型運算,因為如果直接在UI線程執行這樣的運算就會出現UI不響應的問題。解決這類問題的主要途徑是使用多線程,啟動一個後臺線程,把運算操作放在這個後臺線程中完成。但是原生介面的線程操作有一些難度,如果要更進一步的去完成線程間的通訊就會難上加難。 因此,.NET類 ...
  • 一:背景 1. 講故事 前些天有位朋友在微信上丟了一個崩潰的dump給我,讓我幫忙看下為什麼出現了崩潰,在 Windows 的事件查看器上顯示的是經典的 訪問違例 ,即 c0000005 錯誤碼,不管怎麼說有dump就可以上windbg開幹了。 二:WinDbg 分析 1. 程式為誰崩潰了 在 Wi ...
  • CSharpe中的IO+NPOI+序列化 文件文件夾操作 學習一下常見的文件、文件夾的操作。 什麼是IO流? I:就是input O:就是output,故稱:輸入輸出流 將數據讀入記憶體或者記憶體輸出的過程。 常見的IO流操作,一般說的是[記憶體]與[磁碟]之間的輸入輸出。 作用 持久化數據,保證數據不再 ...
  • C#.NET與JAVA互通之MD5哈希V2024 配套視頻: 要點: 1.計算MD5時,SDK自帶的計算哈希(ComputeHash)方法,輸入輸出參數都是byte數組。就涉及到字元串轉byte數組轉換時,編碼選擇的問題。 2.輸入參數,字元串轉byte數組時,編碼雙方要統一,一般為:UTF-8。 ...
  • CodeWF.EventBus,一款靈活的事件匯流排庫,實現模塊間解耦通信。支持多種.NET項目類型,如WPF、WinForms、ASP.NET Core等。採用簡潔設計,輕鬆實現事件的發佈與訂閱。通過有序的消息處理,確保事件得到妥善處理。簡化您的代碼,提升系統可維護性。 ...
  • 一、基本的.NET框架概念 .NET框架是一個由微軟開發的軟體開發平臺,它提供了一個運行時環境(CLR - Common Language Runtime)和一套豐富的類庫(FCL - Framework Class Library)。CLR負責管理代碼的執行,而FCL則提供了大量預先編寫好的代碼, ...
  • 本章將和大家分享在ASP.NET Core中如何使用高級客戶端NEST來操作我們的Elasticsearch。 NEST是一個高級別的Elasticsearch .NET客戶端,它仍然非常接近原始Elasticsearch API的映射。所有的請求和響應都是通過類型來暴露的,這使得它非常適合快速上手 ...
  • 參考delphi的代碼更改為C# Delphi 檢測密碼強度 規則(仿 google) 仿 google 評分規則 一、密碼長度: 5 分: 小於等於 4 個字元 10 分: 5 到 7 字元 25 分: 大於等於 8 個字元 二、字母: 0 分: 沒有字母 10 分: 全都是小(大)寫字母 20 ...