如何設計一個良好的介面

来源:https://www.cnblogs.com/wangjiming/archive/2019/01/14/10256546.html
-Advertisement-
Play Games

在設計介面時,有很多因素要考慮,如介面的業務定位,介面的安全性,介面的可擴展性、介面的穩定性、介面的跨域性、介面的協議規則、介面的路徑規則、介面單一原則、 介面過濾和介面組合等諸多因素,本篇文章將簡要分析這些因素。 一 規範性建議 1.職責原則 在設計介面時,必須明確介面的職責,即介面類型,介面應解 ...


      在設計介面時,有很多因素要考慮,如介面的業務定位,介面的安全性,介面的可擴展性、介面的穩定性、介面的跨域性、介面的協議規則、介面的路徑規則、介面單一原則、

介面過濾和介面組合等諸多因素,本篇文章將簡要分析這些因素。

 

一 規範性建議


1.職責原則

在設計介面時,必須明確介面的職責,即介面類型,介面應解決什麼業務問題等

2.單一性原則

在明確介面職責的條件下,儘量做到介面單一,即一個介面只做一件事,而非兩件以上。很多非資深介面設計者,在設計介面時,

總認為介面所做的事越多,越牛叉,這是非常嚴重的錯誤認識。

3.協議規範

在設計介面時,應明確介面協議,是採用HTTP協議,HTTPS協議還是FTP協議,要根據具體情況來定。

(1)FTP協議(File Transfer Protocol,簡稱FTP),是一套標準的文件傳輸協議,用於傳輸文件,如.txt,.csv等,一般文件傳輸,採用FTP協議

(2)HTTP協議,適用一般對安全性要求比較低或沒要求的業務情景

(3)HTTPS=HTTP+SSL,適用於對安全性要求較高的業務情景

4.路徑規則

由於api獲取的是一種資源,所以網址中儘量為名詞,而非動詞

 /api/v1.0/Pruduct/2019

/api/v1.0/Users/2019

5.http請求方式

介面基本訪問協議:get(獲取),post(新增),put(修改)和delete(刪除)

get     /users:列出所有用戶

get    /users/id:根據id獲取用戶

post   /user:新增用戶

put      /user/id:根據用戶id更新用戶

delete   /user/id:根據用戶id刪除用戶

6.功能變數名稱

一般地,功能變數名稱分為主功能變數名稱和專有功能變數名稱,主功能變數名稱適合api長期不變或變化較少的業務,專有功能變數名稱是解決具體的專有業務的

以百度舉例:

(1)主功能變數名稱:www.baidu.com

(2)產品服務類

 百度文庫:https://wenku.baidu.com/

 百度知道:https://zhidao.baidu.com/

 百度資訊: https://zhidao.baidu.com/

(3)市場活動類

百度公益:http://gongyi.baidu.com

百度logo:http://logo.baidu.com/

百度世界:https://baiduworld.baidu.com

7.跨域考慮

在明確功能變數名稱的情況下,一定要考慮介面是否跨域,以及跨域應採用的技術手段等

8.api版本

對於介面的url,應加版本號http://api.demo.com/v{d}/,如 ,其中d表示版本號,如v1.0,v2.0

例子:獲取產品號為2019,版本號為v1.0的版本號的產品信息

/api/v1.0/Pruducts/2019

9.適度過濾信息

當記錄數比較多時(如 SELECT * FROM TBName),因適當添加一些條件對數據進行過濾,如TOP,分頁,分組,排序和WHERE條件等

下麵是一些常見的參數。

?limit=100:返回100條數據

?offset=101:從第101條數據開始返回

?page=10:指第10頁

per_page=100:每頁100條數據

?sortby=name:排序欄位

?order=desc:降序

?group=groupName:分組

?producy_type=1:篩選條件

10.返回數據格式

返回數據格式,一般包括三個欄位:

(1)失敗情況(狀態碼、錯誤碼和錯誤描述)

{

“status”:0,//狀態碼 0-表示失敗,1-表示成功

“error_code”:”2003”,//錯誤碼,一般在設計時定義

“error_des”:”身份驗證失敗”//錯誤描述,一般在設計時定義

}

