摘要：的特點(diǎn)通過(guò)狀態(tài)碼能知道操作結(jié)果，通過(guò)方法能知道操作類型增刪改查，通過(guò)能知道操作的資源對(duì)象。平臺(tái)只通過(guò)狀態(tài)碼來(lái)判斷操作成功與否。

今年，我的任務(wù)是為公司的私有云平臺(tái)（ PaaS ）開(kāi)發(fā)對(duì)應(yīng)的云服務(wù)平臺(tái)（我們稱之為插件平臺(tái)），這個(gè)云服務(wù)平臺(tái)的主要任務(wù)，是為云平臺(tái)接入一些服務(wù)，服務(wù)包括但不限于mysql、redis、cdn等存儲(chǔ)服務(wù)，天氣預(yù)報(bào)等http服務(wù)。這個(gè)系列文章，希望總結(jié)本人在開(kāi)發(fā)這個(gè)平臺(tái)時(shí)的得與失。
下面將云服務(wù)平臺(tái)簡(jiǎn)稱為平臺(tái)（插件平臺(tái)），所接入的服務(wù)，簡(jiǎn)稱為第三方服務(wù)（插件）

統(tǒng)一接入方案，是指可以幫助插件平臺(tái)更快接入第三方服務(wù)的一種統(tǒng)一方案

首先要回答的第一個(gè)問(wèn)題，是為什么需要插件平臺(tái)：

云平臺(tái)，是一個(gè)強(qiáng)大的開(kāi)發(fā)平臺(tái)，幫助開(kāi)發(fā)人員完成從機(jī)器申請(qǐng)，項(xiàng)目部署，維護(hù)（動(dòng)態(tài)擴(kuò)容……）等一系列操作，像阿里云、騰訊云，都是國(guó)內(nèi)這方面做的比較大的平臺(tái)。一個(gè)完整的云平臺(tái)，必然會(huì)接入一些第三方服務(wù)。簡(jiǎn)單的做法，當(dāng)然是云平臺(tái)自己完成這個(gè)事情。但隨著平臺(tái)及人員規(guī)模的擴(kuò)大，一個(gè)很合理的分工，是將接入、管理、維護(hù)第三方服務(wù)的功能，作為一個(gè)獨(dú)立的模塊、平臺(tái)。這樣符合軟件開(kāi)發(fā)的解耦原則，具體來(lái)講，會(huì)有以下收益：

當(dāng)云平臺(tái)要升級(jí)改造時(shí)，不會(huì)直接影響到第三方服務(wù)。過(guò)往的邏輯鏈路，是云平臺(tái)綁定了 N 個(gè)第三方服務(wù)，而有了插件平臺(tái)，這個(gè)鏈路變成：云平臺(tái)-> 插件平臺(tái) -> N個(gè)第三方服務(wù)。過(guò)往的情況是，云平臺(tái)的一些變動(dòng)，N個(gè)第三方服務(wù)可能要跟著修改。而現(xiàn)在，只需要由插件平臺(tái)統(tǒng)一做變更，而插件平臺(tái)到N個(gè)第三方服務(wù)這條鏈路，可以保持之前約定的規(guī)則不變。另外，云平臺(tái)的一些部署、變更，也能盡量少地影響到插件服務(wù)。

插件平臺(tái)更專注于插件這個(gè)事情，可以把插件接入、維護(hù)這件事情做得更加極致。

一個(gè)插件平臺(tái)，可以對(duì)接多個(gè)云平臺(tái) 。作為一個(gè)中間站，插件平臺(tái)可以按照它和每個(gè)云平臺(tái)的約定進(jìn)行對(duì)接，然后再按照插件平臺(tái)自己的標(biāo)準(zhǔn)流程，和多個(gè)第三方服務(wù)進(jìn)行對(duì)接。這樣，每個(gè)云平臺(tái)上，等于都能接入插件平臺(tái)提供的第三方服務(wù)。

能與開(kāi)源社區(qū)結(jié)合，打造閉環(huán)“廣大開(kāi)發(fā)人員開(kāi)源組件->孵化成熟->成為云平臺(tái)第三方服務(wù)”，從而提供更多豐富的插件。這是我們的實(shí)踐結(jié)果。插件平臺(tái)不僅為云平臺(tái)提供第三方服務(wù)，同時(shí)，我們還開(kāi)發(fā)了這么一個(gè)網(wǎng)站，每個(gè)開(kāi)發(fā)人員，可以到這個(gè)網(wǎng)站開(kāi)源自己寫(xiě)的組件，如果覺(jué)得合適，還可以將這個(gè)組件轉(zhuǎn)成云平臺(tái)適用的第三方服務(wù)。

