服務總線接口規(guī)范標準

1、!-安徽電信服務總線接口規(guī)范安 徽 電 信 有 限 公 司2014年02月!-版本記錄版本號時間記錄人變更原因變更描述V0.12014-1-5李超初始V0.22014-2-22李超修訂增加接口參數(shù)描述第1章概述1.1概述1.2目標1.3規(guī)范使用對象及說明1.4名詞解釋2.3服務定義唯一性原則6第2章服務設計原則2.1接口協(xié)議統(tǒng)一原則2.2數(shù)據(jù)格式統(tǒng)一原則2.4服務無狀態(tài)原則!-4.1訪問鑒權(quán)122.5服務部署原則2.6服務組合原則2.7報文內(nèi)容處理的原則2.8出入?yún)⒃O計原則2.9規(guī)則校驗的原則2.10數(shù)據(jù)量原則2.11冋步調(diào)用原則2.12統(tǒng)一入口原則2.13持久化原則第3章服務接入規(guī)范3.1調(diào)

2、用方式3.2參數(shù)說明103.2.1系統(tǒng)級參數(shù)103.3返回業(yè)務功能12第4章安全控制12!-134.2傳輸加密13第5章異常分類編碼第6章 服務注冊、注銷、變更、調(diào)用流程156.1服務注冊的流程156.2服務注冊的內(nèi)容156.3測試環(huán)境服務注冊的流程16第7章服務治理167.1目標167.2檢查方法177.3服務監(jiān)控的指標187.4服務目錄樹19!-第1章概述1.4名詞解釋1.1概述本規(guī)范明確了安徽電信服務總線接入及服務使用的標準和規(guī) 范，為服務使用方和服務提供方提供開發(fā)參考。1.2目標本規(guī)范為了指導各業(yè)務系統(tǒng)與服務總線平臺的對接，實現(xiàn)以1)2)當服務總線接入業(yè)務系統(tǒng)服務時，為該服務提供方提供

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

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

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

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

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

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

9、.Sync&msgld=crm_20130718_10001 &busiURI=/Sel ectSmslnf/1末位的“ 1是模擬業(yè)務參數(shù)。POST方式:http：/4：7080/oip/res?send=crm&servCode=1001. OP EN_3RD.Sync&msgld=crm_20130718_10001 &busiURI=/SelectSmsln f/1業(yè)務參數(shù)的內(nèi)容放在httP的請求體中傳輸3.2參數(shù)說明321系統(tǒng)級參數(shù)以下參數(shù)是由服務總線定義的。表格3-1系統(tǒng)級參數(shù)參數(shù)名類型是否必需描述Sendstring

10、是客戶端所屬系統(tǒng)編碼，填 與請參考3.1節(jié)（系統(tǒng)標 志全部采用此編碼）servCodestring是客戶端需要訪問的服務編 碼，由服務總線在注冊后 統(tǒng)一提供msgIdstring是由調(diào)用方系統(tǒng)按照 OIP規(guī) 則生成的唯標識次調(diào) 用的字符串，長度小于 64 位。生成規(guī)則： 系統(tǒng)名_當前時間戳_流水口號busiUrlstring是消費方傳遞的業(yè)務部分地 址App keyString否服務總線分配的應用標志transactionldString是交易流水號，由調(diào)用方生 成，多次請求均會包含此 信息。格式建議為系統(tǒng)名 _ 當前時間戳 流水號R1String否動態(tài)路由參數(shù)1R2String否動態(tài)路由參數(shù)

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

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

13、務使用方分配可使用服務的權(quán)限。IP地址鑒權(quán)：應用集成平臺支持服務使用方的IP地址身份認證模式。對于不在服務使用方申請的IP地址范圍內(nèi)產(chǎn)生的服口警。務調(diào)用，平臺給予攔截和告警。對于通過多重路由或映射導 致不能獲得實際IP地址時，將采用鑒權(quán)碼方式替代。摘要式認證：采用標準的HTTP摘要認證方式進行訪問認 證，具體介紹見參考文檔OAuth2.0:對于嚴格權(quán)限限制的場景，通過OAuth2.0協(xié)議進行認證和授權(quán)，授權(quán)由應用系統(tǒng)統(tǒng)一提供。4.2傳輸加密對于安全非常高的場合，建議全流程采用HTTPS協(xié)議進行加密傳輸，如繳費等場景。第5章異常分類編碼在使用平臺服務的過程中，平臺對不同的異常進行分類，供開發(fā)者和

