服務(wù)總線接口規(guī)范方案

1、安徽電信服務(wù)總線接口規(guī)范安徽電信有限公司2014年02月版本記錄版本號(hào)時(shí)間記錄人變更原因變更描述V0.12014-1-5李超初始V0.22014-2-22李超修訂增加接口參數(shù)描述第1章概述41.1 概述41.2 目標(biāo)41.3 規(guī)范使用對(duì)象及說(shuō)明41.4 名詞解釋4第2章服務(wù)設(shè)計(jì)原則52.1 接口協(xié)議統(tǒng)一原則52.3 服務(wù)定義唯一性原則62.4 服務(wù)無(wú)狀態(tài)原則62.5 服務(wù)部署原則62.6 服務(wù)組合原則62.7 報(bào)文內(nèi)容處理的原則72.8 由入?yún)⒃O(shè)計(jì)原則72.9 規(guī)則校驗(yàn)的原則82.10 數(shù)據(jù)量原則82.11 同步調(diào)用原則82.12 統(tǒng)一入口原則82.13 持久化原則8第3章服務(wù)接入規(guī)范93.1

2、 調(diào)用方式93.2 參數(shù)說(shuō)明103.2.1 系統(tǒng)級(jí)參數(shù)103.3 返回業(yè)務(wù)功能12第4章安全控制134.1 訪問(wèn)鑒權(quán)134.2 傳輸加密14第5章異常分類(lèi)編碼14第6章服務(wù)注冊(cè)、注銷(xiāo)、變更、調(diào)用流程156.1 服務(wù)注冊(cè)的流程166.2 服務(wù)注冊(cè)的內(nèi)容166.3 測(cè)試環(huán)境服務(wù)注冊(cè)的流程17第7章服務(wù)治理187.1 目標(biāo)187.2 檢查方法187.3 服務(wù)監(jiān)控的指標(biāo)197.4 服務(wù)目錄樹(shù)20第1章概述1.1 概述本規(guī)范明確了安徽電信服務(wù)總線接入及服務(wù)使用的標(biāo)準(zhǔn)和規(guī)范，為服務(wù)使用方和服務(wù)提供方提供開(kāi)發(fā)參考。1.2 目標(biāo)本規(guī)范為了指導(dǎo)各業(yè)務(wù)系統(tǒng)與服務(wù)總線平臺(tái)的對(duì)接，實(shí)現(xiàn)以下目標(biāo)：1）當(dāng)服務(wù)總線接入業(yè)務(wù)

3、系統(tǒng)服務(wù)時(shí)，為該服務(wù)提供方提供開(kāi)發(fā)依據(jù)。2）當(dāng)服務(wù)使用方調(diào)用服務(wù)總線提供的服務(wù)時(shí)，為該服務(wù)使用方提供開(kāi)發(fā)依據(jù)。3）為服務(wù)使用過(guò)程中安全及控制提供標(biāo)準(zhǔn)和參考。1.3 規(guī)范使用對(duì)象及說(shuō)明本規(guī)范適用于所有新建或改造的服務(wù)接口，均需要遵守本規(guī)范約定。1.4 名詞解釋1）服務(wù)提供方：提供原始服務(wù)，并將服務(wù)發(fā)布到服務(wù)總線的內(nèi)部業(yè)務(wù)系統(tǒng)、第三方企業(yè)或個(gè)人。2）服務(wù)使用方：使用服務(wù)總線上的服務(wù)進(jìn)行應(yīng)用開(kāi)發(fā)的內(nèi)部應(yīng)用系統(tǒng)、第三方企業(yè)或個(gè)人。3）服務(wù)商：平臺(tái)為統(tǒng)一管理服務(wù)的提供方和使用方，綜合其統(tǒng)稱(chēng)為服務(wù)商。4）服務(wù)：服務(wù)是執(zhí)行可重復(fù)任務(wù)的可發(fā)現(xiàn)資源，由外部化的服務(wù)規(guī)范進(jìn)行描述。服務(wù)可分為技術(shù)服務(wù)和業(yè)務(wù)服務(wù)兩種。

