為什么需要搭建開放平臺(tái)

增強(qiáng)產(chǎn)品能力

開放平臺(tái)能夠讓三方開發(fā)者和合作伙伴開發(fā)新的應(yīng)用或服務(wù)，增加原有SaaS產(chǎn)品能力。這樣就可以滿足更多用戶需求，從而提高用戶的滿意度和黏性。

促進(jìn)創(chuàng)新

三方開發(fā)者能夠在SaaS標(biāo)準(zhǔn)產(chǎn)品的基礎(chǔ)上，創(chuàng)造新的解決方案，為平臺(tái)帶來創(chuàng)新的業(yè)務(wù)模式，這些可能為SaaS企業(yè)帶來更多的盈利機(jī)會(huì)。

構(gòu)建生態(tài)系統(tǒng)

開放平臺(tái)能夠建立一個(gè)以SaaS標(biāo)準(zhǔn)產(chǎn)品為中心的生態(tài)系統(tǒng)，吸引開發(fā)者、合作伙伴和其他相關(guān)方參加，共同構(gòu)建一個(gè)互惠互利的生態(tài)圈。

降低開發(fā)和運(yùn)營(yíng)成本

通過邀請(qǐng)三方開發(fā)者來創(chuàng)造和擴(kuò)展產(chǎn)品能力，他們可以有效分擔(dān)SaaS企業(yè)的開發(fā)、運(yùn)營(yíng)成本，更聚焦于核心產(chǎn)品的優(yōu)化和創(chuàng)新。

開放平臺(tái)的服務(wù)對(duì)象是誰？

SaaS企業(yè)的開放平臺(tái)通常包括以下關(guān)鍵用戶角色：

第三方開發(fā)者

他們期望能快速入駐開放平臺(tái)，并構(gòu)建應(yīng)用，通過用戶訂購應(yīng)用獲取收益。因此，他們需要API文檔、SDK工具和開發(fā)者后臺(tái)，幫助開發(fā)者構(gòu)建、測(cè)試和部署應(yīng)用，并且利用平臺(tái)資源推廣自己的應(yīng)用。

定制客戶

定制客戶一般為擁有自研能力的企業(yè)客戶，有定制化功能需求，例如與內(nèi)部系統(tǒng)（如ERP、CRM）進(jìn)行打通，實(shí)現(xiàn)企業(yè)自身的業(yè)務(wù)流程。

平臺(tái)運(yùn)營(yíng)人員

平臺(tái)運(yùn)營(yíng)人員需要為三方開放者和企業(yè)客戶服務(wù)，幫助他們解決問題，因此，需要客戶管理，應(yīng)用申請(qǐng)流程管理、服務(wù)配置、參數(shù)配置、角色分配、財(cái)務(wù)對(duì)賬管理等產(chǎn)品能力。

開放平臺(tái)的運(yùn)營(yíng)流程

SaaS開放平臺(tái)的運(yùn)營(yíng)流程涉及平臺(tái)的管理和維護(hù)，為企業(yè)客戶、三方開發(fā)者提供服務(wù)，包括吸引與管理三方開發(fā)者，提供必要的開發(fā)工具和支持，對(duì)開發(fā)者創(chuàng)建的應(yīng)用進(jìn)行審核和上線管理，通過數(shù)據(jù)監(jiān)控和分析評(píng)估平臺(tái)的健康度和用戶活躍度，確保提供有效的服務(wù)支持，和維護(hù)平臺(tái)的安全和合規(guī)性。

下圖展示了開放平臺(tái)的整體運(yùn)營(yíng)流程，實(shí)際的開放平臺(tái)項(xiàng)目可以基于該流程做變更。

開放平臺(tái)整體架構(gòu)設(shè)計(jì)

管理后臺(tái)

層針對(duì)不同角色，提供不同的管理后臺(tái)：

• 開發(fā)者后臺(tái)：為三方開發(fā)者提供的工作臺(tái)，包括應(yīng)用管理、API接入、開發(fā)工具、數(shù)據(jù)分析和測(cè)試工具等。
• 平臺(tái)運(yùn)營(yíng)后臺(tái)：用于平臺(tái)運(yùn)營(yíng)團(tuán)隊(duì)管理整個(gè)系統(tǒng)的工作臺(tái)，包括客戶管理、權(quán)限控制、計(jì)費(fèi)管理、系統(tǒng)監(jiān)控等功能。
• 商家后臺(tái)：SaaS企業(yè)客戶的后臺(tái)系統(tǒng)，主要用于訂購應(yīng)用市場(chǎng)的三方應(yīng)用，授權(quán)應(yīng)用，并使用其提供的服務(wù)能力。

