服务总线接口规范标准

1、!-安徽电信服务总线接口规范安 徽 电 信 有 限 公 司2014年02月!-版本记录版本号时间记录人变更原因变更描述V0.12014-1-5李超初始V0.22014-2-22李超修订增加接口参数描述第1章概述1.1概述1.2目标1.3规范使用对象及说明1.4名词解释2.3服务定义唯一性原则6第2章服务设计原则2.1接口协议统一原则2.2数据格式统一原则2.4服务无状态原则!-4.1访问鉴权122.5服务部署原则2.6服务组合原则2.7报文内容处理的原则2.8出入参设计原则2.9规则校验的原则2.10数据量原则2.11冋步调用原则2.12统一入口原则2.13持久化原则第3章服务接入规范3.1调

2、用方式3.2参数说明103.2.1系统级参数103.3返回业务功能12第4章安全控制12!-134.2传输加密13第5章异常分类编码第6章 服务注册、注销、变更、调用流程156.1服务注册的流程156.2服务注册的内容156.3测试环境服务注册的流程16第7章服务治理167.1目标167.2检查方法177.3服务监控的指标187.4服务目录树19!-第1章概述1.4名词解释1.1概述本规范明确了安徽电信服务总线接入及服务使用的标准和规 范，为服务使用方和服务提供方提供开发参考。1.2目标本规范为了指导各业务系统与服务总线平台的对接，实现以1)2)当服务总线接入业务系统服务时，为该服务提供方提供

3、开 发依据。当服务使用方调用服务总线提供的服务时，为该服务使用方提供开发依据。3)为服务使用过程中安全及控制提供标准和参考。1.3规范使用对象及说明本规范适用于所有新建或改造的服务接口，均需要遵守本规 范约定。!-1)服务提供方：提供原始服务，并将服务发布到服务总线的内部业务系统、第三方企业或个人。2)服务使用方：使用服务总线上的服务进行应用开发的内部应用系统、第三方企业或个人。3)服务商：平台为统一管理服务的提供方和使用方，综合其统称为服务商。4)服务：服务是执行可重复任务的可发现资源，由外部化的服务规范进行描述。服务可分为技术服务和业务服务两种。第2章服务设计原则由于各个系统和平台之间存在

4、差异性，为确保安徽电信服务总线的稳定高效，服务设计原则如下:2.1接口协议统一原则所有服务的接口均基于 Http协议。服务提供方和服务使用方必须同时使用同一种类型的技术来进行开发和调用，调用的服务通过HTTP URL中特定属性进行标识，具体见接口协议。2.2数据格式统一原则服务的接口数据包含业务所有的业务数据，数据采用JSON格式表示，并且符合相应的 JSON Schema。服务提供方和服务消费方必须同时使用同一种格式进行数据交互。2.3服务定义唯一性原则个服务应该只实现一个业务功能，业务功能的区别通过服 务编码来区分，不应通过定义不同的业务数据在同一个服务 编码下实现不同的业务功能。2.4服

5、务无状态原则服务应是无状态的，两次请求之间无须状态和会话的保持，并可以采用轮询的方式在负载均衡器上进行注册2.5服务部署原则服务应是全局的，不应区分本地网、大区等，但可以部署多份用以提供不同优先级的服务。2.6服务组合原则服务按照服务粒度设计成原子服务和组合服务。原子服务为最细粒度的服务，组合服务由原子服务组合而成。为有效提高组合服务的效率，跨系统的组合服务由服务总线调用 不同的原子服务实现组合，系统内的组合服务由服务提供方 在应用内部进行组合。2.7报文内容处理的原则服务请求和返回的的报文应符合JSON Schema格式。服务请求方和提供方应采用通用的 JSON解析器来构造和解析数据，JSO

6、N不同含义的段落应定义明确含义的字段名称，相同内容的数据应采用数组来进行描述，双方可根据JSON名称和路径进行精确定位，不应根据字段的顺序来获取字段值，字段值不受字段顺序调整的影响。报文统一采用UTF-8进行编码。2.8出入参设计原则为提高查询类服务的通用性和性能，查询类服务在入参中定 义返回字段列表，服务提供方根据入参中指定的字段返回信 息。查询内接口应在入参中定义分页参数，返回参数中应包含当 前页数、总页数或是已到最后一页等信息。返回参数中如返回静态编码值时应同时返回此编码值对应的名称。2.9规则校验的原则服务提供方应对请求报文格式和关键信息进行合规性和业 务校验，防止非法访问和入侵。2.