4、第2章服務(wù)設(shè)計(jì)原則由于各個(gè)系統(tǒng)和平臺(tái)之間存在差異性，為確保安徽電信服務(wù)總線的穩(wěn)定高效，服務(wù)設(shè)計(jì)原則如下：2.1 接口協(xié)議統(tǒng)一原則所有服務(wù)的接口均基于Http協(xié)議。服務(wù)提供方和服務(wù)使用方必須同時(shí)使用同一種類(lèi)型的技術(shù)來(lái)進(jìn)行開(kāi)發(fā)和調(diào)用，調(diào)用的服務(wù)通過(guò)HTTPURL中特定屬性進(jìn)行標(biāo)識(shí)，具體見(jiàn)接口協(xié)2.2 數(shù)據(jù)格式統(tǒng)一原則服務(wù)的接口數(shù)據(jù)包含業(yè)務(wù)所有的業(yè)務(wù)數(shù)據(jù)，數(shù)據(jù)采用JSON格式表示，并且符合相應(yīng)的JSONSchema。服務(wù)提供方和服務(wù)消費(fèi)方必須同時(shí)使用同一種格式進(jìn)行數(shù)據(jù)交互。2.3 服務(wù)定義唯一性原則一個(gè)服務(wù)應(yīng)該只實(shí)現(xiàn)一個(gè)業(yè)務(wù)功能，業(yè)務(wù)功能的區(qū)別通過(guò)服務(wù)編碼來(lái)區(qū)分，不應(yīng)通過(guò)定義不同的業(yè)務(wù)數(shù)據(jù)在同一個(gè)服

5、務(wù)編碼下實(shí)現(xiàn)不同的業(yè)務(wù)功能。2.4 服務(wù)無(wú)狀態(tài)原則服務(wù)應(yīng)是無(wú)狀態(tài)的，兩次請(qǐng)求之間無(wú)須狀態(tài)和會(huì)話的保持，并可以采用輪詢(xún)的方式在負(fù)載均衡器上進(jìn)行注冊(cè)2.5 服務(wù)部署原則服務(wù)應(yīng)是全局的，不應(yīng)區(qū)分本地網(wǎng)、大區(qū)等，但可以部署多份用以提供不同優(yōu)先級(jí)的服務(wù)。2.6 服務(wù)組合原則服務(wù)按照服務(wù)粒度設(shè)計(jì)成原子服務(wù)和組合服務(wù)。原子服務(wù)為最細(xì)粒度的服務(wù)，組合服務(wù)由原子服務(wù)組合而成。為有效提高組合服務(wù)的效率，跨系統(tǒng)的組合服務(wù)由服務(wù)總線調(diào)用不同的原子服務(wù)實(shí)現(xiàn)組合，系統(tǒng)內(nèi)的組合服務(wù)由服務(wù)提供方在應(yīng)用內(nèi)部進(jìn)行組合。2.7 報(bào)文內(nèi)容處理的原則服務(wù)請(qǐng)求和返回的的報(bào)文應(yīng)符合JSONSchema格式服務(wù)請(qǐng)求方和提供方應(yīng)采用通用的JS

6、ON解析器來(lái)構(gòu)造和解析數(shù)據(jù)，JSON不同含義的段落應(yīng)定義明確含義的字段名稱(chēng)，相同內(nèi)容的數(shù)據(jù)應(yīng)采用數(shù)組來(lái)進(jìn)行描述，雙方可根據(jù)JSON名稱(chēng)和路徑進(jìn)行精確定位，不應(yīng)根據(jù)字段的順序來(lái)獲取字段值，字段值不受字段順序調(diào)整的影響。報(bào)文統(tǒng)一采用UTF-8進(jìn)行編碼。2.8 出入?yún)⒃O(shè)計(jì)原則為提高查詢(xún)類(lèi)服務(wù)的通用性和性能，查詢(xún)類(lèi)服務(wù)在入?yún)⒅卸x返回字段列表，服務(wù)提供方根據(jù)入?yún)⒅兄付ǖ淖侄畏祷匦畔?。查?xún)內(nèi)接口應(yīng)在入?yún)⒅卸x分頁(yè)參數(shù)，返回參數(shù)中應(yīng)包含當(dāng)前頁(yè)數(shù)、總頁(yè)數(shù)或是已到最后一頁(yè)等信息。返回參數(shù)中如返回靜態(tài)編碼值時(shí)應(yīng)同時(shí)返回此編碼值對(duì)應(yīng)的名稱(chēng)。2.9 規(guī)則校驗(yàn)的原則服務(wù)提供方應(yīng)對(duì)請(qǐng)求報(bào)文格式和關(guān)鍵信息進(jìn)行合規(guī)性和業(yè)務(wù)

