ESB-服务规范.doc

.南京银行企业服务总线服务接口规范版本：v1.0目录第1章服务规范31.1基本规范31.2SOAP格式规范31.3报文总体组成4固定字段5扩展字段5请求报文6响应报文7出错报文81.4XML格式规范9请求报文10响应报文11第2章接口规范122.1服务操作定义122.2消息定义132.3字段定义132.5命名空间定义14第1章 服务规范1.1 基本规范 消息格式：SOAP SOAP绑定模式：document/literal 字符编码：UTF-81.2 SOAP格式规范先看一个SOAP报文示例：100000000000A6002200310010009999200809290950501110331004198808222239011weikaiSOAP消息的根元素是信封，信封报文主要由报文头（Header）和报文本（Body）构成，ESB的Web-Service将不使用Header，服务调用者可以忽略对Header的关注。因此，ESB的有效载荷在SOAP的Body内，每个Body都只有一个元素（为了便于描述，我们称它为ESB报文元素），这个元素的内部的XML（innerXML）即为要关注的实际报文。如果要了解ESB的接口规格只需简单了解ESB报文元素即可。接口文档的定义，也是针对ESB报文元素进行定义的。上例中的报文元素为：100000000000200310010009999200809290950501110331004198808222239011weikai该报文本中，最上面几个元素（黑体标注）为固定字段，所有服务报文都有这些字段。固定字段之后是可变字段，可变字段对于每个服务来说都是不一样的，具体规格由服务接口定义规范定义，其中中间的几个元素（斜体标注）为扩展字段，主要作用是解决各系统对报文公共头信息的特殊要求。1.3 报文总体组成报文体字段由三部分组成： 固定字段：每个服务都具备的字段，用来描述和标识请求与响应报文。 扩展字段：由于固定字段不能保证满足所有交易的请求与响应信息，各系统可以根据需要对报文进行扩展。 服务相关字段：每个服务的请求与响应字段，即业务字段。固定字段固定字段是服务的元数据类型，在模式文件esb.xsd文件中定义，包含了交易所用到的头信息内容，所有通过ESB发布的WebService服务，必须继承固定字段。ESB固定字段定义文件：扩展字段扩展字段是为了满足服务提供者的请求报文和响应报文中特殊的报文头信息而设定的。各业务系统可以根据需要定制扩展字段模式文件，并包含固定字段模式文件。需要注意的是，扩展字段模式文件中的命名空间必须保持与固定字段模式文件中的命名空间一致。建议一个服务提供者的扩展字段模式文件只定义一个。扩展字段模式文件定义示例：请求报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易号SERVICE_IDN服务交易编号，细粒度交易无需填写渠道代号CHANNEL_IDY请求渠道号机构号BANK_CODEY请求机构号操作员USER_IDY请求操作员号授权操作员AUTH_IDN授权操作员号请求日期TRAN_DATEY格式YYYYMMDD，如20110810请求时间TRAN_TIMEY格式HHMMSSNNN，如092031218认证信息AUTH_CONTEXTN认证信息，暂不使用示例100000000000200310010009999200809290950501110331004198808222239011weikai响应报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水服务号SERVICE_IDN即交易号，对于细粒度服务不需要填写机构号BANK_CODEN请求操作员所属机构号响应日期TRAN_DATEY格式YYYYMMDD，如20110810响应时间TRAN_TIMEY格式HHMMSSNNN，如092031218交易状态TRAN_STATUSYCOMPLETE表示成功，FAIL表示失败失败码ERROR_CODEN交易失败时填写失败描述ERROR_MSGN交易失败时填写交易返回码RET_CODEN交易成功，同时需要返回响应码时，可填写交易返回信息描述RET_MSGN交易成功，同时需要返回响应码时，可填写示例100000000000000string20080929095050COMPLETEststringstring张飞ZhangFei出错报文ESB系统内部错误，全部通过SOAP Fault返回出错报文，包含以下信息：Faultcode：错误码Faultstring：错误信息描述服务调用者可以通过捕获SOAPFaultException，获取错误信息。返回出错报文100000000000000string20080929095050FAILCIF5557客户不存在ststringstringSOAP出错报文E001the fault string1.4 XML格式规范先看一个XML报文示例： 101000059173 0202 ECIF 9957 99957018 20111108 152859843 1025919289 该报文本中，HEAD标签中上面几个元素（黑体标注）为固定字段，所有服务报文都有这些字段。固定字段之后是可扩展字段，可扩展字段对于每个服务来说都是不一样的，具体规格由服务接口定义规范定义，其中中间的几个元素（斜体标注）为扩展字段，主要作用是解决各系统对报文头信息的特殊要求。BODY标签中的字段为业务字段，具体的结构和内容由服务接口定义。请求报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易代码SERVICE_IDY服务交易代码渠道代号CHANNEL_IDY请求渠道号机构号BANK_CODEY请求机构号请求日期TRAN_DATEY格式YYYYMMDD，如20110810请求时间TRAN_TIMEY格式HHMMSSNNN，如092031218扩展信息EXT_HEADN扩展信息，特殊需要的时候添加，由ESB做特殊处理示例 101000059173 0202 ECIF 9957 99957018 20111108 152859843 1025919289 响应报文固定字段中文名称英文名称必填备注交易流水号SEQ_NON交易流水交易代码SERVICE_IDN交易代码机构号BANK_CODEN请求操作员所属机构号响应日期TRAN_DATEY格式YYYYMMDD，如20110810响应时间TRAN_TIMEY格式HHMMSSNNN，如092031218交易状态TRAN_STATUSYCOMPLETE表示成功，FAIL表示失败扩展信息EXT_HEADN公共扩展信息失败码ERROR_CODEN交易失败时填写失败描述ERROR_MSGN交易失败时填写交易返回码RET_CODEN交易成功，同时需要返回响应码时，可填写交易返回信息描述RET_MSGN交易成功，同时需要返回响应码时，可填写示例1010000591730202995720111108152859843COMPLETE第2章 接口规范接口规范是对服务报文元素（SOAP体中的元素）的定义和说明，为了便于查阅，接口定义文件由Excel文件编写。一个服务代表一组相关操作的集合，一个服务包含多个操作，服务操作包含如下内容：2.1 服务操作定义 操作ID 操作名称 操作描述 所属的Web-Service的EndPoint URI原子服务定义方式为：应用路径/表名+Service例如对公客户基本信息维护服务：http:/ip:port/EsbService/PSNBaseInfoService Web-Service操作名称(Operation Name)查询客户清单操作：queryPersonList 输入消息定义操作输入消息名：PersonListRequest类型名定义：业务信息（首字母大写，词组组合的首字母大写）+Request. 输出消息定义操作输出消息名：PersonListResponse类型名定义：业务信息（首字母大写，词组组合的首字母大写）+Response 相关完成代码备注2.2 消息定义消息包含如下定义（不需要列出固定字段）： 消息名称，即报文元素的名称。 报文元素的名命空间 各个子元素（报文字段）说明2.3 字段定义字段说明包含如下内容 字段名称：原则上是带有业务含义的字段名称，为了便于Java系统使用，可以采用java对象字段的书写习惯，小写开始、单词间隔用大写字母，同时为了增加ESBWebService易维护性，对于非WebService服务的WebService服务化，尽量保持与原字段名称一致。 类型：可以采用XML-Schema的类型。 长度：如果是字符串类型，应说明支持的最大长度。不写，为不限制长度。 是否允许空值。 格式：对于日期类型，应该说明日期的格式。其它类型如果有特殊格式要求，应在此标注。 备注：对字段的附加说明。2.5命名空间定义 Schema命名空间定义：n 服务对应的数据类型命名空间：/系统名称/type/服务名/ WSDL命名空间定义：/系统名称/服务名称（首字母大写，词组组合的首字母大写）+ Service/ ESB公用信息命名