其次，解答統(tǒng)一接入方案的重要性和必要性：說(shuō)到底是為了兩個(gè)字,"效率"。沒(méi)有統(tǒng)一接入方案時(shí)，每來(lái)一個(gè)新的第三方服務(wù)，云平臺(tái)開(kāi)發(fā)人員就需要和第三方服務(wù)開(kāi)發(fā)人員討論確定接口，然后一方（第三方服務(wù)）寫(xiě)接口，一方（平臺(tái)）寫(xiě)調(diào)用邏輯，最后進(jìn)行聯(lián)調(diào)，非常麻煩。有沒(méi)辦法改善呢？當(dāng)然是有，就是提供一個(gè)統(tǒng)一的接入方案，不管是什么第三方服務(wù)，都按照這套規(guī)范。平臺(tái)的邏輯是通用的，要接入新的第三方服務(wù)時(shí)，無(wú)需開(kāi)發(fā)。第三方服務(wù)要按照規(guī)范開(kāi)發(fā)幾個(gè)接口，再通過(guò)頁(yè)面配置信息，然后就能接入了。從之前的兩方聯(lián)調(diào)模式，變成單邊適配。

首先做第一層抽象，以一個(gè)MySql服務(wù)為例，用戶可能需要：創(chuàng)建、刪除、變更、查看（基本參數(shù)）一個(gè)MySql實(shí)例。MySql服務(wù)在插件平臺(tái)正式上線前，平臺(tái)需要知道，如何調(diào)用MySql服務(wù)的哪些接口以做增刪改差服務(wù)資源。因此，統(tǒng)一接入，其實(shí)就是解決平臺(tái)和第三方服務(wù)如何對(duì)接這四個(gè)接口的問(wèn)題。

調(diào)用第三方服務(wù)這幾個(gè)接口時(shí)，如何判定操作是成功的（特別是創(chuàng)建、刪除操作）

創(chuàng)建一個(gè)第三方服務(wù)實(shí)例，不同的用戶，需要?jiǎng)?chuàng)建的實(shí)例類型，可能是不一樣的。如何統(tǒng)一？例如，有些項(xiàng)目需要?jiǎng)?chuàng)建帶從庫(kù)的 MySql ，有些項(xiàng)目不用。

平臺(tái)發(fā)送請(qǐng)求時(shí)，要帶上哪些參數(shù)。不同服務(wù)，所需參數(shù)不一樣，怎么在不改平臺(tái)帶代碼的情況下，讓平臺(tái)根據(jù)服務(wù)的不同，帶上不同的參數(shù)。

操作成功及失敗時(shí)，分別要返回哪些信息給用戶。如何從第三方服務(wù)的接口響應(yīng)內(nèi)容中，提取對(duì)應(yīng)的信息

如何讓第三方服務(wù)開(kāi)發(fā)者可以自己調(diào)試協(xié)議，而無(wú)需平臺(tái)開(kāi)發(fā)介入

在第三方服務(wù)正式上線時(shí)，平臺(tái)管理員如何快速檢查接口是否符合約定

既然稱之為統(tǒng)一方案，那么必定就是要做這幾件事情：制訂一套行之有效的標(biāo)準(zhǔn)流程，定義簡(jiǎn)潔清晰的接口規(guī)范，提供相關(guān)的接入工具。

最終的流程如下

開(kāi)發(fā)者按照約定，開(kāi)發(fā)服務(wù)的增刪改查接口

在云服務(wù)平臺(tái)填寫(xiě)服務(wù)信息，使用測(cè)試工具測(cè)試ok后，提交管理員審核

管理員審核并上線

這是很常見(jiàn)的一個(gè)接入流程。下面我們具體看看，我們是如何更簡(jiǎn)潔解決上面提到的問(wèn)題。

第三方服務(wù)在收到請(qǐng)求時(shí)，當(dāng)然需要判定請(qǐng)求來(lái)源是否合法，是否來(lái)自插件平臺(tái)。我們提供了兩種鑒權(quán)方式，供第三方服務(wù)開(kāi)發(fā)者選擇：

keystone
插件平臺(tái)、公司的私有云平臺(tái)，鑒權(quán)都基于 openstack 自身的 keystone 模塊，該模塊為服務(wù)間交互的鑒權(quán)，提供了一種統(tǒng)一方案。因此，和平臺(tái)交互的第三方服務(wù)，也可以采用該方式。