7、校驗(yàn)，防止非法訪問(wèn)和入侵。2.10 數(shù)據(jù)量原則服務(wù)總線所傳遞的單條消息大小原則上不大于1M,否則應(yīng)建議采用文件傳輸、接口表傳輸、直連等連接方式。2.11 同步調(diào)用原則服務(wù)調(diào)用方和服務(wù)提供方采用同步調(diào)用的方式進(jìn)行請(qǐng)求，如需要使用異步調(diào)用可采用消息隊(duì)列或服務(wù)調(diào)用方定義異步通知接口來(lái)實(shí)現(xiàn)。2.12 統(tǒng)一入口原則服務(wù)總線對(duì)外提供統(tǒng)一的調(diào)用地址。2.13 持久化原則服務(wù)使用方在使用服務(wù)的過(guò)程中，由服務(wù)總線進(jìn)行整個(gè)過(guò)程的日志記錄，并對(duì)調(diào)用的詳細(xì)信息進(jìn)行持久化，便于對(duì)賬和稽核。建議服務(wù)調(diào)用方和提供方對(duì)調(diào)用的關(guān)鍵信息（如流水號(hào)，源地址等）進(jìn)行持久化。第3章服務(wù)接入規(guī)范對(duì)于服務(wù)調(diào)用的訪問(wèn)方式，平臺(tái)采用標(biāo)準(zhǔn)的HT

8、TP調(diào)用方式。3.1 調(diào)用方式接口服務(wù)通過(guò)http:/ip:port/oip/rest訪問(wèn)平臺(tái)服務(wù)。IP和PORT根據(jù)實(shí)際生產(chǎn)環(huán)境情況對(duì)外公布。其中/oip/rest保持不變。實(shí)例：基于REST的服務(wù)請(qǐng)求以使用“查詢(xún)BSS用戶(hù)短信詳單”服務(wù)為例，該服務(wù)的具體信息如下：服務(wù)名稱(chēng)：查詢(xún)BSS用戶(hù)短信詳單；服務(wù)編碼：SelectSmsInfo;開(kāi)發(fā)技術(shù)：采用HTTP協(xié)議技術(shù)；請(qǐng)求方式：采用GET/POST都可以調(diào)用方信息不變根據(jù)上面這些信息，得由服務(wù)訪問(wèn)地址為:GET方式：http:4:7080/oip/rest?send=crm&servCode=1001.OPEN_3R

9、D.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1末位的1”是模擬業(yè)務(wù)參數(shù)。POST方式：4:7080/oip/rest?send=crm&servCode=1001.OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1業(yè)務(wù)參數(shù)的內(nèi)容放在http的請(qǐng)求體中傳輸3.2 參數(shù)說(shuō)明3.2.1 系統(tǒng)級(jí)參數(shù)以下參數(shù)是由服務(wù)總線定義的。表格3-1系統(tǒng)級(jí)參數(shù)參數(shù)名是否必描述需Sendstring是客戶(hù)端所屬系統(tǒng)編碼，填寫(xiě)請(qǐng)參考3.1節(jié)（系統(tǒng)

