服务总线接口规范分析解析

《服务总线接口规范分析解析》由会员分享，可在线阅读，更多相关《服务总线接口规范分析解析（24页珍藏版）》请在金锄头文库上搜索。

1、安徽电信服务总线接口规范安徽电信服务总线接口规范 安徽电信有限公司 2014 年 02 月 服务总线接口规范 安徽电信服务总线 第 1 页，共 24 页 版本记录版本记录 第第 1 章章概述概述5 1.1 概述5 1.2 目标5 1.3 规范使用对象及说明5 1.4 名词解释6 第第 2 章章服务设计原则服务设计原则6 2.1 接口协议统一原则6 2.2 数据格式统一原则7 版本号时间记录人变更原因变更描述 V0.12014-1-5李超初始 V0.22014-2-22李超修订增加接口参数描述 服务总线接口规范 安徽电信服务总线 第 2 页，共 24 页 2.3 服务定义唯一性原则7 2.4 服

2、务无状态原则7 2.5 服务部署原则8 2.6 服务组合原则8 2.7 报文内容处理的原则8 2.8 出入参设计原则9 2.9 规则校验的原则9 2.10 数据量原则9 2.11 同步调用原则10 2.12 统一入口原则10 2.13 持久化原则10 第第 3 章章服务接入规范服务接入规范10 3.1 调用方式11 3.2 参数说明12 服务总线接口规范 安徽电信服务总线 第 3 页，共 24 页 3.2.1 系统级参数.12 3.3 返回业务功能14 第第 4 章章安全控制安全控制14 4.1 访问鉴权15 4.2 传输加密16 第第 5 章章异常分类编码异常分类编码16 第第 6 章章服务

3、注册、注销、变更、调用流程服务注册、注销、变更、调用流程17 6.1 服务注册的流程17 6.2 服务注册的内容18 6.3 测试环境服务注册的流程19 第第 7 章章服务治理服务治理19 7.1 目标19 7.2 检查方法20 7.3 服务监控的指标21 服务总线接口规范 安徽电信服务总线 第 4 页，共 24 页 7.4 服务目录树22 服务总线接口规范 安徽电信服务总线 第 5 页，共 24 页 第 1 章 概述 1.1 概述 本规范明确了安徽电信服务总线接入及服务使用的标准和规 范，为服务使用方和服务提供方提供开发参考。 1.2 目标 本规范为了指导各业务系统与服务总线平台的对接，实现

4、以 下目标： 1) 当服务总线接入业务系统服务时，为该服务提供方提供开 发依据。 2) 当服务使用方调用服务总线提供的服务时，为该服务使用 方提供开发依据。 3) 为服务使用过程中安全及控制提供标准和参考。 1.3 规范使用对象及说明 本规范适用于所有新建或改造的服务接口，均需要遵守本规 范约定。 服务总线接口规范 安徽电信服务总线 第 6 页，共 24 页 1.4 名词解释 1) 服务提供方：提供原始服务，并将服务发布到服务总线的 内部业务系统、第三方企业或个人。 2) 服务使用方：使用服务总线上的服务进行应用开发的内部 应用系统、第三方企业或个人。 3) 服务商：平台为统一管理服务的提供方

5、和使用方，综合其 统称为服务商。 4) 服务：服务是执行可重复任务的可发现资源，由外部化的 服务规范进行描述。服务可分为技术服务和业务服务两种。 第 2 章 服务设计原则 由于各个系统和平台之间存在差异性，为确保安徽电信服务 总线的稳定高效，服务设计原则如下： 2.1 接口协议统一原则 服务总线接口规范 安徽电信服务总线 第 7 页，共 24 页 所有服务的接口均基于 Http 协议。服务提供方和服务使用方 必须同时使用同一种类型的技术来进行开发和调用，调用的 服务通过 HTTP URL 中特定属性进行标识，具体见接口协议。 2.2 数据格式统一原则 服务的接口数据包含业务所有的业务数据，数据

6、采用 JSON 格式表示，并且符合相应的 JSON Schema。服务提供方和服 务消费方必须同时使用同一种格式进行数据交互。 2.3 服务定义唯一性原则 一个服务应该只实现一个业务功能，业务功能的区别通过服 务编码来区分，不应通过定义不同的业务数据在同一个服务 编码下实现不同的业务功能。 2.4 服务无状态原则 服务应是无状态的，两次请求之间无须状态和会话的保 持，并可以采用轮询的方式在负载均衡器上进行注册 服务总线接口规范 安徽电信服务总线 第 8 页，共 24 页 2.5 服务部署原则 服务应是全局的，不应区分本地网、大区等，但可以部 署多份用以提供不同优先级的服务。 2.6 服务组合原

