開放平臺架構指南

編碼磚家發表於2022-06-14
架構

1.前言

2010年前，大型社交網站如騰訊QQ、新浪微博都搭建了開放平臺。中小型網際網路公司接入開放平臺，能夠獲取社交平臺的海量使用者，有效的降低獲客成本，獲得社交平臺的其他能力。對於使用者而言，用一個社交帳號登入各種網站或APP，體驗也會更好。後來，許多行業如電商、金融等都開放了業務核心API。這些行業的競爭非常激烈，公司希望通過開放平臺與合作伙伴保持更高效的協作，實現資源交換或者流量變現。

廣義的開放平臺是個龐大的結構，它站在核心業務系統的前面，承接著所有的流量。公司所有的客戶端比如Web站點、手機APP、智慧硬體都對接開放平臺API，只是各自的許可權不同，可以訪問的資源不同。狹義的開放平臺只是開啟了一扇門，讓合作伙伴進來參與業務互動。從業務層面上看，開放平臺僅僅是流量渠道之一。

本文重點討論的是狹義的開放平臺。

2.需求分析

2.1 總體需求

業務系統相當於酒店，開放平臺是專門招待外賓的特殊客房，合作伙伴（以下統稱商戶）就是外賓。外賓進入酒店有專門的通道，不和其他客戶的共用。外賓可以在房間睡覺、點餐，但是不能去其他房間串門。主觀上，酒店希望接納更多的外賓，但是招待能力始終有上限，因此一定要限制外賓活動的頻率，否則沒有足夠的人力招待其他的住客。在系統設計上，開放平臺有四個重要的要求：

  • 1）介面訪問授權：商戶帳號僅能訪問被授權的介面，也不允許訪問到其他商戶的資源。
  • 2）介面訪問限流：商戶訪問介面必須限流，不能對公司的核心繫統造成衝擊。
  • 3）內部業務隔離：商戶最忌諱介面出入引數頻繁變化，內部系統要做好業務規劃和多版本設計，儘可能保證介面出入引數不變動。
  • 4）資料安全：加密敏感資料，比如使用者手機號、銀行卡號。
2.2 平臺角色

開放平臺的使用者只有兩個：商戶和平臺管理員，平臺管理員可以劃分為超級管理員、商務經理、產品經理。

  • 1）超級管理員：擁有最高系統管理許可權。
  • 2）商務經理：商務經理負責與商戶洽談合作事宜，稽核商戶資料的真實性，推動合作的進度。
  • 3）產品經理：產品經理根據商務經理與商戶簽訂的合同，確定產品流程的細節，解答商戶的業務疑問，聯合開發人員協助商戶對接API。如果有需要，甚至要為商戶設計新的API。
2.3 專案構成
  • 1）開放API

商戶的開發水平和意願不一樣，接入方式可以分為三種：

  1. 全API：商戶端技術人員開發前端頁面，後端呼叫開放平臺API，包裝為自己的前端介面，串聯這些前端介面完成產品流程。
  2. 內嵌H5：商戶端技術人員在產品的合適位置嵌入開放平臺提供的H5地址，使用者可以開啟這個地址，完成產品流程。
  3. 內嵌SDK：開放平臺提供Android或IOS平臺的SDK，商戶端技術人員自行整合在產品中，完成產品流程。
  • 2）商戶服務系統

商戶服務系統至少包含商戶入駐、引數配置功能，部分業務還需要佣金結算、訂單統計等功能。

  1. 商戶入駐：商戶先提交企業資料，商務經理稽核通過之後，商戶才能正常訪問開放API。
  2. 引數配置： 配置對接開放API的一些引數，比如接入方式。
  • 3）商戶管理系統

商戶管理系統主要用於查詢、修改、編輯商戶資訊、審批商戶的配置資訊以及其他輔助功能。

3.系統架構

3.1 系統架構

採用成熟的分散式元件實現架構，如下圖所示：

3.2 業務邊界

為了業務的整體可控，核心業務系統不應該迎合開放平臺的變化，而是開放平臺適配核心系統。開放平臺的業務邊界是只做渠道功能，不做核心業務，通過呼叫核心系統的介面完成業務操作。

3.3 資料閉環


核心系統沒有意願儲存商戶ID或者其他與渠道有關的資料，資料閉環是指商戶發起的請求（比如建立訂單），先儲存在開放平臺的資料庫，開放平臺再向核心系統發起請求。這份資料並不需要特別完整，但是至少包含業務主鍵。當有需要的時候，通過查詢核心系統介面來彌補缺失的資料。自主冗餘資料的好處有兩點：1.減少了呼叫鏈，加快介面查詢速度；2.更容易實現根據商戶ID分頁查詢資料、訂單統計、佣金結算等功能。

4 API設計

4.1 RESTful風格

介面設計遵循 RESTful 協議，它有下面的特性：

  • 資源是由 URI 來指定，URI 中可以包含請求引數。
  • 對資源的操作如獲取、建立、修改和刪除，要採用 HTTP 協議提供的動作標識 如GET、POST、PUT 和 DELETE 等。
  • 資源的表現形式可以是XML、HTML、JSON，多數採用JSON。

