esb服务发布与调用规范

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