7、则 服务按照服务粒度设计成原子服务和组合服务。原子服 务为最细粒度的服务，组合服务由原子服务组合而成。为有 效提高组合服务的效率，跨系统的组合服务由服务总线调用 不同的原子服务实现组合，系统内的组合服务由服务提供方 在应用内部进行组合。 2.7 报文内容处理的原则 服务请求和返回的的报文应符合 JSON Schema 格式。服 务请求方和提供方应采用通用的 JSON 解析器来构造和解析 数据，JSON 不同含义的段落应定义明确含义的字段名称， 相同内容的数据应采用数组来进行描述，双方可根据 JSON 名称和路径进行精确定位，不应根据字段的顺序来获取字段 服务总线接口规范 安徽电信服务总线 第

8、9 页，共 24 页 值，字段值不受字段顺序调整的影响。报文统一采用 UTF-8 进行编码。 2.8 出入参设计原则 为提高查询类服务的通用性和性能，查询类服务在入参中定 义返回字段列表，服务提供方根据入参中指定的字段返回信 息。 查询内接口应在入参中定义分页参数，返回参数中应包含当 前页数、总页数或是已到最后一页等信息。 返回参数中如返回静态编码值时应同时返回此编码值对 应的名称。 2.9 规则校验的原则 服务提供方应对请求报文格式和关键信息进行合规性和业 务校验，防止非法访问和入侵。 2.10 数据量原则 服务总线接口规范 安徽电信服务总线 第 10 页，共 24 页 服务总线所传递的单条

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

10、调用的访问方式，平台采用标准的 HTTP 调用 方式。 3.1 调用方式 接口服务通过 http:/ip:port/oip/rest 访问平台服务。 IP 和 PORT 根据实际生产环境情况对外公布。其中/oip/rest 保持不变。 实例：基于 REST 的服务请求 以使用“查询 BSS 用户短信详单”服务为例，该服务的具体 信息如下： 服务名称：查询 BSS 用户短信详单； 服务编码：SelectSmsInfo； 开发技术：采用 HTTP 协议技术； 请求方式：采用 GET/POST 都可以 调用方信息不变。 根据上面这些信息，得出服务访问地址为： 服务总线接口规范 安徽电信服务总线 第

11、12 页，共 24 页 GET 方式： http:/220.102.110.34:7080/oip/rest?send=crm&servCode=1001. OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/Sel ectSmsInf/1 末位的“1”是模拟业务参数。 POST 方式： http:/220.102.110.34:7080/oip/rest?send=crm&servCode=1001.OPEN_3 RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsIn f/1 业务参数的内容放在

12、http 的请求体中传输 3.2 参数说明 3.2.1 系统级参数 以下参数是由服务总线定义的。 表格 3-1 系统级参数 参数名类型 是否必 需 描述 Sendstring是 客户端所属系统编码，填 写请参考 3.1 节（系统标 志全部采用此编码） servCodestring是客户端需要访问的服务编 服务总线接口规范 安徽电信服务总线 第 13 页，共 24 页 码，由服务总线在注册后 统一提供 msgIdstring是 由调用方系统按照 OIP 规 则生成的唯一标识一次调 用的字符串，长度小于 64 位。生成规则： 系统名_当前时间戳_流水 号 busiUrlstring是 消费方传递的

13、业务部分地 址 App_keyString否服务总线分配的应用标志 transactionIdString是 交易流水号，由调用方生 成，多次请求均会包含此 信息。格式建议为系统名_ 当前时间戳_流水号 R1String否动态路由参数 1 R2String否动态路由参数 2 R3String否动态路由参数 3 transactionId：交易流水号。服务请求需经过多个系统或多个 系统模块，为了有效标志出一次业务请求经过的所有调用， 服务调用方在请求时生成一唯一的流水号，服务总线在多次 调用过程中将会保持此交易流水号一致，服务提供方也应记 服务总线接口规范 安徽电信服务总线 第 14 页，共 2

14、4 页 录此交易流水号。所有消息日志应统一记录到统一日志平台 以供事后分析。 R1-R3：动态路由参数，为了保持路由的灵活性，调用方可 动态添加最多 3 个路由参数，如版本号，本地网等参数，服 务总线根据此参数路由到特定的服务提供方节点上，以满足 试点，灰度发布等场景。 3.3 返回业务功能 返回参数分为两部分，一部分为 HTTP 协议部分，包含了请 求的状态，异常代码和异常信息，200 表示本次请求完成， 500 表示服务总线调用服务提供方出现异常等；一部分为业 务数据，业务数据采用 JSON 格式，JSON 格式需符合 JSON Schema 的校验规则，业务异常也在此部分定义。服务总线后 台分析系统将会对请求和返回的报文进行事后分析。 第 4 章 安全控制 服务总线接口规范 安徽电信服务总线 第 15 页，共 24 页 4.1 访问鉴权 服务总线对外提供统一安全控制策略。所有访问能力开 放平台的服