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

1、安徽電信服務(wù)總線接口規(guī)范安徽電信服務(wù)總線接口規(guī)范安徽電信有限公司2014 年 02 月服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 1 頁，共 24 頁版本記錄版本記錄第第 1 章章概述概述.51.1 概述.51.2 目標.51.3 規(guī)范使用對象及說明.51.4 名詞解釋.6第第 2 章章服務(wù)設(shè)計原則服務(wù)設(shè)計原則.62.1 接口協(xié)議統(tǒng)一原則.62.2 數(shù)據(jù)格式統(tǒng)一原則.7版本號時間記錄人變更原因變更描述V0.12014-1-5李超初始V0.22014-2-22李超修訂增加接口參數(shù)描述服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 2 頁，共 24 頁2.3 服務(wù)定義唯一性原則.72.4 服務(wù)無狀態(tài)原則.72.5

2、 服務(wù)部署原則.82.6 服務(wù)組合原則.82.7 報文內(nèi)容處理的原則.82.8 出入?yún)⒃O(shè)計原則.92.9 規(guī)則校驗的原則.92.10 數(shù)據(jù)量原則.92.11 同步調(diào)用原則.102.12 統(tǒng)一入口原則.102.13 持久化原則.10第第 3 章章服務(wù)接入規(guī)范服務(wù)接入規(guī)范.103.1 調(diào)用方式.113.2 參數(shù)說明.12服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 3 頁，共 24 頁3.2.1 系統(tǒng)級參數(shù).123.3 返回業(yè)務(wù)功能.14第第 4 章章安全控制安全控制.144.1 訪問鑒權(quán).154.2 傳輸加密.16第第 5 章章異常分類編碼異常分類編碼.16第第 6 章章服務(wù)注冊、注銷、變更、調(diào)用流程服

3、務(wù)注冊、注銷、變更、調(diào)用流程.176.1 服務(wù)注冊的流程.176.2 服務(wù)注冊的內(nèi)容.186.3 測試環(huán)境服務(wù)注冊的流程.19第第 7 章章服務(wù)治理服務(wù)治理.197.1 目標.197.2 檢查方法.207.3 服務(wù)監(jiān)控的指標.21服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 4 頁，共 24 頁7.4 服務(wù)目錄樹.22服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 5 頁，共 24 頁第 1 章 概述1.1 概述本規(guī)范明確了安徽電信服務(wù)總線接入及服務(wù)使用的標準和規(guī)范，為服務(wù)使用方和服務(wù)提供方提供開發(fā)參考。1.2 目標本規(guī)范為了指導(dǎo)各業(yè)務(wù)系統(tǒng)與服務(wù)總線平臺的對接，實現(xiàn)以下目標：1) 當服務(wù)總線接入業(yè)務(wù)系統(tǒng)服務(wù)時，

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

5、部化的服務(wù)規(guī)范進行描述。服務(wù)可分為技術(shù)服務(wù)和業(yè)務(wù)服務(wù)兩種。第 2 章 服務(wù)設(shè)計原則由于各個系統(tǒng)和平臺之間存在差異性，為確保安徽電信服務(wù)總線的穩(wěn)定高效，服務(wù)設(shè)計原則如下：2.1 接口協(xié)議統(tǒng)一原則服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 7 頁，共 24 頁所有服務(wù)的接口均基于 Http 協(xié)議。服務(wù)提供方和服務(wù)使用方必須同時使用同一種類型的技術(shù)來進行開發(fā)和調(diào)用，調(diào)用的服務(wù)通過 HTTP URL 中特定屬性進行標識，具體見接口協(xié)議。2.2 數(shù)據(jù)格式統(tǒng)一原則服務(wù)的接口數(shù)據(jù)包含業(yè)務(wù)所有的業(yè)務(wù)數(shù)據(jù)，數(shù)據(jù)采用 JSON格式表示，并且符合相應(yīng)的 JSON Schema。服務(wù)提供方和服務(wù)消費方必須同時使用同一種格式

6、進行數(shù)據(jù)交互。2.3 服務(wù)定義唯一性原則一個服務(wù)應(yīng)該只實現(xiàn)一個業(yè)務(wù)功能，業(yè)務(wù)功能的區(qū)別通過服務(wù)編碼來區(qū)分，不應(yīng)通過定義不同的業(yè)務(wù)數(shù)據(jù)在同一個服務(wù)編碼下實現(xiàn)不同的業(yè)務(wù)功能。2.4 服務(wù)無狀態(tài)原則服務(wù)應(yīng)是無狀態(tài)的，兩次請求之間無須狀態(tài)和會話的保持，并可以采用輪詢的方式在負載均衡器上進行注冊服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 8 頁，共 24 頁2.5 服務(wù)部署原則服務(wù)應(yīng)是全局的，不應(yīng)區(qū)分本地網(wǎng)、大區(qū)等，但可以部署多份用以提供不同優(yōu)先級的服務(wù)。2.6 服務(wù)組合原則服務(wù)按照服務(wù)粒度設(shè)計成原子服務(wù)和組合服務(wù)。原子服務(wù)為最細粒度的服務(wù)，組合服務(wù)由原子服務(wù)組合而成。為有效提高組合服務(wù)的效率，跨系統(tǒng)的組合服