7、10数据量原则服务总线所传递的单条消息大小原则上不大于1M，否则应建议采用文件传输、接口表传输、直连等连接方式。2.11同步调用原则服务调用方和服务提供方采用同步调用的方式进行请求，如需要使用异步调用可采用消息队列或服务调用方定义 异步通知接口来实现。2.12统一入口原则服务总线对外提供统一的调用地址。2.13持久化原则服务使用方在使用服务的过程中，由服务总线进行整个过程的日志记录，并对调用的详细信息进行持久化，便于对账和稽核。建议服务调用方和提供方对调用的关键信息（如 流水号，源地址等）进行持久化。第3章服务接入规范对于服务调用的访问方式，平台采用标准的HTTP调用方式。3.1调用方式接口服

8、务通过 http:/ip:port/oip/rest访问平台服务。IP和PORT根据实际生产环境情况对外公布。其中/oi p/rest保持不变。实例：基于REST的服务请求以使用“查询BSS用户短信详单”服务为例，该服务的具体信息如下:服务名称:查询 BSS用户短信详单;服务编码:SelectSmsInfo ；开发技术:采用 HTTP协议技术;请求方式:采用 GET/POST都可以调用方信息不变。根据上面这些信息，得出服务访问地址为:GET方式: htt P： /4:7080/oi p/rest?send=crm&servCode=1001.OP EN_3RD

9、.Sync&msgld=crm_20130718_10001 &busiURI=/Sel ectSmslnf/1末位的“ 1是模拟业务参数。POST方式:http：/4：7080/oip/res?send=crm&servCode=1001. OP EN_3RD.Sync&msgld=crm_20130718_10001 &busiURI=/SelectSmsln f/1业务参数的内容放在httP的请求体中传输3.2参数说明321系统级参数以下参数是由服务总线定义的。表格3-1系统级参数参数名类型是否必需描述Sendstring

10、是客户端所属系统编码，填 与请参考3.1节（系统标 志全部采用此编码）servCodestring是客户端需要访问的服务编 码，由服务总线在注册后 统一提供msgIdstring是由调用方系统按照 OIP规 则生成的唯标识次调 用的字符串，长度小于 64 位。生成规则： 系统名_当前时间戳_流水口号busiUrlstring是消费方传递的业务部分地 址App keyString否服务总线分配的应用标志transactionldString是交易流水号，由调用方生 成，多次请求均会包含此 信息。格式建议为系统名 _ 当前时间戳 流水号R1String否动态路由参数1R2String否动态路由参数

11、2R3String否动态路由参数3transactionld :交易流水号。服务请求需经过多个系统或多个 系统模块，为了有效标志出一次业务请求经过的所有调用，号,服务调用方在请求时生成一唯一的流水号，服务总线在多次口 号。调用过程中将会保持此交易流水号一致，服务提供方也应记 录此交易流水号。所有消息日志应统一记录到统一日志平台 以供事后分析。R1-R3 :动态路由参数，为了保持路由的灵活性，调用方可 动态添加最多3个路由参数，如版本号，本地网等参数，服务总线根据此参数路由到特定的服务提供方节点上，以满足 试点，灰度发布等场景。3.3返回业务功能返回参数分为两部分，一部分为HTTP协议部分，包含

12、了请求的状态，异常代码和异常信息，200表示本次请求完成， 500表示服务总线调用服务提供方出现异常等；一部分为业务数据，业务数据采用 JSON格式，JSON格式需符合JSONSchema的校验规则，业务异常也在此部分定义。服务总线后台分析系统将会对请求和返回的报文进行事后分析。第4章安全控制4.1访问鉴权服务总线对外提供统一安全控制策略。所有访问能力开放平台的服务时，都必须经过平台的鉴权，鉴权通过后方允 许访问，否则将给与拦截。能力开放的访问鉴权提供如下几种策略:服务商鉴权：凡是使用能力开放平台的服务使用方必须是已 注册的服务商下的一个客户端。该部分由使用方进行申请， 平台完成注册，同时为服