10、標(biāo)志全部采用此編碼）servCodestring是客戶(hù)端需要訪問(wèn)的服務(wù)編碼，由服務(wù)總線在注冊(cè)后統(tǒng)一提供msgIdstring是由調(diào)用方系統(tǒng)按照OIP規(guī)則生成的唯一標(biāo)識(shí)次調(diào)用的字符串，長(zhǎng)度小于64位。生成規(guī)則：系統(tǒng)名當(dāng)前時(shí)間戳流水號(hào)busiUrlstring是消費(fèi)方傳遞的業(yè)務(wù)部分地址App_keyString否服務(wù)總線分配的應(yīng)用標(biāo)志transactionldString是交易流水號(hào)，由調(diào)用方生成，多次請(qǐng)求均會(huì)包含此信息。格式建議為系統(tǒng)名當(dāng)前時(shí)間戳流水號(hào)R1String否動(dòng)態(tài)路由參數(shù)1R2String否動(dòng)態(tài)路由參數(shù)2R3String否動(dòng)態(tài)路由參數(shù)3transactionld:交易流水號(hào)。服務(wù)請(qǐng)求需

11、經(jīng)過(guò)多個(gè)系統(tǒng)或多個(gè)系統(tǒng)模塊，為了有效標(biāo)志由一次業(yè)務(wù)請(qǐng)求經(jīng)過(guò)的所有調(diào)用，服務(wù)調(diào)用方在請(qǐng)求時(shí)生成一唯一的流水號(hào)，服務(wù)總線在多次調(diào)用過(guò)程中將會(huì)保持此交易流水號(hào)一致，服務(wù)提供方也應(yīng)記錄此交易流水號(hào)。所有消息日志應(yīng)統(tǒng)一記錄到統(tǒng)一日志平臺(tái)以供事后分析。R1-R3:動(dòng)態(tài)路由參數(shù)，為了保持路由的靈活性，調(diào)用方可動(dòng)態(tài)添加最多3個(gè)路由參數(shù)，如版本號(hào)，本地網(wǎng)等參數(shù)，服務(wù)總線根據(jù)此參數(shù)路由到特定的服務(wù)提供方節(jié)點(diǎn)上，以滿足試點(diǎn)，灰度發(fā)布等場(chǎng)景。3.3 返回業(yè)務(wù)功能返回參數(shù)分為兩部分，一部分為HTTP協(xié)議部分，包含了請(qǐng)求的狀態(tài)，異常代碼和異常信息，200表示本次請(qǐng)求完成，500表示服務(wù)總線調(diào)用服務(wù)提供方由現(xiàn)異常等；一部分

12、為業(yè)務(wù)數(shù)據(jù)，業(yè)務(wù)數(shù)據(jù)采用JSON格式，JSON格式需符合JSONSchema的校驗(yàn)規(guī)則，業(yè)務(wù)異常也在此部分定義。服務(wù)總線后臺(tái)分析系統(tǒng)將會(huì)對(duì)請(qǐng)求和返回的報(bào)文進(jìn)行事后分析。第4章安全控制4.1 訪問(wèn)鑒權(quán)服務(wù)總線對(duì)外提供統(tǒng)一安全控制策略。所有訪問(wèn)能力開(kāi)放平臺(tái)的服務(wù)時(shí)，都必須經(jīng)過(guò)平臺(tái)的鑒權(quán)，鑒權(quán)通過(guò)后方允許訪問(wèn)，否則將給與攔截。能力開(kāi)放的訪問(wèn)鑒權(quán)提供如下幾種策略：服務(wù)商鑒權(quán)：凡是使用能力開(kāi)放平臺(tái)的服務(wù)使用方必須是已注冊(cè)的服務(wù)商下的一個(gè)客戶(hù)端。該部分由使用方進(jìn)行申請(qǐng)，平臺(tái)完成注冊(cè)，同時(shí)為服務(wù)使用方分配可使用服務(wù)的權(quán)限。IP地址鑒權(quán)：應(yīng)用集成平臺(tái)支持服務(wù)使用方的IP地址身份認(rèn)證模式。對(duì)于不在服務(wù)使用方申請(qǐng)