服務(wù)層

服務(wù)層為上層的管理后臺(tái)提供核心服務(wù)能力：

• 開發(fā)者接入：提供API文檔、SDK工具、開發(fā)指南，應(yīng)用的注冊(cè)、管理等。
• 運(yùn)營(yíng)管理：包括平臺(tái)用戶信息管理、權(quán)限設(shè)置、用戶資料管理。對(duì)開發(fā)者提交的應(yīng)用進(jìn)行審核，確保應(yīng)用的質(zhì)量和安全性。管理平臺(tái)計(jì)費(fèi)、結(jié)算，收集和分析平臺(tái)的運(yùn)營(yíng)數(shù)據(jù)。
• 監(jiān)控中心：包括服務(wù)器、應(yīng)用、網(wǎng)絡(luò)、數(shù)據(jù)庫、安全、中間件和存儲(chǔ)監(jiān)控。這些功能確保開放平臺(tái)的穩(wěn)定性、性能和安全，通過實(shí)時(shí)監(jiān)控、告警支持技術(shù)團(tuán)隊(duì)進(jìn)行有效管理和維護(hù)。

API網(wǎng)關(guān)

API網(wǎng)關(guān)是整個(gè)開放平臺(tái)的流量入口，它提供的能力確保了平臺(tái)操作的安全、穩(wěn)定和高效管理。

業(yè)務(wù)開放能力

業(yè)務(wù)開放能力由各個(gè)業(yè)務(wù)域系統(tǒng)提供，這些開放能力提供了核心業(yè)務(wù)數(shù)據(jù)/功能的交互能力。

開放能力設(shè)計(jì)

開放能力可以分為以下幾種類型：

• 前端擴(kuò)展：開發(fā)者可創(chuàng)建個(gè)性化的前端H5/小程序頁面，滿足企業(yè)客戶不同場(chǎng)景不同行業(yè)的需求。
• API 接口/消息推送：API接口允許開發(fā)者通過定義的接口與平臺(tái)系統(tǒng)交互，實(shí)現(xiàn)數(shù)據(jù)和功能的集成，例如商品創(chuàng)建接口。消息推送是指平臺(tái)系統(tǒng)主動(dòng)通知三方系統(tǒng)，如訂單狀態(tài)變更通知。
• 后端擴(kuò)展：開發(fā)者可以通過擴(kuò)展點(diǎn)，自由嵌入自定義流程節(jié)點(diǎn)，構(gòu)建個(gè)性化的業(yè)務(wù)邏輯。
• 數(shù)據(jù)模型擴(kuò)展：允許將三方系統(tǒng)的數(shù)據(jù)模型整合到平臺(tái)系統(tǒng)中，在平臺(tái)系統(tǒng)中可以查看或處理三方數(shù)據(jù)。

以商品系統(tǒng)為例，列出不同類型開放能力的使用場(chǎng)景：

• 前端擴(kuò)展：頁面串聯(lián)、定制商詳組件、定制商品詳情、定制B端管理頁面。
• API 接口/消息推送：商品發(fā)布接口、同步分店接口、查詢商品詳情接口、商品價(jià)格修改接口、商品修改接口、商品屬性接口、商品上下架接口、商品類目接口、商品創(chuàng)建消息、商品變更消息。
• 后端擴(kuò)展：商品校驗(yàn)類擴(kuò)展點(diǎn)（例如，商品創(chuàng)建時(shí)，校驗(yàn)商品編碼是否符合定制需求的規(guī)范）、商品的定制信息計(jì)算擴(kuò)展點(diǎn)（例如，通過外部接口計(jì)算出商品重量信息）。
• 數(shù)據(jù)模型擴(kuò)展：商品模型擴(kuò)展并存儲(chǔ)個(gè)性化的字段信息。

開放API設(shè)計(jì)原則

RESTful風(fēng)格API

RESTful API 是一種遵循 REST 原則的 API 設(shè)計(jì)方式。REST 是一組約束條件和原則，由 Roy Fielding 在 2000 年的博士論文中提出。