7、務(wù)由服務(wù)總線調(diào)用不同的原子服務(wù)實現(xiàn)組合，系統(tǒng)內(nèi)的組合服務(wù)由服務(wù)提供方在應(yīng)用內(nèi)部進行組合。2.7 報文內(nèi)容處理的原則服務(wù)請求和返回的的報文應(yīng)符合 JSON Schema 格式。服務(wù)請求方和提供方應(yīng)采用通用的 JSON 解析器來構(gòu)造和解析數(shù)據(jù)，JSON 不同含義的段落應(yīng)定義明確含義的字段名稱，相同內(nèi)容的數(shù)據(jù)應(yīng)采用數(shù)組來進行描述，雙方可根據(jù) JSON名稱和路徑進行精確定位，不應(yīng)根據(jù)字段的順序來獲取字段服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 9 頁，共 24 頁值，字段值不受字段順序調(diào)整的影響。報文統(tǒng)一采用 UTF-8進行編碼。2.8 出入?yún)⒃O(shè)計原則為提高查詢類服務(wù)的通用性和性能，查詢類服務(wù)在入?yún)⒅卸x

8、返回字段列表，服務(wù)提供方根據(jù)入?yún)⒅兄付ǖ淖侄畏祷匦畔ⅰ２樵儍?nèi)接口應(yīng)在入?yún)⒅卸x分頁參數(shù)，返回參數(shù)中應(yīng)包含當前頁數(shù)、總頁數(shù)或是已到最后一頁等信息。返回參數(shù)中如返回靜態(tài)編碼值時應(yīng)同時返回此編碼值對應(yīng)的名稱。2.9 規(guī)則校驗的原則 服務(wù)提供方應(yīng)對請求報文格式和關(guān)鍵信息進行合規(guī)性和業(yè)務(wù)校驗，防止非法訪問和入侵。2.10 數(shù)據(jù)量原則服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 10 頁，共 24 頁服務(wù)總線所傳遞的單條消息大小原則上不大于 1M，否則應(yīng)建議采用文件傳輸、接口表傳輸、直連等連接方式。2.11 同步調(diào)用原則服務(wù)調(diào)用方和服務(wù)提供方采用同步調(diào)用的方式進行請求，如需要使用異步調(diào)用可采用消息隊列或服務(wù)調(diào)用方

9、定義異步通知接口來實現(xiàn)。2.12 統(tǒng)一入口原則服務(wù)總線對外提供統(tǒng)一的調(diào)用地址。2.13 持久化原則服務(wù)使用方在使用服務(wù)的過程中，由服務(wù)總線進行整個過程的日志記錄，并對調(diào)用的詳細信息進行持久化，便于對賬和稽核。建議服務(wù)調(diào)用方和提供方對調(diào)用的關(guān)鍵信息（如流水號，源地址等）進行持久化。第 3 章 服務(wù)接入規(guī)范服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 11 頁，共 24 頁對于服務(wù)調(diào)用的訪問方式，平臺采用標準的 HTTP 調(diào)用方式。3.1 調(diào)用方式接口服務(wù)通過 http:/ip:port/oip/rest 訪問平臺服務(wù)。IP 和 PORT 根據(jù)實際生產(chǎn)環(huán)境情況對外公布。其中/oip/rest保持不變。 實

10、例：基于 REST 的服務(wù)請求以使用“查詢 BSS 用戶短信詳單”服務(wù)為例，該服務(wù)的具體信息如下：服務(wù)名稱：查詢 BSS 用戶短信詳單；服務(wù)編碼：SelectSmsInfo；開發(fā)技術(shù)：采用 HTTP 協(xié)議技術(shù)；請求方式：采用 GET/POST 都可以 調(diào)用方信息不變。根據(jù)上面這些信息，得出服務(wù)訪問地址為：服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 12 頁，共 24 頁GET 方式：4:7080/oip/rest?send=crm&servCode=1001.OPEN_3RD.Sync&msgId=crm_20130718_10001&b

