esb-服务发布与调用规范.doc

南京银行 ecif 系统性能测试方 案 第 1 页 共 22 页 南京银行企业服务总线服务南京银行企业服务总线服务 发布与调用规范发布与调用规范 版本：v1.0 南京银行 ecif 系统性能测试方 案 第 2 页 共 22 页 1webservice 服务规范服务规范.3 1.1基本规范说明 .3 1.2报文总体组成 .3 1.2.1固定字段.3 1.2.2扩展字段.3 1.2.3业务字段.4 1.2.4请求报文.5 1.2.5响应报文.6 2接口规范接口规范 .7 2.1消息名称定义 .7 2.2消息定义 .8 2.3字段定义 .8 2.4命名空间定义 .8 2.5xml 发布 webservice.9 3服务发布标准实现服务发布标准实现 .10 3.1发布方法 .10 3.1.1xfire框架的服务发布步骤如下（java）：10 3.1.2cfx框架的服务发布步骤如下（java）：10 3.1.3axis框架的服务发布步骤如下（java）：10 3.1.4gsoap框架的服务发布步骤如下（c/c+）：11 3.1.5wcf框架的服务发布步骤如下（.net）：11 4服务调用标准实现服务调用标准实现 .13 4.1调用模式 .13 4.2调用方法 .13 4.2.1jax-ws 2.013 4.2.2apache cxf.15 4.2.3xfire16 4.2.4其他调用方式.19 4.3get 改 post19 5esb 系统生产环境系统生产环境 web 服务介绍服务介绍 .20 南京银行 ecif 系统性能测试方 案 第 3 页 共 22 页 1 webservice 服务规范服务规范 1.1 基本规范说明基本规范说明 消息格式：soap soap 绑定模式：document/literal 字符编码：utf-8 1.2 报文总体组成报文总体组成 报文体字段由三部分组成： 固定字段：每个服务都具备的字段，用来描述和标识请求与响应报文。 扩展字段：由于固定字段不能保证满足所有交易的请求与响应信息，各系统 可以根据需要对报文进行扩展。 服务相关字段：每个服务的请求与响应字段，即业务字段。 1.2.1固定字段固定字段 固定字段是服务的元数据类型，在模式文件 esb.xsd 文件中定义，包含了交易所用到的头信 息内容，所有通过 esb 发布的 webservice 服务，必须继承固定字段。 esb 固定字段定义文件： 1.2.2扩展字段扩展字段 扩展字段是为了满足服务提供者的请求报文和响应报文中特殊的报文公共头信息而设定的。 各业务系统可以根据需要定制扩展字段模式文件，并包含固定字段模式文件。 需要注意的是，扩展字段模式文件中的命名空间必须保持与固定字段模式文件中的命名空间 一致。 建议一个服务提供者的扩展字段模式文件只定义一个。 扩展字段模式文件定义示例（ecif.xsd）： 南京银行 ecif 系统性能测试方 案 第 4 页 共 22 页 客户类型 01：表示个人客户信息； 02：表示公司客户信息； 00：ecif 系统预留； 1.2.3业务字段业务字段 客户关联关系查询请求信息 识别方式,必填项 南京银行 ecif 系统性能测试方 案 第 5 页 共 22 页 客户编号 客户姓名 . 说明：说明：蓝色部分为字段注释，定义的蓝色部分为字段注释，定义的 schema 文件必须包含注释信息。文件必须包含注释信息。 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 认证信息，暂不使用 事例：事例： 100000000000 2003 1001000 9999 20080929 095050 01011 未开未开 南京银行 ecif 系统性能测试方 案 第 6 页 共 22 页 说明：说明：黑体为黑体为 esb 公共报文头，公共报文头，红色为服务系统公共扩展头，红色为服务系统公共扩展头，蓝色为服务相关字段。蓝色为服务相关字段。 1.2.5响应报文响应报文 固定字段：固定字段： 中文名称中文名称英文名称英文名称必填必填备注备注 交易流水号 seq_non 交易流水 服务号 service_idn 即交易号，对于细粒度服务不需要填写 机构号 bank_coden 请求操作员所属机构号 响应日期 tran_datey 格式 yyyymmdd，如 20110810 响应时间 tran_timey 格式 hhmmssnnn，如 092031218 交易状态 tran_statusy complete 表示成功，fail 表示失败 失败码 error_coden 交易失败时填写 失败描述 error_msgn 交易失败时填写 交易返回码 ret_coden 交易成功，同时需要返回响应码时，可填写 交易返回信息 描述 ret_msgn 交易成功，同时需要返回响应码时，可填写 事例：事例： 100000000000000 string 20080929 095050 complete 01 张飞张飞 zhangfei 说明：说明：黑体为黑体为 esb 公共报文头，公共报文头，红色为服务系统公共扩展头，红色为服务系统公共扩展头，蓝色为服务相关字段。蓝色为服务相关字段。 南京银行 ecif 系统性能测试方 案 第 7 页 共 22 页 2 接口规范接口规范 接口规范是对服务报文元素（soap 体中的元素）的定义和说明，为了便 于查阅，接口定义文件由 excel 文件编写。 一个服务代表一组相关操作的集合，一个服务包含多个操作，服务操作 包含如下内容： 2.1 消息名称定义消息名称定义 扩展输入消息定义 操作输入消息名：ecifrequestbase 类型名定义：业务系统简称+requestbase. 扩展输出消息定义 操作输入消息名：ecifresponsebase 类型名定义：业务系统简称+responsebase. 输入消息定义 操作输入消息名：relationinforequest 类型名定义：业务信息（首字母大写，词组组合的首字母大写）+request. 输出消息定义 操作输出消息名：relationinforesponse 类型名定义：业务信息（首字母大写，词组组合的首字母大写）+response 南京银行 ecif 系统性能测试方 案 第 8 页 共 22 页 相关完成代码备注 2.2 消息定义消息定义 消息包含如下定义（不需要列出固定字段）： 消息名称，即报文元素的名称。 报文元素的名命空间 各个子元素（报文字段）说明 2.3 字段定义字段定义 字段说明包含如下内容 字段名称：原则上是带有业务含义的字段名称，为了便于 java 系统使用， 可以采用 java 对象字段的书写习惯，小写开始、单词间隔用大写字母，同 时为了增加 esb 对 webservice 易维护性，对于非 webservice 服务的 webservice 服务化，尽量保持与原字段名称一致。 类型：可以采用 xml-schema 的类型。 长度：如果是字符串类型，应说明支持的最大长度。不写，为不限制长度。 是否允许空值。 格式：对于日期类型，应该说明日期的格式。其它类型如果有特殊格式要求， 应在此标注。 备注：对字段的附加说明。 2.4 命名空间定义命名空间定义 schema 命名空间定义： 南京银行 ecif 系统性能测试方 案 第 9 页 共 22 页 服务对应的数据类型命名空间： /系统名称/type/服务名/ esb 公用信息命名空间定义： /esb/ 扩展信息命名空间定义： 与 esb 公用信息命名空间保持一致，即：/esb/ 2.5 xml 发布发布 webservice 对于在 esb 中发布成 webservice 的 xml 格式报文，需要向 esb 提供服务接口定义文件 （schema） ，这里以 ecif 系统发布 webservice 服务为例，需要提供的文件如下： esb.xsd（esb 系统提供的接口定义文件，esb 固定字段，不可修改） ecif.xsd（ecif 系统提供的系统公共接口定义文件，扩展字段，各系统维护，可修改，如果没有 扩展字段可以不提供） relationinfo.xsd（ecif 系统对公客户交易接口定义文件，业务字段，可修改） 以上三个文件存在继承关系，ecif.xsd 继承 esb.xsd、orgcustinfo.xsd 继承 ecif.xsd，也就是扩展 字段继承 esb 固定字段，业务字段继承扩展字段；对于没有扩展字段的情况，则业务字段直接 继承 esb 固定字段即可。 南京银行 ecif 系统性能测试方 案 第 10 页 共 22页 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) 南京银行 ecif 系统性能测试方 案 第 11 页 共 22页 南京银行 ecif 系统性能测试方 案 第 12 页 共 22页 编写服务代码 部署 webservice 服务。 3.1.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.apache.axis.wsdl.wsdl2java server-side xxx.wsdl 生成服务端代码 南京银行 ecif 系统性能测试方 案 第 13 页 共 22页 编写服务代码 部署 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)/import cp $(gsoap_root)/stdsoap2.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_url% 对生成的代理类做下列处理： 去除所有类之前的 partial 关键字。 interface 的 servicecontract 属性必须和实现类方法的 servicebehavior、app.config 文件中 endpoint/bindingnamespace 的命名 空间都一致。 南京银行 ecif 系统性能测试方 案 第 14 页 共 22页 为所有定义类加上 datacontract 属性。 可去除异步实现方法和 channel 的定义。 使用 servicehost 类来承载服务，而不是用 iis 承载。 针对 servicehost 发布的 wsdl，使用特殊处理如下： 对于 xsd:import 的 schemalocation，手工下载并重命名。 对于命名空间是 /esb/的，重命名为 esb.xsd。 将上述 xsd 一并和 wsdl 交 esb 项目组发布。 南京银行 ecif 系统性能测试方 案 第 15 页 共 22页 4 服务调用标准实现服务调用标准实现 4.1 调用模式调用模式 本地化调用：客户端通过工具将服务发布者提供的 wsdl 本地化，生成本地 调用代码（即服务调用接口） ，客户端将服务当做一个本地接口进行调用。 动态调用：无需将 wsdl 本地化，在程序运行过程中，根据请求的 wsdl 动态 生成客户端以供调用。 本地化调用方式由于其执行效率优于动态调用，作为推荐调用方式使用，但不 做硬性要求。 4.2 调用方法调用方法 强烈推荐使用本地文件的方式生成代码，并通过本地文件中定义的服务地址访问强烈推荐使用本地文件的方式生成代码，并通过本地文件中定义的服务地址访问 esb 的的 web 服务（理由参见服务（理由参见 4.3） 。 4.2.1jax-ws 2.0 jax-ws 2.0 在 j2ee 5.0 中作为标准 web service api 被支持，jax-ws 2.0 不但在绑定方面更灵活，而且也是完全基于 annotation 的。 生成客户端示例（新）： wsimport-d d:workspacetemp -keep d:/esbservice/psnbaseinfoservice.wsdl 这里使用本地文件的方式生成客户端代码（重要）这里使用本地文件的方式生成客户端代码（重要） 。 使用 wsimport 命令生成本地化代码，如下所示： 南京银行 ecif 系统性能测试方 案 第 16 页 共 22页 调用方式如下： 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 test publicstaticvoid main(string args) / webservice客户端 psnbaseinfosoapqsservice service = newpsnbaseinfosoapqsservice(); / webservice接口 psnbaseinfoservicepsnbaseinfoservice = 南京银行 ecif 系统性能测试方 案 第 17 页 共 22页 service.getpsnbaseinfosoapqsport(); / 请求信息 baseinforequest request = newbaseinforequest(); / 赋值 request.setcertno(“330002220000000909“); / baseinforesponse response = null; / webservice调用 try / 执行调用并获取响应 response = psnbaseinfoservice.querybaseinfo(request); catch (soapfaultexception fault) / 异常处理 catch (exception e) / 异常处理 / 处理响应信息 if (response != null) system.out.println(response.getcerttype(); / else / 这里使用本地文件的方式生成客户端代码（重要）这里使用本地文件的方式生成客户端代码（重要） 4.2.2apache cxf apache cxf 是一个开源的 web 服务框架，可以发布和调用 web 服务。 wsdl2java 生成客户端 命令示例：wsdl2java -client helloworld.wsdl ant 示例： 南京银行 ecif 系统性能测试方 案 第 18 页 共 22页 调用方法片段： . psnbaseinfosoapqsservicess = newpsnbaseinfosoapqsservice(wsdlurl, service_name); psnbaseinfoservice port = ss.getpsnbaseinfosoapqsport(); mtbaseinforequestmodifyrequest = 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.3xfire xfire 是一个开源的 web 服务框架，可以发布和调用 web 服务。 利用 xfire 提供的 web service client 来调用发布的 webservice 服务。 南京银行 ecif 系统性能测试方 案 第 19 页 共 22页 生成 本地代码： 南京银行 ecif 系统性能测试方 案 第 20 页 共 22页 调用方式如下： 南京银行 ecif 系统性能测试方 案 第 21 页 共 22页 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。 南京银行 ecif 系统性能测试方 案 第 22 页 共 22页