基于ESB系统的服务接口规范全解.doc

Q/TXN南车株洲电机有限公司企业标准Q/TXN *-*.*-2015基于ESB系统的服务接口规范2015 - 11 *发布2015 -11 *实施南车株洲电机有限公司发布前言本标准按照GB/T 1.1-2009给出的规则起草。目前公司内部上线应用的系统较多（例如ERP、PDM、HCM、AD域等），各系统间接口集成技术不统一，交换信息格式差异大，接口集成欠缺规范化和标准化，在业务系统接口需求不断增加的情况下，系统集成更趋复杂化，将造成大量的系统开发及维护工作，也很难确保数据的一致性。因此，无论从管理或技术角度考虑，都必须建立公司的服务接口规范，从而按照规范要求进行现有系统集成接口的改造及统一管理，严格要求新的接口必须按照规范要求进行开发及管理，从而使各业务系统接口集成趋于规范化。本标准由信息技术部提出。本标准由技术中心（研究院）技术管理部归口。本标准由信息技术部负责起草。本标准主要起草人：何小红、王浩亮、张凯。基于ESB系统的服务接口规范1 范围本规范规定了公司信息系统间数据交互的技术要求，确保信息系统间数据交互的安全与稳定。本规范适用于株洲电机及其下属业务单元信息业务系统间数据的交互、共享。2 规范性引用文件下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。3 术语及定义3.1 ESBEnterprise Service Bus 企业服务总线3.2 ESB SERVER提供多协议的支持以及为服务运行提供了高性能、高可靠的运行环境和方便的扩展机制，为Primeton ESB 融入企业IT环境提供了有效支撑及管控手段，不依赖于J2EE容器的特性大大提升了性能。3.3 ESB SAMESB软件资产管理模块，提供服务注册、服务查找、SLA管理等功能。3.4 ESB SSMESB服务监控模块，提供ESB Server运行时数据的存储、分析能力，增强客户感知度。3.5 ESB ConsoleESB控制台，对独立和集群环境中的ESB Server进行管理，同时对于服务全生命周期进行管理。3.6 WebserviceWeb service是一套标准，它定义了应用程序如何在Web上实现互操作性。可以使用任何语言，在任何平台上编写Web service。可以通过Web service标准对这些服务进行查询和访问。3.7 ESB服务提供方是指ESB服务接口的开发提供方，为调用方提供接口服务。3.8 ESB服务调用方是指ESB服务接口的调用方，调用注册在ESB平台上的服务接口。3.9 ESB服务管理方是指ESB服务接口的集中管理方，负责ESB服务的注册、发布、监控等。4 基于ESB的服务接口规范4.1 核心业务系统范围公司核心业务系统如下： ERP：企业资源计划 Enterprise Resource Planning PLM：产品生命周期管理 Product LifeCycle Management OA： 办公自动化 Office Automation HCM：人力资本管理系统 Human Capital Management ITSM：IT服务管理系统 IT Service Management TDM：试验数据管理系统 Test Data Management RTX：腾讯通（企业实时通讯平台） Real Time eXpert AD：域活动目录 Active Directory4.2 信息系统接口开发原则信息系统之间的接口开发应采用ESB总线集成方式。4.3 基于ESB的应用集成架构基于ESB的信息系统集成总体架构见下图。架构模式图 4.4 ESB总线服务接口工作原理基于ESB的信息系统服务接口工作原理见下图。统一服务工作原理图服务提供方负责处理本系统的业务逻辑，将业务处理进行封装，以webservice形式对外发布。服务管理方负责将服务接口在ESB总线服务管理平台中进行集中管理。服务调用方负责调用统一服务注册中心中的服务。“服务调用方”和“服务提供方”是一对抽象的逻辑概念。对于一个具体的应用系统来说，它既可能是服务调用方，也可能是服务提供方，或者同时具备两种角色。4.5 ESB服务规范4.5.1 服务描述规范服务描述规范主要说明接口服务的描述形式，服务使用者就可以根据服务描述了解服务的技术实现形式、功能和输入/输出等信息 。业务系统向外暴露的服务和ESB向外暴露的服务都需要通过WSDL的方式进行描述，这样使得相关人员可以根据WSDL开发服务调用客户端，WSDL需遵循如下相关标准：a 标准b 版本c WSDLd WSDL1.1e WS-If WS-I Basic Profile 1.1g 1)soap - "http:/schemas.xmlsoap.org/soap/envelope/"h 2)xsi - "http:/www.w3.org/2001/XMLSchema-instance"i 3)xsd - "http:/www.w3.org/2001/XMLSchema"j 4)soapenc - "http:/schemas.xmlsoap.org/soap/encoding/"k 5)wsdl - "http:/schemas.xmlsoap.org/wsdl/"l 6)soapbind - "http:/schemas.xmlsoap.org/wsdl/soap/"备注：对于业务系统如何规划WSDL文件不在本规范讨论范围内。4.5.2 请求报文规范4.5.2.1 相关标准：服务消费者服务客户端运行时需要使用SOAP报文与ESB上暴露的服务进行交互，需遵循如下相关标准：m 标准n 版本o SOAPp SOAP1.1q WS-Ir WS-I Basic Profile 1.1s 1)soap - "http:/schemas.xmlsoap.org/soap/envelope/"t 2)xsi - "http:/www.w3.org/2001/XMLSchema-instance"u 3)xsd - "http:/www.w3.org/2001/XMLSchema"v 4)soapenc - "http:/schemas.xmlsoap.org/soap/encoding/"w 5)wsdl - "http:/schemas.xmlsoap.org/wsdl/"x 6)soapbind - "http:/schemas.xmlsoap.org/wsdl/soap/"4.5.2.2 SOAP Header：服务消费者服务客户端调用服务的还需设置SOAP Header内容，具体如下：属性名称数据类型说明Version版本字符型1) 被调用服务操作的版本标识；2) 关于版本编码详见“5.5 版本编码规范”章节；RequestID-BIZ1)RequestID-ESB请求编码字符型2) 服务调用客户端提交的请求的唯一标识；3) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；4) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；5) 关于请求编码详见“5.4 请求编码规范”章节；AppID应用编码字符型1) 应用编码，即发起请求的应用系统的编码；2) 关于应用编码详见“5.6 应用编码规范”章节；4.5.2.3 HTTP Header：服务消费者服务客户端调用服务的还需设置HTTP Header内容，具体如下：属性名称数据类型说明Version版本字符型1) 被调用服务操作的版本标识；2) 关于版本编码详见“5.5 版本编码规范”章节；RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；AppID应用编码字符型1) 应用编码，即发起请求的应用系统的编码；2) 关于应用编码详见“5.6 应用编码规范”章节；4.5.2.4 SOAP Body：请求报文的SOAP Body内容由具体的服务描述文件WSDL来定义。4.5.3 响应报文规范4.5.3.1 相关标准：服务提供者运行时需要使用SOAP报文与ESB进行交互，并遵循如下相关标准：y 标准z 版本aa SOAPbb SOAP1.1cc WS-Idd WS-I Basic Profile 1.1ee 1)soap - "http:/schemas.xmlsoap.org/soap/envelope/"ff 2)xsi - "http:/www.w3.org/2001/XMLSchema-instance"gg 3)xsd - "http:/www.w3.org/2001/XMLSchema"hh 4)soapenc - "http:/schemas.xmlsoap.org/soap/encoding/"ii 5)wsdl - "http:/schemas.xmlsoap.org/wsdl/"jj 6)soapbind - "http:/schemas.xmlsoap.org/wsdl/soap/"4.5.3.2 SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID-BIZRequestID-ESB请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；4.5.3.3 HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4) 关于请求编码详见“5.4 请求编码规范”章节；4.5.3.4 SOAP Body：响应报文的SOAP Body内容由具体的服务描述文件WSDL来定义 。4.5.4 确认报文规范 确认报文主要使用在异步调用场景，有请求报文的接受方向报文的发送方确认已经正确收到报文 。4.5.4.1 相关标准：服务提供者运行时需要使用SOAP报文与ESB进行交互，并遵循如下相关标准：标准版本SOAPSOAP1.1WS-IWS-I Basic Profile 1.11)soap - "http:/schemas.xmlsoap.org/soap/envelope/"2)xsi - "http:/www.w3.org/2001/XMLSchema-instance"3)xsd - "http:/www.w3.org/2001/XMLSchema"4)soapenc - "http:/schemas.xmlsoap.org/soap/encoding/"5)wsdl - "http:/schemas.xmlsoap.org/wsdl/"6)soapbind - "http:/schemas.xmlsoap.org/wsdl/soap/"4.5.4.2 SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4.5.4.3 HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4.5.4.4 SOAP Body：确认报文的SOAP Body内容为“OK”。4.5.5 异常报文规范异常报文在同步、异常场景下都可以用到。在同步场景下作为异常响应报文，在同步场景下作为异常确认报文 。4.5.5.1 相关标准：服务提供者运行时需要使用SOAP报文与ESB进行交互，并遵循如下相关标准：标准版本SOAPSOAP1.1WS-IWS-I Basic Profile 1.11)soap - "http:/schemas.xmlsoap.org/soap/envelope/"2)xsi - "http:/www.w3.org/2001/XMLSchema-instance"3)xsd - "http:/www.w3.org/2001/XMLSchema"4)soapenc - "http:/schemas.xmlsoap.org/soap/encoding/"5)wsdl - "http:/schemas.xmlsoap.org/wsdl/"6)soapbind - "http:/schemas.xmlsoap.org/wsdl/soap/"4.5.5.2 SOAP Header：服务提供者返回结果时还需设置SOAP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现SOAP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4.5.5.3 HTTP Header：服务提供者返回结果时还需设置HTTP Header内容，具体如下：属性名称数据类型说明RequestID请求编码字符型1) 服务调用客户端提交的请求的唯一标识；2) 应用系统和服务总线任何一方发现HTTP Header中没有RequestID或RequestID为空，都要生成有效的RequestID；3) RequestID作为端到端全路径跟踪的基础，所以需要在其产生之后，端到端服务调用结束之前在相关的应用系统之间传递；4.5.5.4 SOAP Body：可选的 SOAP Fault元素用于指示错误消息。如果已提供了Fault元素，则它必须是 Body 元素的子元素。在一条 SOAP 消息中，Fault 元素只能出现一次。SOAP 的 Fault 元素拥有下列子元素：属性说明<faultcode>供识别故障的代码<faultstring>可供人阅读的有关故障的说明；<faultactor>有关是谁引发故障的信息；<detail>存留涉及 Body 元素的应用程序专用错误信息；4.5.6 报文大小规范4.5.6.1 规范目标限制单次服务调用所携带的数据量大小有助于降低服务总线的负载，提高服务总线的性能。4.5.6.2 规范概述 单笔服务携带的数据量上限为200K ；4.6 ESB服务提拱规范服务提供者按ESB服务接入规范要求提供服务，满足本规范“4.4.1”、“4.4.2”、“4.4.3”、“4.4.4”、“4.4.6”、“5.1”、“5.2”的要求，确保服务能够正确地在ESB总线上进行注册与发布。4.7 ESB服务发布规范ESB服务管理者按ESB服务发布的规范进行服务的发布，包括ESB服务开发、服务命名、服务注册，满足本规范“5.1”、“5.2”、“5.5”、“5.6”的要求。4.8 ESB服务调用规范服务提供者按ESB服务的规范要求进行服务调用，满足本规范中“4.4.1”、“4.4.2”、“4.4.6”、“5.3”、“5.4”、 “5.6”，确保能够正确调用服务。5 编码规范5.1 服务编码规范5.1.1 规范概述服务是若干操作的集合体，业务相关的若干操作可以组合成一个业务目标明确的服务，通过服务名称的规范化有助于开发人员理解服务的业务意义。服务编码规范主要应用于服务定义文件WSDL和ESB部署过程中 。5.1.2 编码规范操作编码规则如下：<应用编码>.<服务名称>其中应用编码详见“5.6 应用编码规范”章节 。5.1.3 规范样例<?xml version='1.0' encoding='UTF-8'?><s0:definitions name="CustomerInfoServiceDefinitions" targetNamespace="http:/com/alsb/hello" xmlns="" xmlns:s0="http:/schemas.xmlsoap.org/wsdl/" xmlns:s1="http:/com/alsb/hello" xmlns:s2="http:/schemas.xmlsoap.org/wsdl/soap/"> <s0:service name="CustomerInfoService"> <s0:port binding="s1:CustomerInfoServiceSoapBinding" name="CustomerInfoPort"> <s2:address location="http:/localhost:7001/ com.csr.motor.server.erp.CustomerInfoService"/> </s0:port> </s0:service></s0:definitions>这个样例说明了应用编码为“com.csr.motor.server.erp”的系统对外暴露的com.csr.motor.server.erp.CustomerInfoService服务 。5.2 操作编码规范5.2.1 规范概述操作编码规范主要体现在服务定义的wsdl文件中对操作编码的定义，“操作”是实际承载业务逻辑的实体，业务关联较强的若干“操作”组成一个“服务”。对“操作”名称的规范有助于相关人员更直观地理解某操作的业务功能 。5.2.2 编码规范操作编码规则如下：使用动宾短语表示某一操作的业务功能，该短语不宜过长。5.2.3 规范样例样例：WSDL接口描述文件<?xml version='1.0' encoding='UTF-8'?><s0:definitions name="CustomerInfoServiceDefinitions" targetNamespace="http:/com/alsb/hello" xmlns="" xmlns:s0="http:/schemas.xmlsoap.org/wsdl/" xmlns:s1="http:/com/alsb/hello" xmlns:s2="http:/schemas.xmlsoap.org/wsdl/soap/"> <s0:types> <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http:/com/alsb/hello" xmlns:xs="http:/www.w3.org/2001/XMLSchema"> <xs:element name="getCustomerInfo"> <xs:complexType> <xs:sequence> <xs:element name="lenght" type="xs:long"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="getCustomerInfoResponse"> <xs:complexType> <xs:sequence> <xs:element name="CustomerInfo" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="updateCustomerInfo"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="updateCustomerInfoResponse"> <xs:complexType> <xs:sequence> <xs:element name="CustomerInfo" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> </s0:types> <s0:message name="getCustomerInfo"> <s0:part element="s1:getCustomerInfo" name="parameters"/> </s0:message> <s0:message name="getCustomerInfoResponse"> <s0:part element="s1:getCustomerInfoResponse" name="parameters"/> </s0:message> <s0:message name="updateCustomerInfo"> <s0:part element="s1:updateCustomerInfo" name="parameters"/> </s0:message> <s0:message name="updateCustomerInfoResponse"> <s0:part element="s1:updateCustomerInfoResponse" name="parameters"/> </s0:message> <s0:portType name="CustomerInfo"> <s0:operation name="getCustomerInfo" parameterOrder="parameters"> <s0:input message="s1:getCustomerInfo"/> <s0:output message="s1:getCustomerInfoResponse"/> </s0:operation> <s0:operation name="updateCustomerInfo" parameterOrder="parameters"> <s0:input message="s1:updateCustomerInfo"/> <s0:output message="s1:updateCustomerInfoResponse"/> </s0:operation> </s0:portType> <s0:binding name="CustomerInfoServiceSoapBinding" type="s1:CustomerInfo"> <s2:binding style="document" transport="http:/schemas.xmlsoap.org/soap/http"/> <s0:operation name="getCustomerInfo"> <s2:operation style="document"/> <s0:input> <s2:body parts="parameters" use="literal"/> </s0:input> <s0:output> <s2:body parts="parameters" use="literal"/> </s0:output> </s0:operation> <s0:operation name="updateCustomerInfo"> <s2:operation style="document"/> <s0:input> <s2:body parts="parameters" use="literal"/> </s0:input> <s0:output> <s2:body parts="parameters" use="literal"/> </s0:output> </s0:operation> </s0:binding> <s0:service name="CustomerInfoService"> <s0:port binding="s1:CustomerInfoServiceSoapBinding" name="CustomerInfoSoapPort"> <s2:address location="http:/localhost:7001/com.cmcc.sh.boss.billing.CustomerInfoService"/> </s0:port> </s0:service></s0:definitions>这个样例说明了如何在一个WSDL文件中描述服务CustomerInfoService中的操作名称，这些操作分别为：getCustomerInfo、updateCustomerInfo 等。5.3 异常编码规范5.3.1 规范概述规范应用系统对外暴露接口的异常信息，有助于相关人员在发现异常时进行准确的问题定位和解决 。5.3.2 编码规范异常编码规则如下：<应用编码> - <9位编码>使用应用编码加9位编码的方式可以方便地理解异常编码所发生的应用以及通过编码表查看异常的原因 。5.3.3 规范样例样例一：异常报文<?xml version="1.0"?><soap:Envelope xmlns:soap="http:/www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http:/www.w3.org/2001/12/soap-encoding"><soap:Header><RequestID> com.csr.motor.server.erp -20110808-000000000012</RequestID></soap:Header><soap:Body><soap:fault><faultcode> com.csr.motor.server.erp -000000009</faultcode><faultstring>物料不存在</faultstring><faultactor></faultactor><detail>ERP中此物料不存在</detail></ soap:fault></soap:Body></soap:Envelope>5.4 请求编码规范5.4.1 规范概述请求编码全局唯一标识了服务消费者的服务请求，该编码是服务消费者每次调用服务时在请求消息的SOAP Header中设置的全局唯一的标识，供SSM等系统进行服务分析用 。5.4.2 编码规范请求编码规则如下：<应用编码> - <日期 yyyyMMdd> - <12位流水号>请求编码由三部分组成，每部分由“-”分割，应用编码是发起请求的应用系统的应用编码，关于应用编码详见“5.6 应用编码规范”章节，日期是发起请求时的日期，流水号每天24:00时重新计算 。5.4.3 编码样例样例：服务请求报文<?xml version="1.0"?><soap:Envelope xmlns:soap="http:/www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http:/www.w3.org/2001/12/soap-encoding"><soap:Header><Version>v1.0</Version>< RequestID> com.csr.motor.server.erp -20110808-000000000012</RequestID >< AppID> com.csr.motor.server.erp <AppID/></soap:Header><soap:Body>业务协议</soap:Body></soap:Envelope>这个样例说明了“株洲电机ERP系统”（应用编码为com.csr.motor.server.erp）在2011年8月8日的第12次对外服务调用，该次服务请求的SOAP Header中RequestID值为com.csr.motor.server.erp -20110808-000000000012 。5.5 版本编码规范5.5.1 规范概述版本是服务操作的版本，是为了服务提供者标识某一操作的不同形式。版本号是在调用服务总线ESB上某一服务时由服务消费者在SOAP Header中设置的，这样有助于服务提供者在得到该信息时进行版本的判断 。5.5.2 编码规范版本编码规则如下：v<大版本号>.<小版本号>编码以“v”字母开头，随后是大小版本号，大版本号与小版本号之间用“.”分割。如何规定“大版本号”和“小版本号”由服务提供者自行确定 。5.5.3 编码样例样例：服务请求报文<?xml version="1.0"?><soap:Envelope xmlns:soap="http:/www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http:/www.w3.org/2001/12/soap-encoding"><soap:Header><Version>v1.0</Version><RequestID> com.csr.motor.server.erp -20110808-000000000012</RequestID ><AppID> com.csr.motor.server.erp <AppID/></soap:Header><soap:Body>业务协议</soap:Body></soap:Envelope>这个样例说明了“株洲电机ERP系统”(应用编码为com.csr.motor.server.erp)调用某一服务的v1.0版本时SOAP Header中设置的Version值 。5.6 应用编码规范5.6.1 规范概述所有的业务支撑系统都需要进行统一的编码，该编码全局唯一并统一管理，该编码主要用于但不