南车电机ESB项目服务接口规范

1、南车电机ESB项目服务接口规范上海普元信息技术股份有限公司目录1规范建设31.1服务接入规范31.1.1同步异步交互场景31.1.2服务描述规范61.1.3请求报文规范71.1.4响应报文规范101.1.5确认报文规范131.1.6异常报文规范151.1.7报文大小规范181.2集成平台编码规范181.2.1服务编码规范181.2.2操作编码规范191.2.3异常编码规范201.2.4请求编码规范211.2.5版本编码规范231.2.6应用编码规范241.3服务管控规范251.3.1注册服务251.3.2变更服务251.3.3注销服务261 规范建设南车电机已建成多个应用系统和工具系统，各系统

2、间接口集成技术不统一，交换信息格式差异大，缺乏规范化和标准化，这使系统不断增加和建设的过程中，系统间接口技术、类型不统一，使系统集成更趋复杂化。因此，从管理和维护角度，需要建设南车电机统一信息交换接口服务规范，从服务接入规范、服务编码规范和服务管控规范多个方面，通过注册、封装、重新发布各应用系统原有集成接口，并规定新系统接口，规范系统集成接口，使系统建设和信息集成更加规范化。1.1 服务接入规范根据接口业务特征，在服务接入总线时，需要定义服务调用的同步或者异步调用。由于同步、异步通信在各自技术上特性不同，同步指发送方发出数据后，等接收方发回响应以后才发下一个数据包的通讯方式，这种通信方式，在集

3、成接口中更适合实时信息的传输，如调用编码系统，对材料实例进行编码等；异步调用指发送方发出数据后，不等接收方发回响应，接着发送下个数据包的通讯方式，这种通信方式，在集成接口中更适合非实时信息的传输，如对表单填写时服务端数据校验，当填完表单第一个属性值，接着填写第二个属性值，不需要等待第一个值的服务端数据校验响应，界面不会停卡在第一个表单，不会影响用户继续下一个表单填写，增强用户体验，用户在客户端与服务端数据通信，操作上更加人性化。1.1.1 同步异步交互场景服务规范对同步服务调用、异步服务调用两种典型的服务交互场景作了详尽的描述和规定： l 同步调用场景步骤描述：1) 服务消费者应用系统A调用服

4、务总线ESB上发布的某个服务，即服务消费者发送请求报文到服务总线ESB，在服务总线ESB返回处理结果之前，服务消费者一直处于等待状态；2) 服务总线ESB接收请求报文并作处理；3) 服务总线ESB将该请求报文按照规则转发到服务提供者应用系统B；4) 服务提供者应用系统B处理该请求报文； 5) 服务提供者应用系统B返回处理结果；6) 服务总线ESB对服务提供者应用系统B返回的结果进行处理；7) 服务总线ESB将处理结果返回给服务消费者应用系统A；8) 到此为止，一次同步调用完毕（1步7步），服务消费者应用系统A继续处理其他业务逻辑；l 异步调用场景步骤描述：1) 服务消费者应用系统A向注册在服务

5、总线ESB上的服务发起服务调用；2) 服务总线ESB保存请求报文；3) 服务总线ESB向服务消费者应用系统A反馈收到请求报文；4) 到此为止，服务消费者应用系统A可以不必等待服务提供者业务系统B的处理结果，而继续处理其他逻辑。5) 服务总线ESB将持久化的服务请求报文转发到服务提供者应用系统B暴露的服务上；6) 服务提供者应用系统B保存请求报文； 7) 服务提供者应用系统B向服务总线ESB反馈确认报文；8) 到此为止，服务总线ESB不必继续等待服务提供者业务系统B的处理结果 。9) 服务提供者应用系统B处理请求报文；10) 到此为止，没有任何其他系统的进程在等待服务提供者应用系统B的处理结果