採用RESTful API的好處有三點：

  • 基於HTTP協議，輕量級，使用廣泛
  • 介面設計面向資源，具有自解釋性。
  • 以 XML，JSON 做資料交換，格式簡單。

在實際的運用中，嚴格遵循 RESTful 協議有下面三點缺陷：

  • 1）HTTP動詞過多

開發人員使用過多的HTTP動詞，心智負擔較大；用動詞標記操作資源滿足不了複雜的業務需求，最後還得通過介面名稱來區分；某些請求如 PUT、DELETE 可能被中間層裝置過濾掉。

  • 2）URL支援引數

URL裡面包含引數佔位符比如GET /Api/Orders/{id}/OrderItems/{id}，閱讀性不佳。如果根據 URL 來統計介面呼叫次數，分析系統需要額外處理相同地址不同引數的情況。

  • 3）HTTP狀態碼錶現力不足

通過20X、30X、4XX、5XX等有限的響應碼無法表達複雜的業務狀態。

為了解決以上三點缺陷，建議介面遵循如下規範：

  • HTTP 動詞僅採用 GET、POST。
  • URL裡面不允許使用引數佔位符。
  • 返回結果採用自定義的業務狀態碼。

通常每個介面都有一個資源地址，為了更靈活些，可以設計為僅有一個入口地址，在引數裡面增加介面名稱，來區分不同的業務操作。參考淘寶API文檔，如下所示：

請求地址：http://gw.api.taobao.com/router/rest
請求引數:

名稱 型別 必須 描述
method String 是 API介面名稱，例如:taobao.user.buyer.get
timestamp String 是 時間戳，格式為yyyy-MM-dd HH:mm:ss，時區為GMT+8，例如：2015-01-01 12:00:00
4.2 分類原則

遵循MECE原則，根據業務領域進行介面分類。

MECE（發音me see）是Mutually Exclusive Collectively Exhaustive的縮寫，意思是“相互獨立，完全窮盡”，也就是對問題的分析，能夠做到不重複、不遺漏，從而直達問題的核心，並找到問題的解決方法。由《金字塔原理》作者巴巴拉·明託1973年發明，也是麥肯錫思維過程的一條基本準則。

4.3 版本管理

不同版本的相同介面，將版本號標識統一後置，如下所示：

# 老版本
http://openapi.test.com/order/create_order
# 新版本
http://openapi.test.com/order/create_order/v2
4.4 返回資料

所有介面的返回資料都採用固定的JSON格式，如下所示：

{
  "code":200,
  "msg":"OK",
  "data":{
    "order_id":"2012120112304512",
    "product_name":"男士衛衣"
  }
}
  • code：父編號，一般是請求成功、異常等標識。
  • msg：父編號資訊，一般是請求結果的資訊提示。
  • data：具體的業務資料。
4.5 安全措施
  • 1）介面MD5簽名

  1. 對所有API請求引數（包括公共引數和業務引數，但除去sign引數、值為空和值為陣列型別的引數），根據引數名稱的ASCII碼錶順序升序排列，比如：foo=1, bar=2, foo_bar=3, foobar=4排序後的順序是bar=2, foo=1, foo_bar=3, foobar=4。

  2. 將排好序的引數名、引數值用&拼裝在一起，採用utf-8編碼，比如：bar=2&foo=1&foo_bar=3&foobar=4。

  3. 在拼裝的字串尾部加上預先分配的金鑰值 secret_value 後，再進行MD5演算法摘要，如：md5(bar=2&foo=1&foo_bar=3&foobar=4&secret=secret_value)。

  • 2）資料加密

加密敏感資料比如使用者資訊，常見加密演算法可以是RSA或者AES。

  • 3）IP白名單

在介面訪問的前置層，只允許在白名單裡的IP的請求。商戶通過商戶服務系統自行管理IP白名單。

4.6 資料推送

資料推送是指系統主動通知商戶資料的變化，滿足部分商戶對資料的實時性要求。舉個例子，商戶建立訂單成功，通過訂單查詢介面GET http://openapi.domain.com/query_order獲得訂單狀態。如果商戶希望儘快知道訂單狀態，可以定時輪詢訂單查詢介面，但是效率低且浪費資源。系統主動通知商戶訂單的狀態，能有效解決這個問題。商戶需要按規範開發介面，接受指定格式的資料。資料推送增加系統了的複雜性，又會造成兩個問題：

  • 業務狀態的順序性

訂單有多個狀態而且有業務順序性，由於網路延遲的未知性，訂單狀態資料可能無序的推送給商戶，這時商戶可以通過業務邏輯去保證訂單狀態的正確性。

  • 推送資料可能遺漏

系統推送資料一般採用MQ非同步傳送，即便有手段保證訊息不丟失，但是商戶的網路故障依然會造成推送失敗。這種故障有兩個方式解決：1.系統在T+1時段提供T日的對賬檔案，裡面包含訂單號和訂單狀態，商戶根據對賬檔案批量更新遺失的訂單號狀態；2.商戶定時輪詢訂單狀態。

4.7 API文件

為了便於商戶查閱和測試API，採用 https://www.apifox.cn/ 管理API文件。

相關文章