13、的IP地址范圍內(nèi)產(chǎn)生的服務(wù)調(diào)用，平臺(tái)給予攔截和告警。對(duì)于通過(guò)多重路由或映射導(dǎo)致不能獲得實(shí)際IP地址時(shí)，將采用鑒權(quán)碼方式替代。摘要式認(rèn)證：采用標(biāo)準(zhǔn)的HTTP摘要認(rèn)證方式進(jìn)行訪問(wèn)認(rèn)證，具體介紹見(jiàn)參考文檔OAuth2.0:對(duì)于嚴(yán)格權(quán)限限制的場(chǎng)景，通過(guò)OAuth2.0協(xié)議進(jìn)行認(rèn)證和授權(quán)，授權(quán)由應(yīng)用系統(tǒng)統(tǒng)一提供。4.2 傳輸加密對(duì)于安全非常高的場(chǎng)合，建議全流程采用HTTPS協(xié)議進(jìn)行加密傳輸，如繳費(fèi)等場(chǎng)景。第5章異常分類(lèi)編碼在使用平臺(tái)服務(wù)的過(guò)程中，平臺(tái)對(duì)不同的異常進(jìn)行分類(lèi)，供開(kāi)發(fā)者和使用方在調(diào)測(cè)及使用過(guò)程中參考種類(lèi)編碼描述正常0成功接口請(qǐng)求方異常2消息格式異常，例如必填參數(shù)未填、消息編碼異常等3無(wú)效的路由

14、屬性10接口請(qǐng)求超過(guò)指定流量9接口請(qǐng)求包大小超過(guò)限制6權(quán)限異常（例如無(wú)權(quán)訪問(wèn)此服務(wù)）101重復(fù)請(qǐng)求102無(wú)效的業(yè)務(wù)域或業(yè)務(wù)大類(lèi)、小類(lèi)199接口請(qǐng)求方其他異常接口響應(yīng)方異常8接口響應(yīng)力超時(shí)201接口響應(yīng)超過(guò)指定流量202接口響應(yīng)包大小超過(guò)限制298接口響應(yīng)力內(nèi)部異常299接口響應(yīng)方其他異常平臺(tái)異常4調(diào)用的服務(wù)未發(fā)布5調(diào)用的服務(wù)已注銷(xiāo)7調(diào)用的服務(wù)已關(guān)閉11調(diào)用的服務(wù)不存在1服務(wù)調(diào)用失敗398平臺(tái)內(nèi)部異常399平臺(tái)其他異常其他異常999其他異常測(cè)試異常601測(cè)試接口未實(shí)現(xiàn)業(yè)務(wù)定義異常1000如果遇到上述類(lèi)似異常代碼或信息，可以和平臺(tái)維護(hù)人員聯(lián)系幫助解決第6章服務(wù)注冊(cè)、注銷(xiāo)、變更、調(diào)用流程6.1 服務(wù)

15、注冊(cè)的流程服務(wù)注冊(cè)和變更：由服務(wù)提供方在ITSM發(fā)起申請(qǐng)，經(jīng)服務(wù)評(píng)審后，由ITSM調(diào)用服務(wù)總線提供的能力進(jìn)行注冊(cè)和變更。服務(wù)注銷(xiāo)：由服務(wù)提供方或服務(wù)總線管理方根據(jù)實(shí)際需求和服務(wù)的調(diào)用次數(shù)等評(píng)估后發(fā)起，經(jīng)服務(wù)提供方、服務(wù)總線管理部門(mén)和服務(wù)調(diào)用方會(huì)審后在ITSM中發(fā)起下線流程。服務(wù)調(diào)用：由服務(wù)調(diào)用方發(fā)起，經(jīng)服務(wù)提供方確認(rèn)和服務(wù)評(píng)審后在服務(wù)總線上進(jìn)行注冊(cè)。服務(wù)評(píng)審由服務(wù)總線管理部門(mén)牽頭組織。6.2 服務(wù)注冊(cè)的內(nèi)容名稱(chēng)說(shuō)明接口名稱(chēng)接口編碼接口筒要描述請(qǐng)求報(bào)文樣例返回報(bào)文樣例請(qǐng)求報(bào)文格式定義返回報(bào)文格式定義接口業(yè)務(wù)異常列表和描述版本號(hào)對(duì)應(yīng)的服務(wù)節(jié)點(diǎn)注冊(cè)服務(wù)地址探測(cè)報(bào)文（可選）是否進(jìn)行探測(cè)（時(shí)間，頻度）備

