服务总线接口规范标准.docx
《服务总线接口规范标准.docx》由会员分享，可在线阅读，更多相关《服务总线接口规范标准.docx（13页珍藏版）》请在冰点文库上搜索。
服务总线接口规范标准
安徽电信服务总线接口规范
安徽电信有限公司
2014年02月
版本记录
版本号
时间
记录人
变更原因
变更描述
V0.1
2014-1-5
李超
初始
V0.2
2014-2-22
李超
修订
增加接口参数描述
第1章
概述
1.1概述
本规范明确了安徽电信服务总线接入及服务使用的标准和规范，为服务使用方和服务提供方提供开发参考。
1.2目标
本规范为了指导各业务系统与服务总线平台的对接，实现以下目标：
1）当服务总线接入业务系统服务时，为该服务提供方提供开发依据。
2）当服务使用方调用服务总线提供的服务时，为该服务使用方提供开发依据。
3）为服务使用过程中安全及控制提供标准和参考。
1.3规范使用对象及说明
本规范适用于所有新建或改造的服务接口，均需要遵守本规范约定。
1.4名词解释
1）服务提供方：
提供原始服务，并将服务发布到服务总线的内部业务系统、第三方企业或个人。
2）服务使用方：
使用服务总线上的服务进行应用开发的内部应用系统、第三方企业或个人。
3）服务商：
平台为统一管理服务的提供方和使用方，综合其统称为服务商。
4）服务：
服务是执行可重复任务的可发现资源，由外部化的服务规范进行描述。
服务可分为技术服务和业务服务两种。
第2章服务设计原则
由于各个系统和平台之间存在差异性，为确保安徽电信服务总线的稳定高效，服务设计原则如下：
2.1接口协议统一原则
所有服务的接口均基于Http协议。
服务提供方和服务使用方必须同时使用同一种类型的技术来进行开发和调用，调用的服务通过HTTPURL中特定属性进行标识，具体见接口协议。
2.2数据格式统一原则
服务的接口数据包含业务所有的业务数据，数据采用JSON格式表示，并且符合相应的JSONSchema。
服务提供方和服务消费方必须同时使用同一种格式进行数据交互。
2.3服务定义唯一性原则
一个服务应该只实现一个业务功能，业务功能的区别通过服务编码来区分，不应通过定义不同的业务数据在同一个服务编码下实现不同的业务功能。
2.4服务无状态原则
服务应是无状态的，两次请求之间无须状态和会话的保持，并可以采用轮询的方式在负载均衡器上进行注册
2.5服务部署原则
服务应是全局的，不应区分本地网、大区等，但可以部署多份用以提供不同优先级的服务。
2.6服务组合原则
服务按照服务粒度设计成原子服务和组合服务。
原子服务为最细粒度的服务，组合服务由原子服务组合而成。
为有效提高组合服务的效率，跨系统的组合服务由服务总线调用不同的原子服务实现组合，系统内的组合服务由服务提供方在应用内部进行组合。
2.7报文内容处理的原则
服务请求和返回的的报文应符合JSONSchema格式。
服务请求方和提供方应采用通用的JSON解析器来构造和解析数据，JSON不同含义的段落应定义明确含义的字段名称，相同内容的数据应采用数组来进行描述，双方可根据JSON名称和路径进行精确定位，不应根据字段的顺序来获取字段值，字段值不受字段顺序调整的影响。
报文统一采用UTF-8进行编码。
2.8出入参设计原则
为提高查询类服务的通用性和性能，查询类服务在入参中定义返回字段列表，服务提供方根据入参中指定的字段返回信息。
查询内接口应在入参中定义分页参数，返回参数中应包含当前页数、总页数或是已到最后一页等信息。
返回参数中如返回静态编码值时应同时返回此编码值对应的名称。
2.9规则校验的原则
服务提供方应对请求报文格式和关键信息进行合规性和业务校验，防止非法访问和入侵。
2.10数据量原则
服务总线所传递的单条消息大小原则上不大于1M，否则应建议采用文件传输、接口表传输、直连等连接方式。
2.11同步调用原则
服务调用方和服务提供方采用同步调用的方式进行请求，如需要使用异步调用可采用消息队列或服务调用方定义异步通知接口来实现。
2.12统一入口原则
服务总线对外提供统一的调用地址。
2.13持久化原则
服务使用方在使用服务的过程中，由服务总线进行整个过程的日志记录，并对调用的详细信息进行持久化，便于对账和稽核。
建议服务调用方和提供方对调用的关键信息（如流水号，源地址等）进行持久化。
第3章服务接入规范
对于服务调用的访问方式，平台采用标准的HTTP调用方式。
3.1调用方式
接口服务通过http:
//ip:
port/oip/rest访问平台服务。
IP和PORT根据实际生产环境情况对外公布。
其中/oip/rest保持不变。
实例：
基于REST的服务请求
以使用“查询BSS用户短信详单”服务为例，该服务的具体信息如下：
服务名称：
查询BSS用户短信详单；
服务编码：
SelectSmsInfo；
开发技术：
采用HTTP协议技术；
请求方式：
采用GET/POST都可以
调用方信息不变。
根据上面这些信息，得出服务访问地址为：
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.OPEN_3RD.Sync&msgId=crm_20130718_10001&busiURl=/SelectSmsInf/1
业务参数的内容放在http的请求体中传输
3.2参数说明
3.2.1系统级参数
以下参数是由服务总线定义的。
表格31系统级参数
参数名
类型
是否必需
描述
Send
string
是
客户端所属系统编码，填写请参考3.1节（系统标志全部采用此编码）
servCode
string
是
客户端需要访问的服务编码，由服务总线在注册后统一提供
msgId
string
是
由调用方系统按照OIP规则生成的唯一标识一次调用的字符串，长度小于64位。
生成规则：
系统名_当前时间戳_流水号
busiUrl
string
是
消费方传递的业务部分地址
App_key
String
否
服务总线分配的应用标志
transactionId
String
是
交易流水号，由调用方生成，多次请求均会包含此信息。
格式建议为系统名_当前时间戳_流水号
R1
String
否
动态路由参数1
R2
String
否
动态路由参数2
R3
String
否
动态路由参数3
transactionId：
交易流水号。
服务请求需经过多个系统或多个系统模块，为了有效标志出一次业务请求经过的所有调用，服务调用方在请求时生成一唯一的流水号，服务总线在多次调用过程中将会保持此交易流水号一致，服务提供方也应记录此交易流水号。
所有消息日志应统一记录到统一日志平台以供事后分析。
R1-R3：
动态路由参数，为了保持路由的灵活性，调用方可动态添加最多3个路由参数，如版本号，本地网等参数，服务总线根据此参数路由到特定的服务提供方节点上，以满足试点，灰度发布等场景。
3.3返回业务功能
返回参数分为两部分，一部分为HTTP协议部分，包含了请求的状态，异常代码和异常信息，200表示本次请求完成，500表示服务总线调用服务提供方出现异常等；一部分为业务数据，业务数据采用JSON格式，JSON格式需符合JSONSchema的校验规则，业务异常也在此部分定义。
服务总线后台分析系统将会对请求和返回的报文进行事后分析。
第4章安全控制
4.1访问鉴权
服务总线对外提供统一安全控制策略。
所有访问能力开放平台的服务时，都必须经过平台的鉴权，鉴权通过后方允许访问，否则将给与拦截。
能力开放的访问鉴权提供如下几种策略：
服务商鉴权：
凡是使用能力开放平台的服务使用方必须是已注册的服务商下的一个客户端。
该部分由使用方进行申请，平台完成注册，同时为服务使用方分配可使用服务的权限。
IP地址鉴权：
应用集成平台支持服务使用方的IP地址身份认证模式。
对于不在服务使用方申请的IP地址范围内产生的服务调用，平台给予拦截和告警。
对于通过多重路由或映射导致不能获得实际IP地址时，将采用鉴权码方式替代。
摘要式认证：
采用标准的HTTP摘要认证方式进行访问认证，具体介绍见参考文档
OAuth2.0:
对于严格权限限制的场景，通过OAuth2.0协议进行认证和授权，授权由应用系统统一提供。
4.2传输加密
对于安全非常高的场合，建议全流程采用HTTPS协议进行加密传输，如缴费等场景。
第5章异常分类编码
在使用平台服务的过程中，平台对不同的异常进行分类，供开发者和使用方在调测及使用过程中参考。
种类
编码
描述
正常
0
成功
接口请求方异常
2
消息格式异常，例如必填参数未填、消息编码异常等
3
无效的路由属性
10
接口请求超过指定流量
9
接口请求包大小超过限制
6
权限异常（例如无权访问此服务）
101
重复请求
102
无效的业务域或业务大类、小类
199
接口请求方其他异常
接口响应方异常
8
接口响应方超时
201
接口响应超过指定流量
202
接口响应包大小超过限制
298
接口响应方内部异常
299
接口响应方其他异常
平台异常
4
调用的服务未发布
5
调用的服务已注销
7
调用的服务已关闭
11
调用的服务不存在
1
服务调用失败
398
平台内部异常
399
平台其他异常
其他异常
999
其他异常
测试异常
601
测试接口未实现
业务定义异常
>1000
如果遇到上述类似异常代码或信息，可以和平台维护人员联系帮助解决。
第6章服务注册、注销、变更、调用流程
6.1服务注册的流程
服务注册和变更：
由服务提供方在ITSM发起申请，经服务评审后，由ITSM调用服务总线提供的能力进行注册和变更。
服务注销：
由服务提供方或服务总线管理方根据实际需求和服务的调用次数等评估后发起，经服务提供方、服务总线管理部门和服务调用方会审后在ITSM中发起下线流程。
服务调用：
由服务调用方发起，经服务提供方确认和服务评审后在服务总线上进行注册。
服务评审由服务总线管理部门牵头组织。
6.2服务注册的内容
名称
说明
接口名称
接口编码
接口简要描述
请求报文样例
返回报文样例
请求报文格式定义
返回报文格式定义
接口业务异常列表和描述
版本号
对应的服务节点
注册服务地址
探测报文（可选）
是否进行探测（时间，频度）
备用服务地址（在连续失败或拨测失败等情况下自动或手工切换服务地址）
6.3测试环境服务注册的流程
测试环境服务注册由ITSM发起，在完成表单填写后自动在服务总线上进行处理。
第7章服务治理
7.1目标
1、所有域的服务按照协议规范全部接入服务总线，避免出现服务未在服务总线直接使用。
2、注册在服务总线上的服务必须符合服务总线的规范，包括接口协议，数据格式，不得私自更改协议或超过注册的内容升级接口内容
7.2检查方法
1、按照所有服务全部由服务总线调用或者由F5负载均衡器调用的基本原则，服务管理团队会定期对主机和F5上服务的调用方IP进行审核，如果出现服务端口出现非服务总线或非F5主机的调用，或者F5主机上服务端口非服务总线的调用，则认为出现了异常的服务调用，由服务提供方提供服务调用日志或版本变化情况进行详细的解释。
2、服务接口参数应符合接口规范，服务总线将定期对服务调用异常、失败、异常代码等进行统计，给出服务接口的符合度。
3、服务返回的业务数据应符合注册时提供的JSONSchema，不符合的则认为是注册信息不全或异常升级。
服务总线将定期从服务调用报文中进行格式校验，对不符合格式的消息请求反馈服务提供方并要求进行说明。
7.3服务监控的指标
指标类型
运行类
调用次数
平均调用时长
1秒以内调用次数
1-5秒以内调用次数
5秒以上调用次数
调用成功次数
调用失败次数
调用超时次数
非法调用个数
常规类
服务注册个数
服务变更个数
服务注销个数
规范类
异常服务接口个数
接口请求不合规个数
报文格式不合规个数
7.4服务目录树
服务总线上注册的服务按照服务目录树进行组织，新增的服务需按照服务的类别进行归类。
服务目录由服务总线统一维护和发布，服务使用方和调用方均可以访问服务总线平台获取服务的详细信息。
服务目录示例：
服务大类
服务小类
服务名称
提供系统
服务编码
输入参数
输出参数
报文示例
异常描述
组织视图
组织视图
工号登陆接口
CRM
工号,密码
工号对象
参考资料：
JSONSchema:
http:
//json-schema.org/
AnExtensiontoHTTP:
DigestAccessAuthentication：
http:
//tools.ietf.org/html/rfc2069
升级会员 