11、usiURl=/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 的請求體中傳輸3.2 參數(shù)說明3.2.1 系統(tǒng)級參數(shù)以下參數(shù)是由服務(wù)總線定義的。表格 3-1 系統(tǒng)級參數(shù)參數(shù)名類型是否必需描述Sendstring是客戶端所屬系統(tǒng)編碼，填寫請參考 3.1 節(jié)（系統(tǒng)標志全部采用此編碼）s

12、ervCodestring是客戶端需要訪問的服務(wù)編服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 13 頁，共 24 頁碼，由服務(wù)總線在注冊后統(tǒng)一提供msgIdstring是由調(diào)用方系統(tǒng)按照 OIP 規(guī)則生成的唯一標識一次調(diào)用的字符串，長度小于 64位。生成規(guī)則：系統(tǒng)名_當前時間戳_流水號busiUrlstring是消費方傳遞的業(yè)務(wù)部分地址App_keyString否服務(wù)總線分配的應(yīng)用標志transactionIdString是交易流水號，由調(diào)用方生成，多次請求均會包含此信息。格式建議為系統(tǒng)名_當前時間戳_流水號R1String否動態(tài)路由參數(shù) 1R2String否動態(tài)路由參數(shù) 2R3String否動態(tài)路

13、由參數(shù) 3transactionId：交易流水號。服務(wù)請求需經(jīng)過多個系統(tǒng)或多個系統(tǒng)模塊，為了有效標志出一次業(yè)務(wù)請求經(jīng)過的所有調(diào)用，服務(wù)調(diào)用方在請求時生成一唯一的流水號，服務(wù)總線在多次調(diào)用過程中將會保持此交易流水號一致，服務(wù)提供方也應(yīng)記服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 14 頁，共 24 頁錄此交易流水號。所有消息日志應(yīng)統(tǒng)一記錄到統(tǒng)一日志平臺以供事后分析。R1-R3：動態(tài)路由參數(shù)，為了保持路由的靈活性，調(diào)用方可動態(tài)添加最多 3 個路由參數(shù)，如版本號，本地網(wǎng)等參數(shù)，服務(wù)總線根據(jù)此參數(shù)路由到特定的服務(wù)提供方節(jié)點上，以滿足試點，灰度發(fā)布等場景。3.3 返回業(yè)務(wù)功能返回參數(shù)分為兩部分，一部分為 HT

14、TP 協(xié)議部分，包含了請求的狀態(tài)，異常代碼和異常信息，200 表示本次請求完成，500 表示服務(wù)總線調(diào)用服務(wù)提供方出現(xiàn)異常等；一部分為業(yè)務(wù)數(shù)據(jù)，業(yè)務(wù)數(shù)據(jù)采用 JSON 格式，JSON 格式需符合 JSON Schema 的校驗規(guī)則，業(yè)務(wù)異常也在此部分定義。服務(wù)總線后臺分析系統(tǒng)將會對請求和返回的報文進行事后分析。第 4 章 安全控制服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 15 頁，共 24 頁4.1 訪問鑒權(quán)服務(wù)總線對外提供統(tǒng)一安全控制策略。所有訪問能力開放平臺的服務(wù)時，都必須經(jīng)過平臺的鑒權(quán)，鑒權(quán)通過后方允許訪問，否則將給與攔截。能力開放的訪問鑒權(quán)提供如下幾種策略：服務(wù)商鑒權(quán)服務(wù)商鑒權(quán)：凡是使用能

15、力開放平臺的服務(wù)使用方必須是已注冊的服務(wù)商下的一個客戶端。該部分由使用方進行申請，平臺完成注冊，同時為服務(wù)使用方分配可使用服務(wù)的權(quán)限。IP 地址鑒權(quán)地址鑒權(quán)：應(yīng)用集成平臺支持服務(wù)使用方的 IP 地址身份認證模式。對于不在服務(wù)使用方申請的 IP 地址范圍內(nèi)產(chǎn)生的服務(wù)調(diào)用，平臺給予攔截和告警。對于通過多重路由或映射導(dǎo)致不能獲得實際 IP 地址時，將采用鑒權(quán)碼方式替代。摘要式認證：摘要式認證：采用標準的 HTTP 摘要認證方式進行訪問認證，具體介紹見參考文檔服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 16 頁，共 24 頁OAuth2.0: 對于嚴格權(quán)限限制的場景，通過 OAuth2.0 協(xié)議進行認證和授

