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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

最終的流程如下

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

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

管理員審核并上線

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

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

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

這樣有兩個好處：

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

不用自己造輪子

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

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

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

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

請求響應碼，操作成功返回200，否則返回4xx，5xx。平臺只通過狀態(tài)碼來判斷操作成功與否。

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

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

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

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

遵循 RESTful 設計，HTTP方法映射對應的操作

在請求Header中加上通用信息

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

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

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

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

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

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

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

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

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

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

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

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

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

類別

摘要。幾十個字概括說明

插件特點。對摘要的簡單補充

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

套餐。

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

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

信息管理

基礎信息編輯

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

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

接口測試工具

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

用戶列表。使用該插件的項目列表。

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

先曬一下界面

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

請求url

請求body

期望返回

實際返回

測試結(jié)論

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

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

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

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

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

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

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

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