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

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

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

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

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

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

服務商應用

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

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

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

基本屬性

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

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

授權認證

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

淘寶授權頁

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

  • 開放平臺

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

OAuth2授權機制

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

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

[一文帶你瞭解 OAuth2 協議與 Spring Security OAuth2 整合！
](https://mp.weixin.qq.com/s?__...;mid=2247488722&idx=1&sn=9d0ec7d5b9a16611073eb31d07afd99e&chksm=9f47781aa830f10c3e6baefc6ebba7501183dba8f65f810ee3d748c85b75b57ab6279c340b7d&token=1300302581&lang=zh_CN#rd)

授權流程

請求引數

請求引數分兩類：系統引數、業務引數：

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

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

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

業務引數

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

業務引數的載體，常用的如：application/json、application/x-www-form-urlencode等。

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

請求籤名

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

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

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程式設計師，目前正在準備出道的路上。。。，記得給我點個贊，鼓勵鼓勵！

相關文章