這樣有兩個(gè)好處：

從云平臺(tái)、插件平臺(tái)、第三方服務(wù)，自上而下，鑒權(quán)都是統(tǒng)一、標(biāo)準(zhǔn)、可信任

不用自己造輪子

password
平臺(tái)和服務(wù)之間約定一個(gè)密碼，平臺(tái)發(fā)起請(qǐng)求時(shí)，會(huì)在 Header 中帶上該密碼，服務(wù)在收到請(qǐng)求時(shí)，判斷該密碼是否和約定一致

這兩個(gè)方式，前者略重，但安全可靠，后者略輕，卻快速簡(jiǎn)單。 keystone 是 openstack 的標(biāo)準(zhǔn)方式，它的好處自不必說(shuō)，而 password 這個(gè)方式，是考慮到我們是個(gè)私有云，可以減低安全要求，同時(shí)更要盡量快速簡(jiǎn)單地接入第三方服務(wù)。

和下面要展開(kāi)的“請(qǐng)求參數(shù)格式"一樣，這里的關(guān)鍵，是如何抽離區(qū)分，平臺(tái)的統(tǒng)一參數(shù)及不同服務(wù)之間的差異參數(shù)。什么意思呢？哪些是統(tǒng)一的參數(shù)，哪些是差異參數(shù)。例如，不管是何種第三方服務(wù)，創(chuàng)建一個(gè)資源后，都需要返回操作的明確結(jié)果，資源的id。而其他的返回參數(shù)，則存在差異，例如一個(gè) mysql 服務(wù)，還需要告知，資源的 url ，端口號(hào)，用戶名，密碼等，而圖片服務(wù)，則可能提供一個(gè)存儲(chǔ)路徑 url 即可。

我們是這樣做的：請(qǐng)求、響應(yīng)設(shè)計(jì)，遵循 RESTful 設(shè)計(jì)。RESTful 的特點(diǎn)：通過(guò) HTTP 狀態(tài)碼能知道操作結(jié)果，通過(guò) HTTP 方法能知道操作類型（增刪改查），通過(guò) Url 能知道操作的資源對(duì)象。這些特點(diǎn)，剛好和服務(wù)接入的標(biāo)準(zhǔn)不謀而合。因此，我們約定：

請(qǐng)求響應(yīng)碼，操作成功返回200，否則返回4xx，5xx。平臺(tái)只通過(guò)狀態(tài)碼來(lái)判斷操作成功與否。

標(biāo)準(zhǔn)的返回內(nèi)容（示例）如下：

{
    "id": "68788943-d109-416b-983d-e3df70a9463b",
    "config_vars": {
        "port": "3306",
        "host": "d9888.mysql.oa.com",
        "slave_host": "fd9888.slave.mysql.oa.com",
        "default_db": "db_name",
        "user": "a742e2fe34d6",
        "password": "12345678"
    },
    "message": "success!!!"
}

上面是 MySql 服務(wù)的返回例子。對(duì)于所有服務(wù)，我們都約定，返回格式統(tǒng)一使用 json，json第一級(jí)要包含 id ，message ，config_vars 這三個(gè)屬性。其中，id 為資源 id，后續(xù)對(duì)該資源的刪除，變更，都通過(guò)該id進(jìn)行。message 為附帶的消息，特別是操作失敗時(shí)，方便告知用戶失敗的原因。config_vars 中，會(huì)包含跟服務(wù)相關(guān)的差異參數(shù)，不同服務(wù)的參數(shù)，是不一樣的。在最終的信息配置頁(yè)面，提供了如下的配置功能

在該頁(yè)面中，開(kāi)發(fā)者可以配置 config_vars 中的參數(shù)。而平臺(tái)在收到實(shí)際請(qǐng)求時(shí)，也會(huì)去驗(yàn)證 config_vars 中是否包含這些參數(shù)，以確保請(qǐng)求有效性。

上面我們提到，同一個(gè)第三方服務(wù)，會(huì)有不同的類型，并對(duì)應(yīng)不同的請(qǐng)求參數(shù)。還是以MySql為例，假設(shè)我們將參數(shù)的配置直接扔給用戶，例如用戶需要一個(gè) MySql，頁(yè)面提供好幾個(gè)填寫(xiě)項(xiàng)：是否帶從庫(kù)、buffer 內(nèi)容要多大，是否為 SSD 硬盤(pán)等等，用戶自己填寫(xiě)，然后才能創(chuàng)建一個(gè) MySql。這樣是否會(huì)讓用戶覺(jué)得很懵呢？用戶能懂怎么填嗎？用戶是否真的需要這些選項(xiàng)呢？