RESTful API 的設(shè)計(jì)依賴于網(wǎng)絡(luò)協(xié)議，主要是 HTTP，并且它使用 HTTP 的原生功能（比如 HTTP 的動(dòng)詞和狀態(tài)碼）來執(zhí)行操作。以下是 RESTful API 的一些主要特點(diǎn)：

• 面向資源：在REST架構(gòu)中，所有內(nèi)容都被視為"資源"，每個(gè)"資源"都有一個(gè)獨(dú)特的URI（統(tǒng)一資源標(biāo)識(shí)符）。
• 無狀態(tài)：RESTful API不保存狀態(tài)，這意味著每個(gè)請(qǐng)求都應(yīng)包含執(zhí)行請(qǐng)求所需的信息。服務(wù)器不會(huì)保存客戶端的任何信息。
• 統(tǒng)一接口：RESTful API應(yīng)該有一個(gè)統(tǒng)一的接口，客戶端和服務(wù)器基于接口交互，實(shí)現(xiàn)解耦。交互通常通過HTTP動(dòng)詞實(shí)現(xiàn)，如GET（獲取資源）、POST（創(chuàng)建資源）、PUT（更新資源）、DELETE（刪除資源）。

RESTful API的三個(gè)顯著優(yōu)勢(shì)如下：

• 它建立在HTTP協(xié)議上，協(xié)議簡(jiǎn)潔易用，得到了廣泛的應(yīng)用。
• 接口設(shè)計(jì)以資源為中心，讓接口易于理解和使用，比較直觀。
• 數(shù)據(jù)交換采用XML或JSON格式，大大簡(jiǎn)化了數(shù)據(jù)的處理和傳輸過程。

但嚴(yán)格遵循 RESTful API風(fēng)格，也有一些缺陷：

HTTP協(xié)議的動(dòng)詞受限

當(dāng)業(yè)務(wù)需求變得復(fù)雜時(shí)，僅依賴于HTTP的動(dòng)詞方法來對(duì)資源操作，可能不足以滿足需求，這時(shí)往往需要通過接口名稱來進(jìn)一步區(qū)分。此外，一些特定的HTTP請(qǐng)求，如PUT和DELETE，可能會(huì)在網(wǎng)絡(luò)傳輸過程中被某些防火墻設(shè)備攔截。

URL包含參數(shù)，可讀性差

在URL中嵌入?yún)?shù)占位符（例如：GET /Api/Orders/{id}/OrderItems/{id}）會(huì)降低其可讀性。如果需要基于URL統(tǒng)計(jì)接口的調(diào)用次數(shù)，需要對(duì)具有相同URL的不同參數(shù)進(jìn)行額外的處理。

HTTP狀態(tài)碼的表達(dá)性差

使用如20X、30X、4XX、5XX等標(biāo)準(zhǔn)的HTTP狀態(tài)碼，不足以描述復(fù)雜的業(yè)務(wù)場(chǎng)景的狀態(tài)。

建議接口設(shè)計(jì)遵循以下準(zhǔn)則：

• 限制HTTP方法的使用，僅采用GET和POST。
• 避免在URL中包含參數(shù)占位符，盡量使用URL的參數(shù)傳參。
• 使用自定義的業(yè)務(wù)狀態(tài)碼來提供更豐富的響應(yīng)信息。

API分組原則

根據(jù)業(yè)務(wù)領(lǐng)域，對(duì)開放API進(jìn)行分組。例如店鋪API、商品API、庫存API、訂單API、物流API、客戶API、營(yíng)銷API。

SaaS標(biāo)準(zhǔn)產(chǎn)品一般都基于DDD進(jìn)行架構(gòu)設(shè)計(jì)，根據(jù)業(yè)務(wù)領(lǐng)域組織開放API，是普遍采用的最佳實(shí)踐。當(dāng)需要改進(jìn)或變更某個(gè)特定業(yè)務(wù)領(lǐng)域的功能時(shí)，開發(fā)人員可以直接找到相關(guān)的API組進(jìn)行修改，不會(huì)影響到其他領(lǐng)域的API。

對(duì)于三方開發(fā)人員，可以更容易地找到與某個(gè)業(yè)務(wù)功能相關(guān)的API，因?yàn)樗鼈兺ㄟ^業(yè)務(wù)域的劃分邏輯組織在一起。

版本管理

為了統(tǒng)一和清晰地標(biāo)識(shí)不同版本的相同接口，建議將版本號(hào)放置在接口路徑的末尾，示例如下：