13、务使用方分配可使用服务的权限。IP地址鉴权：应用集成平台支持服务使用方的IP地址身份认证模式。对于不在服务使用方申请的IP地址范围内产生的服口警。务调用，平台给予拦截和告警。对于通过多重路由或映射导 致不能获得实际IP地址时，将采用鉴权码方式替代。摘要式认证：采用标准的HTTP摘要认证方式进行访问认 证，具体介绍见参考文档OAuth2.0:对于严格权限限制的场景，通过OAuth2.0协议进行认证和授权，授权由应用系统统一提供。4.2传输加密对于安全非常高的场合，建议全流程采用HTTPS协议进行加密传输，如缴费等场景。第5章异常分类编码在使用平台服务的过程中，平台对不同的异常进行分类，供开发者和

14、使用方在调测及使用过程中参考。种类编码描述正常0成功接口请求方 异常2消息格式异常，例如必填参数未填、消 息编码异常等3无效的路由属性10接口请求超过指定流量9接口请求包大小超过限制6权限异常（例如无权访问此服务）101重复请求102无效的业务域或业务大类、小类199接口请求方其他异常接口响应方 异常8接口响应方超时201接口响应超过指疋流量202接口响应包大小超过限制298接口响应方内部异常299接口响应方其他异常平台异常4调用的服务未发布5调用的服务已注销7调用的服务已关闭11调用的服务不存在1服务调用失败398平台内部异常399平台其他异常其他异常999其他异常测试异常601测试接口未实

15、现业务定义异 常>1000如果遇到上述类似异常代码或信息，可以和平台维护人员联 系帮助解决。第6章 服务注册、注销、变更、调用流程6.1服务注册的流程服务注册和变更：由服务提供方在ITSM发起申请，经服务评审后，由ITSM调用服务总线提供的能力进行注册和变 更。服务注销：由服务提供方或服务总线管理方根据实际需求和服务的调用次数等评估后发起，经服务提供方、服务总线管理部门和服务调用方会审后在ITSM中发起下线流程。服务调用：由服务调用方发起，经服务提供方确认和服务评审后在服务总线上进行注册。服务评审由服务总线管理部门牵头组织。6.2服务注册的内容名称说明接口名称接口编码接口间要描述请求报文

16、样例返回扌艮文样例请求扌艮文格式定义返回扌艮文格式定义接口业务异常列表 和描述版本号对应的服务节点注册服务地址探测扌艮文（可选）是否进行探测（时 间，频度）备用服务地址（在 连续失败或拨测失 败等情况下自动或 手工切换服务地 址）6.3测试环境服务注册的流程测试环境服务注册由ITSM发起，在完成表单填写后自动在 服务总线上进行处理。第7章服务治理7.1目标1、所有域的服务按照协议规范全部接入服务总线，避免出现服务未在服务总线直接使用。2、注册在服务总线上的服务必须符合服务总线的规范，包括接口协议，数据格式，不得私自更改协议或超过注册的 内容升级接口内容7.2检查方法1、按照所有服务全部由服务总

17、线调用或者由F5负载均衡器调用的基本原则，服务管理团队会定期对主机和F5上服务的调用方IP进行审核，如果出现服务端口出现非服务 总线或非F5主机的调用，或者 F5主机上服务端口非服务总线的调用，则认为出现了异常的服务调用，由服务提供方提供服务调用日志或版本变化情况进行详细的解释。2、服务接口参数应符合接口规范，服务总线将定期对服务调用异常、失败、异常代码等进行统计，给出服务接口的符合度。3、 服务返回的业务数据应符合注册时提供的JSONSchema,不符合的则认为是注册信息不全或异常升级。服务总线将定期从服务调用报文中进行格式校验，对不符合格式的消息请求反馈服务提供方并要求进行说明。7.3服务监控的指标指标类型运行类调用次数平均调用时长1秒以内调用 次数1-5秒以内调 用次数5秒以上调用 次数调用成功次数调用失败次数调用超时次数非法调用个数常规类服务注册个数服务变更个数服务注销个数规范类异常服务接口 个数接口请求不合 规个数报文格式不合 规个数!-7.4服务目录树服务总线上注