1、南京銀行企業服務總線服務南京銀行企業服務總線服務發布與調用規范發布與調用規范版本：v1.01webservice 服務規范服務規范.31.1基本規范說明 .31.2報文總體組成 .31.2.1固定字段.31.2.2擴展字段.31.2.3業務字段.41.2.4請求報文.51.2.5響應報文.62接口規范接口規范 .72.1消息名稱定義 .72.2消息定義 .82.3字段定義 .82.4命名空間定義 .82.5xml 發布 webservice.93服務發布標準實現服務發布標準實現 .103.1發布方法 .103.1.1xfire框架的服務發布步驟如下（java）：.103.1.2cfx框架的服務

2、發布步驟如下（java）：.103.1.3axis框架的服務發布步驟如下（java）：.103.1.4gsoap框架的服務發布步驟如下（c/c+）：.113.1.5wcf框架的服務發布步驟如下（.net）：.114服務調用標準實現服務調用標準實現 .134.1調用模式 .134.2調用方法 .134.2.1jax-ws .2apache cxf.154.2.3xfire.164.2.4其他調用方式.194.3get 改 post.195esb 系統生產環境系統生產環境 web 服務介紹服務介紹 .201 webservice 服務規范服務規范1.1 基本規范說明基本規范說明消

3、息格式：soapsoap 綁定模式：document/literal字符編碼：utf-81.2 報文總體組成報文總體組成報文體字段由三部分組成：固定字段：每個服務都具備的字段，用來描述和標識請求與響應報文。擴展字段：由于固定字段不能保證滿足所有交易的請求與響應信息，各系統可以根據需要對報文進行擴展。服務相關字段：每個服務的請求與響應字段，即業務字段。1.2.1固定字段固定字段固定字段是服務的元數據類型，在模式文件 esb.xsd 文件中定義，包含了交易所用到的頭信息內容，所有通過 esb 發布的 webservice 服務，必須繼承固定字段。esb 固定字段定義文件：1.2.2擴展字段擴展字段

4、擴展字段是為了滿足服務提供者的請求報文和響應報文中特殊的報文公共頭信息而設定的。各業務系統可以根據需要定制擴展字段模式文件，并包含固定字段模式文件。需要注意的是，擴展字段模式文件中的命名空間必須保持與固定字段模式文件中的命名空間一致。建議一個服務提供者的擴展字段模式文件只定義一個。擴展字段模式文件定義示例（ecif.xsd）： 客戶類型 01：表示個人客戶信息； 02：表示公司客戶信息； 00：ecif 系統預留； 1.2.3業務字段業務字段 客戶關聯關系查詢請求信息 識別方式,必填項 客戶編號 客戶姓名 . .說明：說明：藍色部分為字段注釋，定義的藍色部分為字段注釋，定義的 schema 文

5、件必須包含注釋信息。文件必須包含注釋信息。1.2.4請求報文請求報文固定字段：固定字段：中文名稱中文名稱英文名稱英文名稱必填必填備注備注交易流水號seq_non交易流水交易號service_idn服務交易編號，細粒度交易無需填寫渠道代號channel_idy請求渠道號機構號bank_codey請求機構號操作員user_idy請求操作員號授權操作員auth_idn授權操作員號請求日期tran_datey格式 yyyymmdd，如 20110810請求時間tran_timey格式 hhmmssnnn，如 092031218認證信息auth_contextn認證信息，暫不使用事例：事例：100000

6、0000002003100100099992008092909505001331004198808222239011未開未開 說明：說明：黑體為黑體為 esb 公共報文頭，公共報文頭，紅色為服務系統公共擴展頭，紅色為服務系統公共擴展頭，藍色為服務相關字段。藍色為服務相關字段。1.2.5響應報文響應報文固定字段：固定字段：中文名稱中文名稱英文名稱英文名稱必填必填備注備注交易流水號seq_non交易流水服務號service_idn即交易號，對于細粒度服務不需要填寫機構號bank_coden請求操作員所屬機構號響應日期tran_datey格式 yyyymmdd，如 20110810響應時間tran_

7、timey格式 hhmmssnnn，如 092031218交易狀態tran_statusycomplete 表示成功，fail 表示失敗失敗碼error_coden交易失敗時填寫失敗描述error_msgn交易失敗時填寫交易返回碼ret_coden交易成功，同時需要返回響應碼時，可填寫交易返回信息描述ret_msgn交易成功，同時需要返回響應碼時，可填寫事例：事例：100000000000000string20080929095050complete01張飛張飛zhangfei說明：說明：黑體為黑體為 esb 公共報文頭，公共報文頭，紅色為服務系統公共擴展頭，紅色為服務系統公共擴展頭，藍色為服