(2)成功情況(標識id,數據對象,狀態碼)

{

     ”sid“:”sh20190111”,//token id

     ”users“:{

                   ”id“:”al201901111341”,//用戶id

                  “name”:”Alan_beijing”,//用戶名

                   “addr”:”用戶地址”

},

     “status”:1//狀態碼 0-表示失敗,1-表示成功

}

11.安全性原則

介面暴露的考慮,介面併發量的考慮,介面防攻擊的考慮,介面跨域的考慮等

12.可擴展性原則

在設計介面時,充分考慮介面的可擴展性。

13.定義api界限

任何api,從許可權上,可歸結為匿名api和非匿名api,前者不需要驗證,後者需要驗證

14.定義api返回碼

在api設計時,要定好api返回碼,如

1 --授權過期

404--未找到資源

500--內部伺服器錯誤

600--賬號被鎖

二 反規範性建議


      存在這樣一種業務場景:某個介面需要返回多個api介面組合的結果 ,在類似的業務場景下,所設計的介面,具有一定的反規範性。

1.Request

data:[
    {url:'api1',type:'get',data:{...}},
    {url:'api2',type:'get',data:{...}},
]

2.Responce

{
    status:0,
    msg:'',
    data:[
        {status:1,msg:'',data:[]},
        {status:1,msg:'',data:{}}
    ]
}

 

三  實例


      假設存在這樣一個一個業務:一個ERP系統,需要提供兩個介面,一個是用戶訪問介面(需要驗證),另一個是用戶註冊介面(不需要驗證)。

根據本篇文章一,二部分的建議,我們來設計滿足該業務需求的介面

(一)定義統一參數

1.定義統一輸入參數

2.定義統一輸出參數

3.定義統一錯誤碼

(二)定義介面授權類別

如下為定義介面授權類別

(三)用戶介面

1.用戶註冊

2.Request

3.Responce

4.code示例

Request:
{
    "mobile":13636595499,
    "verify_code":"987654",
    "pwd":"123456"
}

Responce:
(1)error
{
   "status":0,
   "error_code":1001"error_desc":"手機驗證碼已失效"
}
(2)succed
{
   "sid":"sh201901141529",
   "uid":1,
   "status":1
}

(四)用戶登錄

1.登錄介面概述

 

2.Request

3.Responce

4.Code

Responce:
1.error
{
   "status":0,
   "error_code":1002,
   "error_desc":"密碼錯誤"
}
2.succeed
{
   "sid":"sh201901141529",
   "user":{
         "id":1,
     "username":"",
      age:0,
      gender:0
   },
   "status":1
}

四  WebApi相關文章


【01】淺談HTTP在WebApi開發中的運用

【02】聊聊WebApi體繫結構

【03】詳解WebApi參數的傳遞

【04】詳解WebApi測試和PostMan

【05】淺談WebApi Cores

【06】詳解WebApi 異常處理

【07】用WebAPI寫個基於EF的CURD

【08】淺談WebAPI身份認證

【09】詳解系列化和模型綁定

【10】淺談WebApi如何配合Mvc有效工作

【11】淺談API Reference

【12】淺談介面在軟體架構中的作用

【13】淺談WebApi和WebService的比較

【14】如何設計一個良好的介面

 

五  版權區


 

  • 感謝您的閱讀,若有不足之處,歡迎指教,共同學習、共同進步。
  • 博主網址:http://www.cnblogs.com/wangjiming/。
  • 極少部分文章利用讀書、參考、引用、抄襲、複製和粘貼等多種方式整合而成的,大部分為原創。
  • 如您喜歡,麻煩推薦一下;如您有新想法,歡迎提出,郵箱:[email protected]
  • 可以轉載該博客,但必須著名博客來源。

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