14、使用方在調(diào)測及使用過程中參考。種類編碼描述正常0成功接口請求方 異常2消息格式異常，例如必填參數(shù)未填、消 息編碼異常等3無效的路由屬性10接口請求超過指定流量9接口請求包大小超過限制6權(quán)限異常（例如無權(quán)訪問此服務）101重復請求102無效的業(yè)務域或業(yè)務大類、小類199接口請求方其他異常接口響應方 異常8接口響應方超時201接口響應超過指疋流量202接口響應包大小超過限制298接口響應方內(nèi)部異常299接口響應方其他異常平臺異常4調(diào)用的服務未發(fā)布5調(diào)用的服務已注銷7調(diào)用的服務已關閉11調(diào)用的服務不存在1服務調(diào)用失敗398平臺內(nèi)部異常399平臺其他異常其他異常999其他異常測試異常601測試接口未實

15、現(xiàn)業(yè)務定義異 常>1000如果遇到上述類似異常代碼或信息，可以和平臺維護人員聯(lián) 系幫助解決。第6章 服務注冊、注銷、變更、調(diào)用流程6.1服務注冊的流程服務注冊和變更：由服務提供方在ITSM發(fā)起申請，經(jīng)服務評審后，由ITSM調(diào)用服務總線提供的能力進行注冊和變 更。服務注銷：由服務提供方或服務總線管理方根據(jù)實際需求和服務的調(diào)用次數(shù)等評估后發(fā)起，經(jīng)服務提供方、服務總線管理部門和服務調(diào)用方會審后在ITSM中發(fā)起下線流程。服務調(diào)用：由服務調(diào)用方發(fā)起，經(jīng)服務提供方確認和服務評審后在服務總線上進行注冊。服務評審由服務總線管理部門牽頭組織。6.2服務注冊的內(nèi)容名稱說明接口名稱接口編碼接口間要描述請求報文

16、樣例返回扌艮文樣例請求扌艮文格式定義返回扌艮文格式定義接口業(yè)務異常列表 和描述版本號對應的服務節(jié)點注冊服務地址探測扌艮文（可選）是否進行探測（時 間，頻度）備用服務地址（在 連續(xù)失敗或撥測失 敗等情況下自動或 手工切換服務地 址）6.3測試環(huán)境服務注冊的流程測試環(huán)境服務注冊由ITSM發(fā)起，在完成表單填寫后自動在 服務總線上進行處理。第7章服務治理7.1目標1、所有域的服務按照協(xié)議規(guī)范全部接入服務總線，避免出現(xiàn)服務未在服務總線直接使用。2、注冊在服務總線上的服務必須符合服務總線的規(guī)范，包括接口協(xié)議，數(shù)據(jù)格式，不得私自更改協(xié)議或超過注冊的 內(nèi)容升級接口內(nèi)容7.2檢查方法1、按照所有服務全部由服務總

17、線調(diào)用或者由F5負載均衡器調(diào)用的基本原則，服務管理團隊會定期對主機和F5上服務的調(diào)用方IP進行審核，如果出現(xiàn)服務端口出現(xiàn)非服務 總線或非F5主機的調(diào)用，或者 F5主機上服務端口非服務總線的調(diào)用，則認為出現(xiàn)了異常的服務調(diào)用，由服務提供方提供服務調(diào)用日志或版本變化情況進行詳細的解釋。2、服務接口參數(shù)應符合接口規(guī)范，服務總線將定期對服務調(diào)用異常、失敗、異常代碼等進行統(tǒng)計，給出服務接口的符合度。3、 服務返回的業(yè)務數(shù)據(jù)應符合注冊時提供的JSONSchema,不符合的則認為是注冊信息不全或異常升級。服務總線將定期從服務調(diào)用報文中進行格式校驗，對不符合格式的消息請求反饋服務提供方并要求進行說明。7.3服務監(jiān)控的指標指標類型運行類調(diào)用次數(shù)平均調(diào)用時長1秒以內(nèi)調(diào)用 次數(shù)1-5秒以內(nèi)調(diào) 用次數(shù)5秒以上調(diào)用 次數(shù)調(diào)用成功次數(shù)調(diào)用失敗次數(shù)調(diào)用超時次數(shù)非法調(diào)用個數(shù)常規(guī)類服務注冊個數(shù)服務變更個數(shù)服務注銷個數(shù)規(guī)范類異常服務接口 個數(shù)接口請求不合 規(guī)個數(shù)報文格式不合 規(guī)個數(shù)!-7.4服務目錄樹服務總線上注