“淘寶” 開放平臺介面設計思路

架構文摘發表於2021-09-25

最近對接的開放平臺有點多,像淘寶、京東、快手、抖音等電商平臺的開放平臺基本對接了個遍,什麼是CRUD BODY也許就是這樣的吧!!!

雖然對接各大開放平臺沒啥技術含量,但我們也得學點東西不是,不能白對接哈!經過這幾天的整理,腦子裡大概有了個開放平臺介面的設計套路,故整理成文章方便有需要的時間去實現自己的開放平臺介面。

開放平臺比較關注的幾個點:

  • 易用性:介面設計要簡潔,請求引數要見名知意,使服務商能快速接收,為使用者提供服務
  • 安全性:開放平臺介面是暴露在外網,必須保證使用者資料的安全
  • 穩定性:開放平臺介面是給上游的服務商使用,必須保證穩定為服務商應用提供服務
  • ...

服務商應用

開放平臺可以分為幾大部分:

  1. 接入指南:幫助服務商接入開放平臺
  2. 介面文件:幫助服務商的開發人員,實現業務功能
  3. 應用:服務商應用在開放平臺的身份標示

服務商接入開放平臺的首要步驟就是建立應用,有了服務商應用平臺內部就能辨別服務商的身份,這樣就能很方便的做限流、許可權控制等。

基本屬性

服務商應用一般有appid、appsecret、授權回撥地址這三個基本的屬性:

  • appid: 服務商應用的唯一標識
  • appsecret:服務商應用的金鑰簽名、驗證身份時用到
  • 授權回撥地址:授權時會用到

授權認證

授權不是開放平臺對服務商應用的授權 ,而是需要開放平臺的客戶(使用者)對服務商應用的授予,比如ERP應用,也就是淘寶的店鋪商家對應用進行授權,使其能夠拉取到店鋪的訂單來完成訂單履約。

淘寶授權頁

所以授權需要三個角色才能完成:

  • 開放平臺

    • 提供授權頁面,引導客戶完成服務商應用的授權
    • 客戶完成授權後,跳轉到服務商應用提供的授權回撥地址同時帶上授權資訊
  • 客戶:在開放平臺提供的授權頁面中,完成對服務商應用的授權
  • 服務商應用:接收開放平臺回撥的授權資訊,完成務商應用與客戶的繫結關係、儲存授權資訊
當然也可以使用appid + appsecret 直接認證服務商應用的身份,這種適合沒有第三方的時候,資料都是屬於開放平臺的,跟客戶沒有半點關係,也就不存在需要客戶授權的問題。

OAuth2授權機制

OAuth2是一套授權標準,現在網際網路做授權基本都用它,如github登陸 、微信公眾號授權等都是基於OAuth2的應用。

如果不瞭解OAuth2可以參考我以前的文章:

一文帶你瞭解 OAuth2 協議與 Spring Security OAuth2 整合!

授權流程

請求引數

請求引數分兩類:系統引數業務引數

  • 系統引數:每次API呼叫都必需攜帶的引數
  • 業務引數:開放平臺根據不同的業務,提供的引數。

業務引數根據業務來定,先說系統引數一般包含:

  • appid:服務商應用唯一標識
  • appsecret: 服務商應用金鑰
  • timestamp:時間戳
  • sign:請求籤名
系統引數使用url引數傳遞

業務引數

業務引數是呼叫開放平臺介面時傳遞的請求引數,如一次訂單查詢介面,要實現按訂單狀態的維度查詢訂單,那麼訂單查詢介面就需要接收status引數,然後去查庫後返回訂單資料。

業務引數的載體,常用的如:application/jsonapplication/x-www-form-urlencode等。

業務引數使用post請求引數的方式傳遞,同時也需要參與簽名,後面說簽名會提到

請求籤名

對請求籤名的目的就是防止資料被篡改,常見的md5sha都可以用來做為簽名演算法,理論上只要保證雙方能夠生成簽名和驗籤就行,像支付寶這類高安全級別的應用就是使用的非對稱加密,雙方各生成一對私鑰和公鑰,然後交換公鑰用於驗籤即可。

生成簽名的方式自行定義,這裡列舉一個常見的簽名生成方式:

sign = appsecret + appid + timestamp + 業務引數(排序後) + appsecret

虛擬碼


String appid = "abcd";
String appsecret = "12345";
Long timestamp = 948758686
//有序map,按key的值排序
Map<String, Object> requestBody = new TreeMap<>();
requestBody.put("a", 1);
requestBody.put("b",21);
requestBody.put("c", 2);
//轉換成json字串
String jsonBody = JSON.toJSONString(requestBody);
String sign  = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);

驗籤

驗籤步驟與生成簽名的步驟類似,仿程式碼如下:


String appid = request.getParameter("appid");
String appsecret = request.getParameter("appsecret");
Long timestamp = request.getParameter("timestamp");
//拿出請求的業務引數,轉成TreeMap
Map<String, Object> requestBody = new TreeMap<>(JSON.parseObject("post請求引數"));
//轉換成json字串
String jsonBody = JSON.toJSONString(requestBody);
String sign  = DigestUtils.md5hex(appsecret + appid + timestamp + jsonBody + appsecret);
String originSign =  request.getParameter("sign");
if(Objects.equals(sign ,originSign )){
  //驗證簽名成功
}else{
  //驗證簽名失敗
}

總結

以上就是開放平臺介面設計的一些思路,其實也是對接開放平臺多了, 對那些開放平臺對接的一些基本的套路的一些整理,希望有朝一日能用上。

對接開放平臺的時候遇到的問題不少,有的平臺有SDK有的是直接是restapi,有SDK的平臺對接起來還是挺幸福的,下期給大家整個平臺SDK的設計。

在下藝名驚天霸戈(驚天bug),一枚喜歡製造bug的Java程式設計師,目前正在準備出道的路上。。。,記得給我點個贊,鼓勵鼓勵!

相關文章