• 老版本：http://api.xxxx.com/item/create_item
• 新版本：http://api.xxxx.com/item/create_item/v2

返回?cái)?shù)據(jù)

每個(gè)接口的響應(yīng)數(shù)據(jù)，應(yīng)遵循統(tǒng)一的JSON或XML格式規(guī)范，并且至少應(yīng)包含以下關(guān)鍵字段：

• 狀態(tài)碼 (code)：表示請(qǐng)求的總體結(jié)果，通常用于標(biāo)識(shí)操作的成功或異常狀態(tài)。
• 消息 (msg)：提供關(guān)于狀態(tài)碼的詳細(xì)描述，以幫助理解請(qǐng)求的具體結(jié)果。
• 數(shù)據(jù) (data)：包含與請(qǐng)求相關(guān)的具體業(yè)務(wù)信息和數(shù)據(jù)。

{
	"code":200,
	"msg":"OK",
	"data":{
	"item_id":"123456",
	"product_name":"奶油蛋糕"
	}
}

安全措施

接口簽名

為開發(fā)者分配AccessKey（開發(fā)者標(biāo)識(shí)，確保唯一）和SecretKey（用于接口加密，確保不易被窮舉，生成算法不易被猜測(cè)）。

按照請(qǐng)求參數(shù)名的字母升序排列非空請(qǐng)求參數(shù)（包含AccessKey），使用URL鍵值對(duì)的格式（即key1=value1&key2=value2…）拼接成字符串A。

在字符串A最后拼接上Secretkey得到字符串B。

對(duì)字符串B進(jìn)行MD5運(yùn)算，得到Sign值。請(qǐng)求時(shí)，攜帶參數(shù)AccessKey和Sign，只有擁有合法的身份AccessKey和正確的簽名Sign才能放行。這樣就解決了身份驗(yàn)證和參數(shù)篡改問題，即使請(qǐng)求參數(shù)被劫持，由于獲取不到SecretKey（僅作本地加密使用，不參與網(wǎng)絡(luò)傳輸），也無法偽造合法的請(qǐng)求。

數(shù)據(jù)加密

敏感數(shù)據(jù)，如用戶信息，應(yīng)使用加密算法進(jìn)行保護(hù)，常用的加密方法包括RSA和AES。

訪問控制

在接口訪問的API網(wǎng)關(guān)，應(yīng)設(shè)置訪問控制，僅允許來自被商家授權(quán)的白名單的請(qǐng)求。商家可以通過商家后臺(tái)系統(tǒng)自主管理其白名單。

消息推送

消息推送是平臺(tái)主動(dòng)通知三方系統(tǒng)，提供數(shù)據(jù)更新的一種機(jī)制，滿足三方系統(tǒng)對(duì)信息實(shí)時(shí)性的需求。例如，當(dāng)商家成功創(chuàng)建訂單后，三方系統(tǒng)可以通過訂單查詢接口來獲取訂單的當(dāng)前狀態(tài)。

三方系統(tǒng)若想實(shí)時(shí)獲取訂單狀態(tài)，可以選擇定時(shí)查詢接口，但這樣效率低并消耗大量資源。通過系統(tǒng)主動(dòng)推送訂單狀態(tài)信息，可以有效地解決這一問題。但消息推送也帶來了一些挑戰(zhàn)：

• 順序性問題：訂單可能經(jīng)歷多個(gè)狀態(tài)，且這些狀態(tài)在業(yè)務(wù)上有特定順序。網(wǎng)絡(luò)延遲可能導(dǎo)致狀態(tài)送達(dá)三方系統(tǒng)時(shí)，順序錯(cuò)亂，這時(shí)三方系統(tǒng)需要通過校驗(yàn)訂單狀態(tài)，判斷變更是否符合業(yè)務(wù)邏輯，來確保訂單狀態(tài)的準(zhǔn)確性。
• 消息丟失風(fēng)險(xiǎn)：目前系統(tǒng)通常采用消息隊(duì)列異步發(fā)送消息推送，盡管有消息中間件的機(jī)制確保消息的可靠性，但三方系統(tǒng)出現(xiàn)網(wǎng)絡(luò)問題，仍有可能導(dǎo)致推送失敗。解決方案：三方系統(tǒng)可以定期全量查詢訂單狀態(tài)，對(duì)雙邊的訂單狀態(tài)進(jìn)行對(duì)賬處理，確保數(shù)據(jù)的完整性。