服务总线接口规范.doc

精品文档 1欢迎下载 安徽电信服务总线接口规范安徽电信服务总线接口规范 精品文档 2欢迎下载 安徽电信有限公司 2014 年 02 月 精品文档 1欢迎下载 版本记录版本记录 第第 1 1 章章概述概述 5 5 1 1 概述 5 1 2 目标 5 1 3 规范使用对象及说明 5 1 4 名词解释 6 第第 2 2 章章服务设计原则服务设计原则 6 6 2 1 接口协议统一原则 6 2 2 数据格式统一原则 7 2 3 服务定义唯一性原则 7 版本号时间记录人变更原因变更描述 V0 12014 1 5 李超初始 V0 22014 2 22 李超修订增加接口参数描述 精品文档 2欢迎下载 2 4 服务无状态原则 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 3 章章服务接入规范服务接入规范 1010 3 1 调用方式 11 3 2 参数说明 12 3 2 1 系统级参数 12 3 3 返回业务功能 14 第第 4 4 章章安全控制安全控制 1414 精品文档 3欢迎下载 4 1 访问鉴权 15 4 2 传输加密 16 第第 5 5 章章异常分类编码异常分类编码 1616 第第 6 6 章章服务注册 注销 变更 调用流程服务注册 注销 变更 调用流程 1717 6 1 服务注册的流程 17 6 2 服务注册的内容 18 6 3 测试环境服务注册的流程 19 第第 7 7 章章服务治理服务治理 1919 7 1 目标 19 7 2 检查方法 20 7 3 服务监控的指标 21 7 4 服务目录树 22 精品文档 4欢迎下载 第 1 章 概述 1 1 概述 本规范明确了安徽电信服务总线接入及服务使用的标准和规 范 为服务使用方和服务提供方提供开发参考 1 2 目标 本规范为了指导各业务系统与服务总线平台的对接 实现以 下目标 1 当服务总线接入业务系统服务时 为该服务提供方提供开 发依据 2 当服务使用方调用服务总线提供的服务时 为该服务使用 方提供开发依据 3 为服务使用过程中安全及控制提供标准和参考 1 3 规范使用对象及说明 本规范适用于所有新建或改造的服务接口 均需要遵守本规 范约定 1 4 名词解释 精品文档 5欢迎下载 1 服务提供方 提供原始服务 并将服务发布到服务总线的 内部业务系统 第三方企业或个人 2 服务使用方 使用服务总线上的服务进行应用开发的内部 应用系统 第三方企业或个人 3 服务商 平台为统一管理服务的提供方和使用方 综合其 统称为服务商 4 服务 服务是执行可重复任务的可发现资源 由外部化的 服务规范进行描述 服务可分为技术服务和业务服务两种 第 2 章 服务设计原则 由于各个系统和平台之间存在差异性 为确保安徽电信服务 总线的稳定高效 服务设计原则如下 2 1 接口协议统一原则 所有服务的接口均基于 Http 协议 服务提供方和服务使用方 必须同时使用同一种类型的技术来进行开发和调用 调用的 服务通过 HTTP URL 中特定属性进行标识 具体见接口协议 2 2 数据格式统一原则 精品文档 6欢迎下载 服务的接口数据包含业务所有的业务数据 数据采用 JSON 格 式表示 并且符合相应的 JSON Schema 服务提供方和服务 消费方必须同时使用同一种格式进行数据交互 2 3 服务定义唯一性原则 一个服务应该只实现一个业务功能 业务功能的区别通过服 务编码来区分 不应通过定义不同的业务数据在同一个服务 编码下实现不同的业务功能 2 4 服务无状态原则 服务应是无状态的 两次请求之间无须状态和会话的保 持 并可以采用轮询的方式在负载均衡器上进行注册 2 5 服务部署原则 服务应是全局的 不应区分本地网 大区等 但可以部 署多份用以提供不同优先级的服务 2 6 服务组合原则 服务按照服务粒度设计成原子服务和组合服务 原子服 务为最细粒度的服务 组合服务由原子服务组合而成 为有 效提高组合服务的效率 跨系统的组合服务由服务总线调用 精品文档 7欢迎下载 不同的原子服务实现组合 系统内的组合服务由服务提供方 在应用内部进行组合 2 7 报文内容处理的原则 服务请求和返回的的报文应符合 JSON Schema 格式 服 务请求方和提供方应采用通用的 JSON 解析器来构造和解析数 据 JSON 不同含义的段落应定义明确含义的字段名称 相同 内容的数据应采用数组来进行描述 双方可根据 JSON 名称和 路径进行精确定位 不应根据字段的顺序来获取字段值 字 段值不受字段顺序调整的影响 报文统一采用 UTF 8 进行编 码 2 8 出入参设计原则 为提高查询类服务的通用性和性能 查询类服务在入参中定 义返回字段列表 服务提供方根据入参中指定的字段返回信 息 查询内接口应在入参中定义分页参数 返回参数中应包含当 前页数 总页数或是已到最后一页等信息 精品文档 8欢迎下载 返回参数中如返回静态编码值时应同时返回此编码值对 应的名称 2 9 规则校验的原则 服务提供方应对请求报文格式和关键信息进行合规性和 业务校验 防止非法访问和入侵 2 10 数据量原则 服务总线所传递的单条消息大小原则上不大于 1M 否则应建 议采用文件传输 接口表传输 直连等连接方式 2 11 同步调用原则 服务调用方和服务提供方采用同步调用的方式进行请求 如需要使用异步调用可采用消息队列或服务调用方定义异步 通知接口来实现 2 12 统一入口原则 服务总线对外提供统一的调用地址 2 13 持久化原则 服务使用方在使用服务的过程中 由服务总线进行整个 过程的日志记录 并对调用的详细信息进行持久化 便于对 精品文档 9欢迎下载 账和稽核 建议服务调用方和提供方对调用的关键信息 如 流水号 源地址等 进行持久化 第 3 章 服务接入规范 对于服务调用的访问方式 平台采用标准的 HTTP 调用 方式 3 1 调用方式 接口服务通过 http ip port oip rest 访问平台服 务 IP 和 PORT 根据实际生产环境情况对外公布 其中 oip rest 保持不变 实例 基于 REST 的服务请求 以使用 查询 BSS 用户短信详单 服务为例 该服务的具体 信息如下 服务名称 查询 BSS 用户短信详单 服务编码 SelectSmsInfo 开发技术 采用 HTTP 协议技术 请求方式 采用 GET POST 都可以 精品文档 10欢迎下载 调用方信息不变 根据上面这些信息 得出服务访问地址为 GET 方式 http 220 102 110 34 7080 oip rest send crm servCode 1001 OPEN 3RD Sync msgId crm 20130718 10001 busiURl SelectSmsInf 1 末位的 1 是模拟业务参数 POST 方式 http 220 102 110 34 7080 oip rest send crm servCode 1001 OP EN 3RD Sync msgId crm 20130718 10001 busiURl SelectS msInf 1 业务参数的内容放在 http 的请求体中传输 3 2 参数说明 3 2 1 系统级参数 以下参数是由服务总线定义的 表格 3 1 系统级参数 精品文档 11欢迎下载 参数名类型 是否必 需 描述 Send strin g 是 客户端所属系统编码 填 写请参考 3 1 节 系统标 志全部采用此编码 servCode strin g 是 客户端需要访问的服务编 码 由服务总线在注册后 统一提供 msgId strin g 是 由调用方系统按照 OIP 规 则生成的唯一标识一次调 用的字符串 长度小于 64 位 生成规则 系统名 当前时间戳 流水 号 busiUrl strin g 是 消费方传递的业务部分地 址 App key Strin g 否服务总线分配的应用标志 transactionI d Strin g 是 交易流水号 由调用方生 成 多次请求均会包含此 信息 格式建议为系统名 当前时间戳 流水号 R1 Strin g 否动态路由参数 1 R2 Strin g 否动态路由参数 2 R3 Strin g 否动态路由参数 3 精品文档 12欢迎下载 transactionId 交易流水号 服务请求需经过多个系统或多 个系统模块 为了有效标志出一次业务请求经过的所有调用 服务调用方在请求时生成一唯一的流水号 服务总线在多次 调用过程中将会保持此交易流水号一致 服务提供方也应记 录此交易流水号 所有消息日志应统一记录到统一日志平台 以供事后分析 R1 R3 动态路由参数 为了保持路由的灵活性 调用方可动 态添加最多 3 个路由参数 如版本号 本地网等参数 服务 总线根据此参数路由到特定的服务提供方节点上 以满足试 点 灰度发布等场景 3 3 返回业务功能 返回参数分为两部分 一部分为 HTTP 协议部分 包含了请求 的状态 异常代码和异常信息 200 表示本次请求完成 500 表示服务总线调用服务提供方出现异常等 一部分为业务数 据 业务数据采用 JSON 格式 JSON 格式需符合 JSON Schema 的校验规则 业务异常也在此部分定义 服务总线后台分析 系统将会对请求和返回的报文进行事后分析 精品文档 13欢迎下载 第 4 章 安全控制 4 1 访问鉴权 服务总线对外提供统一安全控制策略 所有访问能力开 放平台的服务时 都必须经过平台的鉴权 鉴权通过后方允 许访问 否则将给与拦截 能力开放的访问鉴权提供如下几种策略 服务商鉴权服务商鉴权 凡是使用能力开放平台的服务使用方必须是已 注册的服务商下的一个客户端 该部分由使用方进行申请 平台完成注册 同时为服务使用方分配可使用服务的权限 IPIP 地址鉴权地址鉴权 应用集成平台支持服务使用方的 IP 地址身份 认证模式 对于不在服务使用方申请的 IP 地址范围内产生的 服务调用 平台给予拦截和告警 对于通过多重路由或映射 导致不能获得实际 IP 地址时 将采用鉴权码方式替代 摘要式认证 摘要式认证 采用标准的 HTTP 摘要认证方式进行访问认证 具体介绍见参考文档 精品文档 14欢迎下载 OAuth2 0 对于严格权限限制的场景 通过 OAuth2 0 协议 进行认证和授权 授权由应用系统统一提供 4 2 传输加密 对于安全非常高的场合 建议全流程采用 HTTPS 协议进行加 密传输 如缴费等场景 第 5 章 异常分类编码 在使用平台服务的过程中 平台对不同的异常进行分类 供 开发者和使用方在调测及使用过程中参考 种类编码描述 正常 0 成功 2 消息格式异常 例如必填参数未填 消 息编码异常等 3 无效的路由属性 10 接口请求超过指定流量 9 接口请求包大小超过限制 6 权限异常 例如无权访问此服务 101 重复请求 102 无效的业务域或业务大类 小类 接口请求方 异常 199 接口请求方其他异常 8 接口响应方超时接口响应方 异常 201 接口响应超过指定流量 精品文档 15欢迎下载 202 接口响应包大小超过限制 298 接口响应方内部异常 299 接口响应方其他异常 4 调用的服务未发布 5 调用的服务已注销 7 调用的服务已关闭 11 调用的服务不存在 1 服务调用失败 398 平台内部异常 平台异常 399 平台其他异常 其他异常 999 其他异常 测试异常 601 测试接口未实现 业务定义异 常 1000 如果遇到上述类似异常代码或信息 可以和平台维护人员联 系帮助解决 第 6 章 服务注册 注销 变更 调用流程 6 1 服务注册的流程 服务注册和变更 由服务提供方在 ITSM 发起申请 经服务评 审后 由 ITSM 调用服务总线提供的能力进行注册和变更 服务注销 由服务提供方或服务总线管理方根据实际需求和 服务的调用次数等评估后发起 经服务提供方 服务总线管 理部门和服务调用方会审后在 ITSM 中发起下线流程 精品文档 16欢迎下载 服务调用 由服务调用方发起 经服务提供方确认和服务评 审后在服务总线上进行注册 服务评审由服务总线管理部门牵头组织 6 2 服务注册的内容 名称说明 接口名称 接口编码 接口简要描述 请求报文样例 返回报文样例 请求报文格式定义 返回报文格式定义 接口业务异常列表 和描述 版本号 对应的服务节点 注册服务地址 探测报文 可选 是否进行探测 时 间 频度 备用服务地址 在 连续失败或拨测失 败等情况下自动或 手工切换服务地址 精品文档 17欢迎下载 6 3 测试环境服务注册的流程 测试环境服务注册由 ITSM 发起 在完成表单填写后自动在服 务总线上进行处理 第 7 章 服务治理 7 1 目标 1 所有域的服务按照协议规范全部接入服务总线 避免出 现服务未在服务总线直接使用 2 注册在服务总线上的服务必须符合服务总线的规范 包 括接口协议 数据格式 不得私自更改协议或超过注册的 内容升级接口内容 7 2 检查方法 1 按照所有服务全部由服务总线调用或者由 F5 负载均衡 器调用的基本原则 服务管理团队会定期对主机和 F5 上 精品文档 18欢迎下载 服务的调用方 IP 进行审核 如果出现服务端口出现非服 务总线或非 F5 主机的调用 或者 F5 主机上服务端口非服 务总线的调用 则认为出现了异常的服务调用 由服务提 供方提供服务调用日志或版本变化情况进行详细的解释 2 服务接口参数应符合接口规范 服务总线将定期对服务 调用异常 失败 异常代码等进行统计 给出服务接口的 符合度 3 服务返回的业务数据应符合注册时提供的 JSON Schema 不符合的则认为是注册信息