16、權(quán)，授權(quán)由應(yīng)用系統(tǒng)統(tǒng)一提供。4.2 傳輸加密對于安全非常高的場合，建議全流程采用 HTTPS 協(xié)議進行加密傳輸，如繳費等場景。第 5 章 異常分類編碼在使用平臺服務(wù)的過程中，平臺對不同的異常進行分類，供開發(fā)者和使用方在調(diào)測及使用過程中參考。種類編碼描述正常0成功2消息格式異常，例如必填參數(shù)未填、消息編碼異常等3無效的路由屬性10接口請求超過指定流量9接口請求包大小超過限制6權(quán)限異常（例如無權(quán)訪問此服務(wù)）101重復(fù)請求102無效的業(yè)務(wù)域或業(yè)務(wù)大類、小類接口請求方異常199接口請求方其他異常服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 17 頁，共 24 頁8接口響應(yīng)方超時201接口響應(yīng)超過指定流量202

17、接口響應(yīng)包大小超過限制298接口響應(yīng)方內(nèi)部異常接口響應(yīng)方異常299接口響應(yīng)方其他異常4調(diào)用的服務(wù)未發(fā)布5調(diào)用的服務(wù)已注銷7調(diào)用的服務(wù)已關(guān)閉11調(diào)用的服務(wù)不存在1服務(wù)調(diào)用失敗398平臺內(nèi)部異常平臺異常399平臺其他異常其他異常999其他異常測試異常601測試接口未實現(xiàn)業(yè)務(wù)定義異常1000如果遇到上述類似異常代碼或信息，可以和平臺維護人員聯(lián)系幫助解決。第 6 章 服務(wù)注冊、注銷、變更、調(diào)用流程6.1 服務(wù)注冊的流程服務(wù)注冊和變更：由服務(wù)提供方在 ITSM 發(fā)起申請，經(jīng)服務(wù)評審后，由 ITSM 調(diào)用服務(wù)總線提供的能力進行注冊和變更。服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 18 頁，共 24 頁服務(wù)注銷

18、：由服務(wù)提供方或服務(wù)總線管理方根據(jù)實際需求和服務(wù)的調(diào)用次數(shù)等評估后發(fā)起，經(jīng)服務(wù)提供方、服務(wù)總線管理部門和服務(wù)調(diào)用方會審后在 ITSM 中發(fā)起下線流程。服務(wù)調(diào)用：由服務(wù)調(diào)用方發(fā)起，經(jīng)服務(wù)提供方確認和服務(wù)評審后在服務(wù)總線上進行注冊。服務(wù)評審由服務(wù)總線管理部門牽頭組織。6.2 服務(wù)注冊的內(nèi)容名稱說明接口名稱接口編碼接口簡要描述請求報文樣例返回報文樣例請求報文格式定義返回報文格式定義接口業(yè)務(wù)異常列表和描述版本號對應(yīng)的服務(wù)節(jié)點注冊服務(wù)地址探測報文（可選）服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 19 頁，共 24 頁是否進行探測（時間，頻度）備用服務(wù)地址（在連續(xù)失敗或撥測失敗等情況下自動或手工切換服務(wù)地址）

19、6.3 測試環(huán)境服務(wù)注冊的流程測試環(huán)境服務(wù)注冊由 ITSM 發(fā)起，在完成表單填寫后自動在服務(wù)總線上進行處理。第 7 章 服務(wù)治理7.1 目標1、 所有域的服務(wù)按照協(xié)議規(guī)范全部接入服務(wù)總線，避免出現(xiàn)服務(wù)未在服務(wù)總線直接使用。服務(wù)總線接口規(guī)范安徽電信服務(wù)總線 第 20 頁，共 24 頁2、 注冊在服務(wù)總線上的服務(wù)必須符合服務(wù)總線的規(guī)范，包括接口協(xié)議，數(shù)據(jù)格式，不得私自更改協(xié)議或超過注冊的內(nèi)容升級接口內(nèi)容7.2 檢查方法1、 按照所有服務(wù)全部由服務(wù)總線調(diào)用或者由 F5 負載均衡器調(diào)用的基本原則，服務(wù)管理團隊會定期對主機和 F5 上服務(wù)的調(diào)用方 IP 進行審核，如果出現(xiàn)服務(wù)端口出現(xiàn)非服務(wù)總線或非 F5 主機的調(diào)用，或者 F5 主機上服務(wù)端口非服務(wù)總線的調(diào)用，則認為出現(xiàn)了異常的服務(wù)調(diào)用，由服務(wù)提供方提供服務(wù)調(diào)用日志或版本變化情況進行詳細的解釋。2、 服務(wù)接口參數(shù)應(yīng)符合接口規(guī)范，服務(wù)總線將定期對服務(wù)調(diào)用異常、失敗、異常代碼等進行統(tǒng)計，給出服務(wù)接口的符合度。服務(wù)總