6、。11) 服务提供者应用系统B将处理结果发送给注册在服务总线ESB上的服务；12) 服务总线ESB保存处理结果；13) 服务总线ESB向服务提供者应用系统B反馈收到请求报文； 14) 到此为止，没有任何系统的进程在等待服务提供者应用系统B的处理结果 。15) 服务总线ESB将处理结果发送到服务消费者应用系统A暴露的服务上。16) 服务消费者应用系统A保存处理结果；17) 服务消费者应用系统A向服务总线ESB发送确认消息报文；到此为止，整个闭环的业务操作执行完毕，这个处理过程以异步的形式被分割成若干互补等待的处理过程。1.1.2 服务描述规范l 规范描述服务描述规范主要说明接口服务的描述形式，服

7、务使用者就可以根据服务描述了解服务的技术实现形式、功能和输入/输出等信息 。业务系统向外暴露的服务和ESB向外暴露的服务都需要通过WSDL的方式进行描述，这样使得相关人员可以根据WSDL开发服务调用客户端，WSDL需遵循如下相关标准：标准版本WSDLWSDL1.1WS-IWS-I Basic Profile 1.11)soap - "/soap/envelope/"2)xsi - "/2001/XMLSchema-instance"3)xsd - "http:/w

8、/2001/XMLSchema"4)soapenc - "/soap/encoding/"5)wsdl - "/wsdl/"6)soapbind - "/wsdl/soap/"备注：1) 对于业务系统如何规划WSDL文件不在本规范讨论范围内；l 规范样例样例一：WSDL接口描述文件<?xml version='1.0' encoding=

9、'UTF-8'?><s0:definitions name="CustomerInfoServiceDefinitions" targetNamespace="http:/com/alsb/hello" xmlns="" xmlns:s0="/wsdl/" xmlns:s1="http:/com/alsb/hello" xmlns:s2="/wsdl/soap

10、/"> <s0:types> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http:/com/alsb/hello" xmlns:xs="/2001/XMLSchema"> <xs:element name="getCustomerInfo"> <xs:comple

11、xType> <xs:sequence> <xs:element name="lenght" type="xs:long"/> </xs:sequence> </xs:complexType> </s0:service></s0:definitions>1.1.3 请求报文规范 规范概述(一) 相关标准：服务消费者服务客户端运行时需要使用SOAP报文与ESB上暴露的服务进行交互，需遵循如下相关标准：标准版本SOAPSOAP1.1WS-IWS-I Basic Pro

12、file 1.11)soap - "/soap/envelope/"2)xsi - "/2001/XMLSchema-instance"3)xsd - "/2001/XMLSchema"4)soapenc - "/soap/encoding/"5)wsdl - "/wsdl/"6)so

13、apbind - "/wsdl/soap/"(二) SOAP Header：服务消费者服务客户端调用服务的还需设置SOAP Header内容，具体如下：属性名称数据类型说明Version版本字符型1) 被调用服务操作的版本标识；2) 关于版本编码详见“5.5 版本编码规范”章节；RequestID-BIZ1)RequestID-ESB请求编码字符型2) 服务调用客户端提交的请求的唯一标识；3) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestI

14、D；4) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；5) 关于请求编码详见“5.4 请求编码规范”章节；AppID应用编码字符型1) 应用编码，即发起请求的应用系统的编码；2) 关于应用编码详见“5.6 应用编码规范”章节；(三) HTTP Header：服务消费者服务客户端调用服务的还需设置HTTP Header内容，具体如下：属性名称数据类型说明Version版本字符型1) 被调用服务操作的版本标识；2) 关于版本编码详见“5.5 版本编码规范”章节；RequestID请求编码字符型1) 服务调用客户端提交的请求的唯

15、一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；AppID应用编码字符型1) 应用编码，即发起请求的应用系统的编码；2) 关于应用编码详见“5.6 应用编码规范”章节；(四) SOAP Body：请求报文的SOAP Body内容由具体的服务描述文件WSDL来定义 。 规范样例样例一：SOAP请求报文POST

16、/com.primeton.boss.billing.CustomerInfoService HTTP/1.1Host: service.sh.cmccVersion:v1.0RequestID: com.primeton.billing-20110808-000000000012AppID: com.primeton.boss.billingContent-Type: application/soap+xml; charset=utf-8Content-Length: length<?xml version="1.0"?><soap:Envelope x

17、mlns:soap="/2001/12/soap-envelope" xmlns:cust="http:/com/alsb/hello" soap:encodingStyle="/2001/12/soap-encoding"><soap:Header><Version>v1.0</Version>< RequestID> com.primeton.boss.billing-20110808-000000000012&l