16、用服務(wù)地址（在連續(xù)失敗或撥測(cè)失敗等情況下自動(dòng)或手工切換服務(wù)地址）6.3 測(cè)試環(huán)境服務(wù)注冊(cè)的流程測(cè)試環(huán)境服務(wù)注冊(cè)由ITSM發(fā)起，在完成表單填寫(xiě)后自動(dòng)在服務(wù)總線上進(jìn)行處理第7章服務(wù)治理7.1目標(biāo)1、 所有域的服務(wù)按照協(xié)議規(guī)范全部接入服務(wù)總線，避免由現(xiàn)服務(wù)未在服務(wù)總線直接使用。2、 注冊(cè)在服務(wù)總線上的服務(wù)必須符合服務(wù)總線的規(guī)范，包括接口協(xié)議，數(shù)據(jù)格式，不得私自更改協(xié)議或超過(guò)注冊(cè)的內(nèi)容升級(jí)接口內(nèi)容7.2 檢查方法1、 按照所有服務(wù)全部由服務(wù)總線調(diào)用或者由F5負(fù)載均衡器調(diào)用的基本原則，服務(wù)管理團(tuán)隊(duì)會(huì)定期對(duì)主機(jī)和F5上服務(wù)的調(diào)用方IP進(jìn)行審核，如果由現(xiàn)服務(wù)端口由現(xiàn)非服務(wù)總線或非F5主機(jī)的調(diào)用，或者F5主機(jī)

17、上服務(wù)端口非服務(wù)總線的調(diào)用，則認(rèn)為由現(xiàn)了異常的服務(wù)調(diào)用，由服務(wù)提供方提供服務(wù)調(diào)用日志或版本變化情況進(jìn)行詳細(xì)的解釋。2、 服務(wù)接口參數(shù)應(yīng)符合接口規(guī)范，服務(wù)總線將定期對(duì)服務(wù)調(diào)用異常、失敗、異常代碼等進(jìn)行統(tǒng)計(jì)，給由服務(wù)接口的符合度。3、 服務(wù)返回的業(yè)務(wù)數(shù)據(jù)應(yīng)符合注冊(cè)時(shí)提供的JSONSchema,不符合的則認(rèn)為是注冊(cè)信息不全或異常升級(jí)。服務(wù)總線將定期從服務(wù)調(diào)用報(bào)文中進(jìn)行格式校驗(yàn)，對(duì)不符合格式的消息請(qǐng)求反饋服務(wù)提供方并要求進(jìn)行說(shuō)明。7.3 服務(wù)監(jiān)控的指標(biāo)指標(biāo)類(lèi)型運(yùn)行類(lèi)調(diào)用次數(shù)平均調(diào)用時(shí)長(zhǎng)1秒以?xún)?nèi)調(diào)用次數(shù)1-5秒以?xún)?nèi)調(diào)用次數(shù)5秒以上調(diào)用次數(shù)調(diào)用成功次數(shù)調(diào)用失敗次數(shù)調(diào)用超時(shí)次數(shù)非法調(diào)用個(gè)數(shù)常規(guī)類(lèi)服務(wù)注冊(cè)個(gè)數(shù)服務(wù)變更個(gè)數(shù)服務(wù)注銷(xiāo)個(gè)數(shù)規(guī)范類(lèi)異常服務(wù)接口個(gè)數(shù)接口請(qǐng)求不合規(guī)個(gè)數(shù)報(bào)文格式不合規(guī)個(gè)數(shù)7.4 服務(wù)目錄樹(shù)