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

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

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

首先要回答的第一個問題，是為什么需要插件平臺：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

最終的流程如下

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

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

管理員審核并上線

這是很常見的一個接入流程。下面我們具體看看，我們是如何更簡潔解決上面提到的問題。

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

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

這樣有兩個好處：

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

不用自己造輪子

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

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

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

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

請求響應(yīng)碼，操作成功返回200，否則返回4xx，5xx。平臺只通過狀態(tà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ù)的返回例子。對于所有服務(wù)，我們都約定，返回格式統(tǒng)一使用 json，json第一級要包含 id ，message ，config_vars 這三個屬性。其中，id 為資源 id，后續(xù)對該資源的刪除，變更，都通過該id進(jìn)行。message 為附帶的消息，特別是操作失敗時(shí)，方便告知用戶失敗的原因。config_vars 中，會包含跟服務(wù)相關(guān)的差異參數(shù)，不同服務(wù)的參數(shù)，是不一樣的。在最終的信息配置頁面，提供了如下的配置功能

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

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

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

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

在請求Header中加上通用信息

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

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

用戶ID。哪個用戶在控制臺要求插件平臺發(fā)起此次請求

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

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

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

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

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

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

通過下圖所示，配置請求的參數(shù)名

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

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

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

類別

摘要。幾十個字概括說明

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

圖標(biāo)。可以美化頁面，一開始擔(dān)心開發(fā)者抱怨圖標(biāo)不好找。后來發(fā)現(xiàn)恰恰相反，很多很贊的圖標(biāo)。

套餐。

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

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

信息管理

基礎(chǔ)信息編輯

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

一個基于markdown的說明文檔編輯器

接口測試工具

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

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

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

先曬一下界面

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

請求url

請求body

期望返回

實(shí)際返回

測試結(jié)論

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

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

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

然后，展開解決思路如下：

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

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

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

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