18、t;/RequestID >< AppID>com.primeton.boss.billing< AppID/></soap:Header><soap:Body><cust:getCustomerInfo><cust:lenght>10</cust:lenght></cust:getCustomerInfo></soap:Body></soap:Envelope>1.1.4 响应报文规范 规范概述(一) 相关标准：服务提供者运行时需要使用SOAP报文与ES

19、B进行交互，并遵循如下相关标准：标准版本SOAPSOAP1.1WS-IWS-I Basic Profile 1.11)soap - "/soap/envelope/"2)xsi - "/2001/XMLSchema-instance"3)xsd - "/2001/XMLSchema"4)soapenc - "/soap/encoding/"5)wsdl

20、- "/wsdl/"6)soapbind - "/wsdl/soap/"(二) SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID-BIZ1)RequestID-ESB请求编码字符型2) 服务调用客户端提交的请求的唯一标识；3) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；4) Reque

21、stID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；5) 关于请求编码详见“5.4 请求编码规范”章节；(三) HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用

22、系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；(四) SOAP Body：响应报文的SOAP Body内容由具体的服务描述文件WSDL来定义 。 规范样例样例一：SOAP响应报文HTTP/1.0 200 OKRequestID: com.primeton.boss.billing-20110808-000000000012Date: Tue, 13 Mar 2001 02:45:12 GMTServer: Apache/1.3.12 (Unix) Content-Type: text/xml Connection: close <?xml version

23、="1.0"?><soap:Envelope xmlns:soap="/2001/12/soap-envelope" xmlns:cust="http:/com/alsb/hello"soap:encodingStyle="/2001/12/soap-encoding"><soap:Header>< RequestID> com.primeton.boss.billing-20110808-0000000000

24、12</RequestID ></soap:Header><soap:Body>< cust:getCustomerInfoResponse xmlns="</cust:getCustomerInfoResponse></soap:Body></soap:Envelope>1.1.5 确认报文规范 规范概述确认报文主要使用在异步调用场景，有请求报文的接受方向报文的发送方确认已经正确收到报文。(一) 相关标准：服务提供者运行时需要使用SOAP报文与ESB进行交互，并遵循如下相关标准：标准版本SO

25、APSOAP1.1WS-IWS-I Basic Profile 1.11)soap - "/soap/envelope/"2)xsi - "/2001/XMLSchema-instance"3)xsd - "/2001/XMLSchema"4)soapenc - "/soap/encoding/"5)wsdl - "http:/schemas.

26、/wsdl/"6)soapbind - "/wsdl/soap/"(二) SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在

27、相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；(三) HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型5) 服务调用客户端提交的请求的唯一标识；6) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；7) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；8) 关于请求编码详见“5.4 请求编码规范”章节；(四) SOAP

28、 Body：确认报文的SOAP Body内容为“OK”。 规范样例样例一：SOAP响应报文HTTP/1.0 200 OKRequestID: com.primeton.boss.billing-20110808-000000000012Date: Tue, 13 Mar 2001 02:45:12 GMTServer: Apache/1.3.12 (Unix) Content-Type: text/xml Connection: close <?xml version="1.0"?><soap:Envelope xmlns:soap=&quo

29、t;/2001/12/soap-envelope" soap:encodingStyle="/2001/12/soap-encoding"><soap:Header>< RequestID> com.primeton.boss.billing-20110808-000000000012</RequestID ></soap:Header><soap:Body>ok</soap:Body></soap:Envelope&

30、gt;1.1.6 异常报文规范 规范概述异常报文在同步、异常场景下都可以用到,在同步场景下作为异常响应报文，在同步场景下作为异常确认报文。(一) 相关标准：服务提供者运行时需要使用SOAP报文与ESB进行交互，并遵循如下相关标准：标准版本SOAPSOAP1.1WS-IWS-I Basic Profile 1.11)soap - "/soap/envelope/"2)xsi - "/2001/XMLSchema-instance"3)xsd - "ht