8、務相關字段。藍色為服務相關字段。2 接口規范接口規范接口規范是對服務報文元素（soap 體中的元素）的定義和說明，為了便于查閱，接口定義文件由 excel 文件編寫。一個服務代表一組相關操作的集合，一個服務包含多個操作，服務操作包含如下內容：2.1 消息名稱定義消息名稱定義擴展輸入消息定義操作輸入消息名：ecifrequestbase類型名定義：業務系統簡稱+requestbase.擴展輸出消息定義操作輸入消息名：ecifresponsebase類型名定義：業務系統簡稱+responsebase.輸入消息定義操作輸入消息名：relationinforequest類型名定義：業務信息（首字母大寫

9、，詞組組合的首字母大寫）+request.輸出消息定義操作輸出消息名：relationinforesponse類型名定義：業務信息（首字母大寫，詞組組合的首字母大寫）+response相關完成代碼備注2.2 消息定義消息定義消息包含如下定義（不需要列出固定字段）：消息名稱，即報文元素的名稱。報文元素的名命空間各個子元素（報文字段）說明2.3 字段定義字段定義字段說明包含如下內容字段名稱：原則上是帶有業務含義的字段名稱，為了便于 java 系統使用，可以采用 java 對象字段的書寫習慣，小寫開始、單詞間隔用大寫字母，同時為了增加 esb 對 webservice 易維護性，對于非 webser

10、vice 服務的webservice 服務化，盡量保持與原字段名稱一致。類型：可以采用 xml-schema 的類型。長度：如果是字符串類型，應說明支持的最大長度。不寫，為不限制長度。是否允許空值。格式：對于日期類型，應該說明日期的格式。其它類型如果有特殊格式要求，應在此標注。備注：對字段的附加說明。2.4 命名空間定義命名空間定義schema 命名空間定義：服務對應的數據類型命名空間：http:/ 公用信息命名空間定義：http:/ esb 公用信息命名空間保持一致，即：http:/ xml 發布發布 webservice對于在 esb 中發布成 webservice 的 xml 格式報文，

11、需要向 esb 提供服務接口定義文件（schema） ，這里以 ecif 系統發布 webservice 服務為例，需要提供的文件如下：esb.xsd（esb 系統提供的接口定義文件，esb 固定字段，不可修改）ecif.xsd（ecif 系統提供的系統公共接口定義文件，擴展字段，各系統維護，可修改，如果沒有擴展字段可以不提供）relationinfo.xsd（ecif 系統對公客戶交易接口定義文件，業務字段，可修改）以上三個文件存在繼承關系，ecif.xsd 繼承 esb.xsd、orgcustinfo.xsd 繼承 ecif.xsd，也就是擴展字段繼承 esb 固定字段，業務字段繼承擴展字

12、段；對于沒有擴展字段的情況，則業務字段直接繼承 esb 固定字段即可。3 服務發布標準實現服務發布標準實現本章主要介紹如何通過一個已經存在的 wsdl 文件創建一個 web service 服務3.1 發布方法發布方法3.1.1xfire 框架的服務發布步驟如下（框架的服務發布步驟如下（java）：）：將服務的請求和響應字段、服務 action 交 esb 項目組，確認 wsdl 符合 esb 規范。new web service,create web service from wsdl document(top-down scenario)編寫服務代碼部署 webservice 服務。3.1

13、.2cfx 框架的服務發布步驟如下（框架的服務發布步驟如下（java）：）：配置 cfx 環境變量將服務的請求和響應字段、服務 action 交 esb 項目組，確認 wsdl 符合 esb 規范。利用 wsdl2java server xxx.wsdl 生成服務端代碼編寫服務代碼部署 webservice 服務。3.1.3axis 框架的服務發布步驟如下（框架的服務發布步驟如下（java）：）：服務器上部署 axis將服務的請求和響應字段、服務 action 交 esb 項目組，確認 wsdl 符合 esb 規范。利用 java djava.ext.dirs=axis-lib org.apa

14、che.axis.wsdl.wsdl2java server-side xxx.wsdl 生成服務端代碼編寫服務代碼部署 webservice 服務。3.1.4gsoap 框架的服務發布步驟如下（框架的服務發布步驟如下（c/c+）：）：將服務的請求和響應字段、服務 action 交 esb 項目組，確認 wsdl 符合 esb 規范。使用類似腳本將需要的文件和信息下載到本地文件夾。wsdl2h -c -o $(trancode).h $(wsdl_url)soapcpp2 -s $(trancode).h -c -i $(gsoap_root)/importcp $(gsoap_root)/s

15、tdsoap2.c .cp $(gsoap_root)/stdsoap2.h .編寫服務代碼。重載 gsoap 服務主函數，實現 http get wsdl 和 xsd 的方法。注意：使用 iconv 庫來將輸入和輸出字段進行轉碼。esb 使用 utf-8 字符集。3.1.5wcf 框架的服務發布步驟如下（框架的服務發布步驟如下（.net）：）：將服務的請求和響應字段、服務 action 交 esb 項目組，確認 wsdl 符合 esb 規范。使用下面腳本生成服務的代理類。svcutil /language:c# /out:%interface%.cs /n:*,%clr_ns% %wsdl_