為了讓用戶選擇更加簡(jiǎn)易，我們加入了套餐的概念。由第三方服務(wù)開(kāi)發(fā)者定義幾個(gè)套餐，例如，高級(jí)套餐對(duì)應(yīng)配置比較高的服務(wù)，中級(jí)、低級(jí)套餐則配置低些。用戶在選擇時(shí)，可以先了解每個(gè)套餐對(duì)應(yīng)哪些參數(shù)，然后再確定用哪個(gè)套餐。當(dāng)用戶選擇套餐（無(wú)需輸入?yún)?shù)值）后，平臺(tái)在后臺(tái)組裝對(duì)應(yīng)套餐的實(shí)際參數(shù)，并調(diào)用第三方服務(wù)的接口。

遵循 RESTful 設(shè)計(jì)，HTTP方法映射對(duì)應(yīng)的操作

在請(qǐng)求Header中加上通用信息

不管服務(wù)如何變化，總有一些信息是不變的，都要帶上的。對(duì)于這些通用的信息，我們會(huì)將其放在Header中。請(qǐng)求參數(shù)（ request param ）中不包含這些信息，更專注于跟服務(wù)相關(guān)的參數(shù)。
這些通用信息包括：

鑒權(quán)串。如上文提到的 keystone 串，password 串等

用戶ID。哪個(gè)用戶在控制臺(tái)要求插件平臺(tái)發(fā)起此次請(qǐng)求

項(xiàng)目ID。例如，告知 MySql 服務(wù)，是哪個(gè)項(xiàng)目要求創(chuàng)建一個(gè) MySql 資源。

來(lái)源?？刂婆_(tái)（前臺(tái)）頁(yè)面，是哪個(gè)系統(tǒng)。用戶可以在私有云平臺(tái)上創(chuàng)建一個(gè)第三方服務(wù)資源，也可以在插件平臺(tái)界面上創(chuàng)建。這是個(gè)輔助信息，沒(méi)前三個(gè)那么重要。

約定請(qǐng)求參數(shù)格式

一份請(qǐng)求內(nèi)容示例：

{
    "plan": "xxxx",
    "config": {
        "DISK": "SSD",
        "plan": "BASIC02",
        "MEMORY": "2",
        "REPLICATION": "0"
    }
}

在調(diào)用POST（創(chuàng)建）請(qǐng)求時(shí)，會(huì)帶上如上參數(shù)。和響應(yīng)格式的約定一樣，也是采用 json，第一級(jí)是約定的參數(shù)名plan，config。所有自定義參數(shù)會(huì)放在config中。在平臺(tái)管理頁(yè)面，提供了對(duì)應(yīng)的配置能力。

通過(guò)下圖所示，配置請(qǐng)求的參數(shù)名

通過(guò)下圖所示，配置套餐及各個(gè)參數(shù)對(duì)應(yīng)的參數(shù)值。支持配置接口參數(shù)值及在頁(yè)面顯示給用戶的文本值。

用戶在使用第三方服務(wù)前，可以通過(guò)頁(yè)面了解該服務(wù)。我們定義了一些關(guān)鍵信息，要求服務(wù)開(kāi)發(fā)者填寫(xiě)：

插件名稱。包含中文、英文名字。英文名字用于程序、接口的交互

類別

摘要。幾十個(gè)字概括說(shuō)明

插件特點(diǎn)。對(duì)摘要的簡(jiǎn)單補(bǔ)充

圖標(biāo)?？梢悦阑?yè)面，一開(kāi)始擔(dān)心開(kāi)發(fā)者抱怨圖標(biāo)不好找。后來(lái)發(fā)現(xiàn)恰恰相反，很多很贊的圖標(biāo)。

套餐。

文檔。詳細(xì)的說(shuō)明、使用文檔。文檔約定使用markdown，以帶來(lái)更統(tǒng)一的文檔閱讀體驗(yàn)。

我們提供了一個(gè)頁(yè)面，幫助第三方服務(wù)開(kāi)發(fā)者管理自己的插件（服務(wù)），包括了以下模塊：

信息管理

基礎(chǔ)信息編輯