-Advertisement-
Play Games
更多相關文章
  • 問題 父級元素不能被子元素內容撐開的解決辦法,父級元素沒有高度的解決辦法。 今天在寫網頁時遇到如下圖問題,解決問題後自己做個隨筆,希望幫到更多的學前端的童鞋! 問題圖片 問題描述 最外層的父級元素不能自適應高度-不能隨對象撐開沒有高度 當在對象內的盒子使用了float後,導致對象本身不能被撐開自適應 ...
  • 此插件是一位外國人寫的,官網API地址:https://photo-sphere-viewer.js.org/#methods 我只是記錄下我在使用此插件時用到的方法和相關屬性,以防以後忘記 1.按要求在頁面中引入文件後,使用以下方式調用,其它配置 jq選中的元素最後返回的是一個document,不 ...
  • 一.組件模板和樣式 類似於頁面,自定義組件擁有自己的 wxml 和模板 wxss 樣式。 1.組件模板 組件的寫法和頁面的寫法相同,組件模板與組件數據結合後生成的數節點, 將被插入到組件的引用位置。在組件模板中提供一個<slot> 節點,用於承載組件 引用時候提供的子節點。 例如: <view cl ...
  • 函數是由事件驅動的或者當它被調用時執行的可重覆使用的代碼塊。 實例1: 效果:通過點擊按鈕“點我”,會彈出"Hello World!"的提示框! 1.JavaScript 基本函數語法 函數就是包裹在花括弧中的代碼塊,前面使用了關鍵詞 function: 當調用該函數時,會執行函數內的代碼。 可以在 ...
  • 今天,棧長分享下 Zookeeper 的集群安裝及配置。 下載 下載地址:http://zookeeper.apache.org/ 下載過程就不說了,我們下載了最新的 。 安裝 1、上傳安裝包 把下載的最新的包(如:zookeeper 3.4.11.tar.gz)上傳到伺服器,上傳的方式也不多說了。 ...
  • 個人博客原文: "創建型模式:單例模式" 簡介 姓名 :單例模式 英文名 :Singleton Pattern 價值觀 :我的生活我主宰(只允許自己實例化,不願意被其他對象實例化) 個人介紹 : Ensure a class has only one instance, and provide a ...
  • 一、引言 最近懶勁又上來了,隔了幾天沒有學習,最近的博文閱讀量也比較少,不過還是希望自己堅持下去,相信水滴石穿,量變總會引起質變的。 今天要學習的是適配器模式,顧名思義,適配器模式是將兩個不相容的介面進行適配,類似轉換器的功能。 先看一個例子,我們一個播放器,它有一個播放功能(繼承一個播放介面,只有 ...
  • 一、環境 eclipse mar jdk 1.7 apache-maven-3.3.3 註意: 1> eclipse mar 已集成maven插件,我們只需要配置成自己的maven即可,類似eclipse集成tomcat 2> maven3.3+版本需要的jdk1.7以上的版本 二、本地安裝和配置m ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發(一):使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說,近來想嘗試開發一款安卓APP,考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP,畢竟是使用Visual Studio開發工具,使用起來也比較的順手,結合微軟官方的教程進行了安卓 ...
  • 前言 QuestPDF 是一個開源 .NET 庫,用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫,它徹底改變了我們生成 PDF 文檔的方 ...
  • 項目地址 項目後端地址: https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址: ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址: http://tree ...
  • 話不多說,直接開乾 一.下載 1.官方鏈接下載: https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe,運行開始下載SQL server; 二. ...
  • 前言 隨著物聯網(IoT)技術的迅猛發展,MQTT(消息隊列遙測傳輸)協議憑藉其輕量級和高效性,已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫,為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog支持多種接收器用於日誌存儲,增強器用於添加屬性,LogContext管理動態屬性,支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項,適用於不同需求。 ...
  • 目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據,爬取信息時需要模擬瀏覽器行為,否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下: 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • 1.前言 什麼是熱更新 游戲或者軟體更新時,無需重新下載客戶端進行安裝,而是在應用程式啟動的情況下,在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR,Xlua,ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles,Addressable, ...
  • 本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺,其實像阿裡雲,騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後,它會送 ...
  • 通過以下方式可以高效,並保證數據同步的可靠性 1.API設計 使用RESTful設計,確保API端點明確,並使用適當的HTTP方法(如POST用於創建,PUT用於更新)。 設計清晰的請求和響應模型,以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證,確保接收到的數據符合預期格 ...