開放平台架構指南

• 2022 年 6 月 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文檔，如下所示：

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

4.2 分類原則

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

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

4.3 版本管理

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

# 老版本
//openapi.test.com/order/create_order
# 新版本
//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 //openapi.domain.com/query_order獲得訂單狀態。如果商戶希望儘快知道訂單狀態，可以定時輪詢訂單查詢介面，但是效率低且浪費資源。系統主動通知商戶訂單的狀態，能有效解決這個問題。商戶需要按規範開發介面，接受指定格式的數據。數據推送增加系統了的複雜性，又會造成兩個問題：

• 業務狀態的順序性

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

• 推送數據可能遺漏

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

4.7 API文檔

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