31、tp://2001/XMLSchema"4)soapenc - "/soap/encoding/"5)wsdl - "/wsdl/"6)soapbind - "/wsdl/soap/"(二) SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的

32、请求的唯一标识；2) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；(三) HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有Reques

33、tID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；(四) SOAP Body：可选的 SOAP Fault元素用于指示错误消息。如果已提供了Fault元素，则它必须是 Body 元素的子元素。在一条 SOAP 消息中，Fault 元素只能出现一次。SOAP 的 Fault 元素拥有下列子元素：属性说明<faultcode>供识别故障的代码，详见“6.3 异常编码”章节；<faultstri

34、ng>可供人阅读的有关故障的说明；<faultactor>有关是谁引发故障的信息；<detail>存留涉及 Body 元素的应用程序专用错误信息； 规范样例样例一：异常报文HTTP/1.0 200 OKRequestID: com.primeton.boss.billing-20110808-000000000012Date: Tue, 13 Mar 2001 02:45:12 GMTServer: Apache/1.3.12 (Unix) Content-Type: text/xml Connection: close<?xml versio

35、n="1.0"?><soap:Envelope xmlns:soap="/2001/12/soap-envelope" soap:encodingStyle="/2001/12/soap-encoding"><soap:Header><RequestID> com.primeton.boss.billing-20110808-000000000012</RequestID></soap:Header><

36、;soap:Body><soap:fault><faultcode>Client.AuthenticationFailure</faultcode><faultstring>认证失败</faultstring><faultactor><detail></detail></ soap:fault></soap:Body></soap:Envelope>1.1.7 报文大小规范 规范目标限制单次服务调用所携带的数据量大小有助于降低服务总线的负载，提

37、高服务总线的性能。 规范概述单笔服务多携带的数据量上限为300K。1.2 集成平台编码规范1.2.1 服务编码规范 规范概述服务是若干操作的集合体，业务相关的若干操作可以组合成一个业务目标明确的服务，通过服务名称的规范化有助于开发人员理解服务的业务意义。服务规范主要应用于服务定义文件WSDL和ESB部署过程中。 编码规范操作编码规则：<应用编码>.<服务名称>其中应用编码详见“4.2.6 应用编码规范”章节。 规范样例<?xml version='1.0' encoding='UTF-

38、8'?><s0:definitions name="CustomerInfoServiceDefinitions" targetNamespace="http:/com/alsb/hello" xmlns="" xmlns:s0="/wsdl/" xmlns:s1="http:/com/alsb/hello" xmlns:s2="/wsdl/soap/"&g

39、t; <s0:service name="CustomerInfoService"> <s0:port binding="s1:CustomerInfoServiceSoapBinding" name="CustomerInfoPort"> <s2:address location="http:/localhost:7001/com.primeton.boss.billing.CustomerInfoService"/> </s0:port> </s0:serv

40、ice></s0:definitions>这个样例说明了应用编码为“com.sysware.mdm.code”的系统对外暴露的com.primeton. sysware.mdm.CustomerInfoService服务。1.2.2 操作编码规范 规范概述操作编码规范主要体现在服务定义的wsdl文件中对操作编码的定义，“操作”是实际承载业务逻辑的实体，业务关联较强的若干“操作”组成一个“服务”。对“操作”名称的规范有助于相关人员更直观地理解某操作的业务功能。 编码规范操作编码规则：<动宾短语>+SYN使用动宾短语表示某一操作的业务功能，

41、该短语不宜过长。 规范样例样例一：WSDL接口描述文件<?xml version='1.0' encoding='UTF-8'?><s0:definitions name="CustomerInfoServiceDefinitions" targetNamespace="http:/com/alsb/hello" xmlns="" xmlns:s0="/wsdl/" xmlns:s1="htt

42、p:/com/alsb/hello" xmlns:s2="/wsdl/soap/"> <s0:types> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http:/com/alsb/hello" xmlns:xs="/2001/XMLSchema&q

43、uot;> <xs:element name="getCustomerInfo"> <xs:complexType> <xs:sequence> <xs:element name="lenght" type="xs:long"/> </xs:sequence> </xs:complexType> </xs:element> .</s0:definitions>这个样例说明了如何在一个WSDL文件中描述服务CustomerInfoSer

