服务总线接口规范

安徽电信服务总线接口规范安徽电信有限公司2014年02月服务总线接口规范安徽电信服务总线第1页，共24页版本记录第1章概述................................................................................51.1概述.......................................................................................51.2目标.......................................................................................51.3规范使用对象及说明...........................................................51.4名词解释...............................................................................6第2章服务设计原则................................................................62.1接口协议统一原则...............................................................62.2数据格式统一原则...............................................................7版本号时间记录人变更原因变更描述V0.12014-1-5李超初始V0.22014-2-22李超修订增加接口参数描述服务总线接口规范安徽电信服务总线第2页，共24页2.3服务定义唯一性原则...........................................................72.4服务无状态原则...................................................................72.5服务部署原则.......................................................................82.6服务组合原则.......................................................................82.7报文内容处理的原则...........................................................82.8出入参设计原则...................................................................92.9规则校验的原则...................................................................92.10数据量原则.........................................................................92.11同步调用原则...................................................................102.12统一入口原则...................................................................102.13持久化原则.......................................................................10第3章服务接入规范..............................................................103.1调用方式.............................................................................113.2参数说明.............................................................................12服务总线接口规范安徽电信服务总线第3页，共24页3.2.1系统级参数....................................................................123.3返回业务功能.....................................................................14第4章安全控制......................................................................144.1访问鉴权.............................................................................154.2传输加密.............................................................................16第5章异常分类编码..............................................................16第6章服务注册、注销、变更、调用流程..........................176.1服务注册的流程.................................................................176.2服务注册的内容.................................................................186.3测试环境服务注册的流程................................................19第7章服务治理......................................................................197.1目标.....................................................................................197.2检查方法.............................................................................207.3服务监控的指标.................................................................21服务总线接口规范安徽电信服务总线第4页，共24页7.4服务目录树.........................................................................22服务总线接口规范安徽电信服务总线第5页，共24页第1章概述1.1概述本规范明确了安徽电信服务总线接入及服务使用的标准和规范，为服务使用方和服务提供方提供开发参考。1.2目标本规范为了指导各业务系统与服务总线平台的对接，实现以下目标：1)当服务总线接入业务系统服务时，为该服务提供方提供开发依据。2)当服务使用方调用服务总线提供的服务时，为该服务使用方提供开发依据。3)为服务使用过程中安全及控制提供标准和参考。1.3规范使用对象及说明本规范适用于所有新建或改造的服务接口，均需要遵守本规范约定。服务总线接口规范安徽电信服务总线第6页，共24页1.4名词解释1)服务提供方：提供原始服务，并将服务发布到服务总线的内部业务系统、第三方企业或个人。2)服务使用方：使用服务总线上的服务进行应用开发的内部应用系统、第三方企业或个人。3)服务商：平台为统一管理服务的提供方和使用方，综合其统称为服务商。4)服务：服务是执行可重复任务的可发现资源，由外部化的服务规范进行描述。服务可分为技术服务和业务服务两种。第2章服务设计原则由于各个系统和平台之间存在差异性，为确保安徽电信服务总线的稳定高效，服务设计原则如下：2.1接口协议统一原则服务总线接口规范安徽电信服务总线第7页，共24页所有服务的接口均基于Http协议。服务提供方和服务使用方必须同时使用同一种类型的技术来进行开发和调用，调用的服务通过HTTPURL中特定属性进行标识，具体见接口协议。2.2数据格式统一原则服务的接口数据包含业务所有的业务数据，数据采用JSON格式表示，并且符合相应的JSONSchema。服务提供方和服务消费方必须同时使用同一种格式进行数据交互。2.3服务定义唯一性原则一个服务应该只实现一个业务功能，业务功能的区别通过服务编码来区分，不应通过定义不同的业务数据在同一个服务编码下实现不同的业务功能。2.4服务无状态原则服务应是无状态的，两次请求之间无须状态和会话的保持，并可以采用轮询的方式在负载均衡器上进行注册服务总线接口规范安徽电信服务总线第8页，共24页2.5服务部署原则服务应是全局的，不应区分本地网、大区等，但可以部署多份用以提供不同优先级的服务。2.6服务组合原则服务按照服务粒度设计成原子服务和组合服务。原子服务为最细粒度的服务，组合服务由原子服务组合而成。为有效提高组合服务的效率，跨系统的组合服务由服务总线调用不同的原子服务实现组合，系统内的组合服务由服务提供方在应用内部进行组合。2.7报文内容处理的原则服务请求和返回的的报文应符合JSONSchema格式。服务请求方和提供方应采用通用的JSON解析器来构造和解析数据，JSON不同含义的段落应定义明确含义的字段名称，相同内容的数据应采用数组来进行描述，双方可根据JSON名称和路径进行精确定位，不应根据字段的顺序来获取字段服务总线接口规范安徽电信服务总线第9页，共24页值，字段值不受字段顺序调整的影响。报文统一采用UTF-8进行编码。2.8出入参设计原则为提高查询类服务的通用性和性能，查询类服务在入参中定义返回字段列表，服务提供方根据入参中指定的字段返回信息。查询内接口应在入参中定义分页参数，返回参数中应包含当前页数、总页数或是已到最后一页等信息。返回参数中如返回静态编码值时应同时返回此编码值对应的名称。2.9规则校验的原则服务提供方应对请求报文格式和关键信息进行合规性和业务校验，防止非法访问和入侵。2.10数据量原则服务总线接口规范安徽电信服务总线第10页，共24页服务总线所传递的单条消息大小原则上不大于1M，否则应建议采用文件传输、接口表传输、直连等连接方式。2.11同步调用原则服务调用方和服务提供方采用同步调用的方式进行请求，如需要使用异步调用可采用消息队列或服务调用方定义异步通知接口来实现。2.12统一入口原则服务总线对外提供统一的调用地址。2.13持久化原则服务使用方在使用服务的过程中，由服务总线进行整个过程的日志记录，并对调用的详细信息进行持久化，便于对账和稽核。建议服务调用方和提供方对调用的关键信息（如流水号，源地址等）进行持久化。第3章服务接入规范服务总线接口规范安徽电信服务总线第11页，共24页对于服务调用的访问方式，平台采用标准的HTTP调用方式。3.1调用方式接口服务通过访问平台服务。IP和PORT根据实际生产环境情况对外公布。其中/oip/rest保持不变。实例：基于REST的服务请求以使用“查询BSS用户短信详单”服务为例，该服务