16、url%對生成的代理類做下列處理：去除所有類之前的 partial 關鍵字。interface 的 servicecontract 屬性必須和實現類方法的servicebehavior、app.config 文件中 endpoint/bindingnamespace 的命名空間都一致。為所有定義類加上 datacontract 屬性。可去除異步實現方法和 channel 的定義。使用 servicehost 類來承載服務，而不是用 iis 承載。針對 servicehost 發布的 wsdl，使用特殊處理如下：對于 xsd:import 的 schemalocation，手工下載并重命名。對于

17、命名空間是 http:/ esb.xsd。將上述 xsd 一并和 wsdl 交 esb 項目組發布。4 服務調用標準實現服務調用標準實現4.1 調用模式調用模式本地化調用：客戶端通過工具將服務發布者提供的 wsdl 本地化，生成本地調用代碼（即服務調用接口） ，客戶端將服務當做一個本地接口進行調用。動態調用：無需將 wsdl 本地化，在程序運行過程中，根據請求的 wsdl 動態生成客戶端以供調用。本地化調用方式由于其執行效率優于動態調用，作為推薦調用方式使用，但不做硬性要求。4.2 調用方法調用方法強烈推薦使用本地文件的方式生成代碼，并通過本地文件中定義的服務地址訪問強烈推薦使用本地文件的方式

18、生成代碼，并通過本地文件中定義的服務地址訪問 esb 的的web 服務（理由參見服務（理由參見 4.3） 。4.2.1jax-ws 2.0jax-ws 2.0 在 j2ee 5.0 中作為標準 web service api 被支持，jax-ws 2.0不但在綁定方面更靈活，而且也是完全基于 annotation 的。生成客戶端示例（新）：wsimport-d d:workspacetemp -keep d:/esbservice/psnbaseinfoservice.wsdl這里使用本地文件的方式生成客戶端代碼（重要）這里使用本地文件的方式生成客戶端代碼（重要） 。使用 wsimport 命

19、令生成本地化代碼，如下所示：調用方式如下：packagecom.demo;importjavax.xml.ws.soap.soapfaultexception;.njcb.ecif.psnbaseinfo.psnbaseinfosoapqsservice;.njcb.ecif.psnbaseinfo.psnbaseinfoservice;.njcb.ecif.type.psnbaseinfo.baseinforequest;.njcb.ecif.type.psnbaseinfo.baseinforesponse;/* * api 調用示例 * * author * */publicclass

20、test publicstaticvoid main(string args) / webservice客戶端psnbaseinfosoapqsservice service = newpsnbaseinfosoapqsservice();/ webservice接口psnbaseinfoservicepsnbaseinfoservice = service.getpsnbaseinfosoapqsport();/ 請求信息baseinforequest request = newbaseinforequest();/ 賦值request.setcertno(33000222000000090

21、9);/ .baseinforesponse response = null;/ webservice調用try / 執行調用并獲取響應response = psnbaseinfoservice.querybaseinfo(request);catch (soapfaultexception fault) / 異常處理catch (exception e) / 異常處理/ 處理響應信息if (response != null) system.out.println(response.getcerttype();/ .else / .這里使用本地文件的方式生成客戶端代碼（重要）這里使用本地文件的

22、方式生成客戶端代碼（重要）4.2.2apache cxfapache cxf 是一個開源的 web 服務框架，可以發布和調用 web 服務。 wsdl2java 生成客戶端命令示例：wsdl2java -client helloworld.wsdlant 示例：調用方法片段：.psnbaseinfosoapqsservicess = newpsnbaseinfosoapqsservice(wsdlurl, service_name);psnbaseinfoservice port = ss.getpsnbaseinfosoapqsport();mtbaseinforequestmodifyre

23、quest = null;try mtbaseinforesponsemodifyresponse = port.modifybaseinfo(modifyrequest);system.out.println(modifybaseinfo.result= + modifyresponse.geterrorcode(); catch (soapfaultexception e) system.out.println(e.getfault().getfaultcode();system.out.println(e.getfault().getfaultstring();.4.2.3xfirexf

24、ire 是一個開源的 web 服務框架，可以發布和調用 web 服務。利用 xfire 提供的 web service client 來調用發布的 webservice 服務。生成本地代碼：調用方式如下：4.2.4其他調用方式其他調用方式4.3 get 改改 post問題問題：調用 esb webservice 服務時，使用了 get 方法，怎么無縫的不改代碼框架支持 post ?方式方式:某系統請求 esb 的服務，有兩種方式:一種通過 url 的地址直接請求。一種通過讀 wsdl 文件的地址請求。例子例子: :通過 url：方式一：url = new url(93:8001/esbservice/cnaps2wyp3201?wsdl);通過wsdl文件：方式二：url = new url(file:/d:/workspaces/soap/wsdl/cnaps2wyp3201.wsdl);方法：方法：get 改 post 只需把方式一改成方式二。就可無縫不改代碼框架支持 post。5 esb 系統生產環境系統生產環境 web 服務介紹服務介紹服務 ip 和端口：esb 生產環境中，會將服務發布在 6 個端口中，分別為28：8001、8002、8003，13