44、vice中的操作名称，这些操作分别为：getCustomerInfo、updateCustomerInfo 等。1.2.3 异常编码规范 规范概述规范化应用系统对外暴露接口的异常信息，有助于相关人员在发现异常时进行准确的问题定位和解决。 编码规范异常编码规则：<应用编码> - <9位编码>使用应用编码加9位编码的方式可以方便地理解异常编码所发生的应用以及通过编码表查看异常的原因。 规范样例样例一：异常报文<?xml version="1.0"?><soap:Envelope xmlns:so

45、ap="/2001/12/soap-envelope" soap:encodingStyle="/2001/12/soap-encoding"><soap:Header><RequestID> com.primeton.boss.billing-20110808-000000000012</RequestID></soap:Header><soap:Body><soap:fault><faultcode>

46、; com.primeton.boss.billing-000000009</faultcode><faultstring>材料信息获取</faultstring><faultactor></faultactor><detail>材料信息获取失败</detail></ soap:fault></soap:Body></soap:Envelope>1.2.4 请求编码规范 规范概述请求编码全局唯一标识了服务消费者的服务请求，该编码是服务消费者每次调用服务时在请求消

47、息的SOAP Header中设置的全局唯一的标识，供SSM等系统进行服务分析用。 编码规范请求编码规则：<应用编码> - <日期 yyyyMMdd> - <12位流水号>请求编码由三部分组成，每部分由“-”分割，应用编码是发起请求的应用系统的应用编码，关于应用编码详见“5.6 应用编码规范”章节，日期是发起请求时的日期，流水号每天24:00时重新计算。 编码样例样例一：服务请求报文<?xml version="1.0"?><soap:Envelope xmlns:soap="http

48、://2001/12/soap-envelope" soap:encodingStyle="/2001/12/soap-encoding"><soap:Header><Version>v1.0</Version>< RequestID> com.sysware.tc.mtm-20131208-000000000012</RequestID >< AppID> com.sysware.tc.mtm<AppID/></so

49、ap:Header><soap:Body>业务协议</soap:Body></soap:Envelope>这个样例说明了“TC 域中的材料”（应用编码为com.sysware.tc.mtm）第12次对外服务调用，该次服务请求的SOAP Header中RequestID值为com.sysware.tc.mtm-20131208-000000000012。1.2.5 版本编码规范 规范概述版本是服务操作的版本，是为了服务提供者标识某一操作的不同形式。版本号是在调用服务总线ESB上某一服务时由服务消费者在SOAP Header中设置的，这样有助

50、于服务提供者在得到该信息时进行版本的判断。 编码规范版本编码规则：v<大版本号>.<小版本号> 编码以“v”字母开头，随后是大小版本号，大版本号与小版本号之间用“.”分割。如何规定“大版本号”和“小版本号”由服务提供者自行确定。 编码样例样例一：服务请求报文<?xml version="1.0"?><soap:Envelope xmlns:soap="/2001/12/soap-envelope" soap:encodingStyle="htt

51、p://2001/12/soap-encoding"><soap:Header><Version>v1.0</Version><RequestID> com.sysware.tc.mtm-20131208-000000000012</RequestID ><AppID> com.sysware.tc.mtm <AppID/></soap:Header><soap:Body>业务协议</soap:Body></soap:Envelope

52、>这个样例说明了“TC域中的材料库”(应用编码为com.sysware.tc.mtm)调用某一服务的v1.0版本时SOAP Header中设置的Version值。1.2.6 应用编码规范 规范概述所有的业务支撑系统都需要进行统一的编码，该编码全局唯一并统一管理，该编码主要用于但不限于：在SAM中进行应用注册时该编码作为唯一的标识；在SAM上进行权限设置时将不同的服务或操作分配给不同的应用系统；在SSM中通过统一的应用编码可以分析不同应用系统访问服务的行为特征；该应用唯一标识在服务消费者调用服务时需在SOAP Header中设置。 编码规范应用系统编码规则：com.sysware.<系统域编码>.<系统编码> 编码用“.”隔开，其中系统域编码和系统编码参见附录。 编码样例样例一：服务请求报文<?xml version