服務(wù)配置，包括接口url，請(qǐng)求參數(shù)，響應(yīng)參數(shù)，套餐配置

一個(gè)基于markdown的說(shuō)明文檔編輯器

接口測(cè)試工具

貢獻(xiàn)率圖表。通過(guò)云平臺(tái)總項(xiàng)目數(shù)、插件數(shù)、使用量等，按公式計(jì)算貢獻(xiàn)率，以反映該插件的價(jià)值

用戶列表。使用該插件的項(xiàng)目列表。

第三方服務(wù)接入的一個(gè)痛點(diǎn)，就是兩方要一起調(diào)試，這會(huì)浪費(fèi)雙方很多時(shí)間。因此，我們?cè)O(shè)計(jì)了一個(gè)簡(jiǎn)單易用的web測(cè)試工具。

先曬一下界面

這個(gè)工具可以幫助開(kāi)發(fā)者、平臺(tái)管理員，快速測(cè)試第三方服務(wù)接口。打開(kāi)該工具，可以看到：

請(qǐng)求url

請(qǐng)求body

期望返回

實(shí)際返回

測(cè)試結(jié)論

當(dāng)用戶點(diǎn)擊右上角的“測(cè)試"按鈕時(shí)，將按照?qǐng)D中所示的url及請(qǐng)求body進(jìn)行測(cè)試，測(cè)試完畢后，將顯示實(shí)際返回，并和期望返回做對(duì)比，得出測(cè)試結(jié)論。

實(shí)踐證明，該工具有效提高了聯(lián)調(diào)的效率。第三方服務(wù)通過(guò)該工具可以自己檢查接口是否符合規(guī)范，而無(wú)需平臺(tái)管理員介入。

首先，開(kāi)篇提出現(xiàn)狀，我們需要為云平臺(tái)提供一個(gè)平臺(tái)，專門(mén)用于管理、接入第三方服務(wù)。當(dāng)平臺(tái)和第三方服務(wù)聯(lián)調(diào)相應(yīng)接口后，服務(wù)才能正式上線，普通用戶才能通過(guò)平臺(tái)來(lái)創(chuàng)建對(duì)應(yīng)的第三方服務(wù)資源。為了更快地測(cè)試、接入第三方服務(wù)，平臺(tái)需要定義一套對(duì)所有第三方服務(wù)都行之有效的規(guī)范。

然后，展開(kāi)解決思路如下：

我們先是梳理了不同服務(wù)在接入時(shí)，接口、操作類型、請(qǐng)求參數(shù)、響應(yīng)格式的相同點(diǎn)及不同點(diǎn)，發(fā)現(xiàn)了RESTful設(shè)計(jì)理念和我們接口設(shè)計(jì)相當(dāng)契合，因此引入了RESTful來(lái)定義接口規(guī)范：同個(gè)服務(wù)的不同操作類型（增刪改查）對(duì)應(yīng)同個(gè)Url，通過(guò)HTTP 方法來(lái)表達(dá)具體的操作類型。

請(qǐng)求參數(shù)、響應(yīng)格式設(shè)計(jì)，努力求同存異，通過(guò)HTTP狀態(tài)碼來(lái)表達(dá)操作的結(jié)果，簡(jiǎn)單明了；而內(nèi)容則約定為json格式——當(dāng)前最流行的HTTP內(nèi)容格式；在請(qǐng)求及響應(yīng)內(nèi)容的第一級(jí)，都是約定的參數(shù)名，將有差異，自定義的內(nèi)容都指定放于某個(gè)指定參數(shù)中的第二級(jí)中，從而在內(nèi)容格式上取得統(tǒng)一。

開(kāi)發(fā)者通過(guò)頁(yè)面填寫(xiě)自定義參數(shù)、各種套餐。這樣平臺(tái)就不用為了新接入一個(gè)第三方服務(wù)寫(xiě)代碼，直接讀配置，就能組裝對(duì)應(yīng)的請(qǐng)求格式。當(dāng)用戶選擇套餐時(shí)，平臺(tái)將把套餐對(duì)應(yīng)的參數(shù)值發(fā)給第三方服務(wù)。

最后，為了方便聯(lián)調(diào)，提高效率，還提供了一個(gè)強(qiáng)大的在線測(cè)試工具。當(dāng)然，如果沒(méi)有上述的規(guī)范，也沒(méi)有辦法形成標(biāo)準(zhǔn)的測(cè)試流程，沒(méi)辦法打造這款測(cè)試工具。