中国移动浙江公司IT系统接口设计规范(v1.1)

shengpsary 贡献于2013-10-26

作者 温暖  创建于2008-07-02 19:19:00   修改者Tony  修改于2012-10-31 02:38:00字数18544

文档摘要:  为提升软件质量,提升内外部客户感知,系统架构管理工作已列为部门工作重心,通过架构调整推动系统性能和稳定性的提升、系统灵活性和扩展性的提升,延长系统生命周期。
关键词:

 中国移动浙江公司IT技术规范 JSGF-SJ-105 中国移动浙江公司信息技术部 2012年10月 目 录 1 文档修订记录 1 2 引言 2 2.1 编写背景 2 2.2 适用范围 2 2.3 参考文档 2 3 接口设计要求 3 3.1 接口设计原则 3 3.2 接口设计方法要求 4 4 接口集成技术 5 4.1 传输控制设计 5 4.2 动态资源管理设计 5 4.3 接口服务封装设计 5 4.4 接口集成方式 6 4.4.1 接口技术分析 6 4.4.2 接口技术适用场景 7 4.4.3 接口的归纳与分类 9 5 服务类接口设计 10 5.1 接口功能架构设计 10 5.2 接口功能设计 12 5.2.1 会话解析 12 5.2.2 流量控制 12 5.2.3 报文获取与解析 13 5.2.4 安全控制 14 5.2.5 业务逻辑 16 5.2.6 输出参数封装 18 5.2.7 异常处理 18 5.2.8 日志设计 20 5.3 接口功能流程 22 5.4 配置要求 24 6 表接口设计 25 6.1 表接口分类 25 6.2 表接口适用场景 26 6.3 表接口设计要求 26 6.4 表接口访问要求 28 6.4.1 业务处理要求 28 6.4.2 归档要求 28 6.5 数据库设计要求 29 6.5.1 命名规则要求 29 6.5.2 清理机制 29 7 文件接口设计 30 7.1 文件分类和使用场景 30 7.1.1 文件类型 30 7.1.2 生成方式 30 7.1.3 采集方式 30 7.2 文件设计 31 7.2.1 文件命名 31 7.2.2 文件大小 31 7.2.3 文件内容 31 7.2.4 分隔符 32 7.2.5 基本数据格式 32 7.3 功能设计 33 7.3.1 业务数据检查 33 7.3.2 完整性检查 33 7.3.3 安全控制 33 7.3.4 文件压缩 34 7.3.5 文件处理 34 7.4 日志设计 34 8 编码规则 35 8.1 接口编码规则 35 1 文档修订记录 修改日期 修改人 修改内容简述 版本号 2012-5-10 石益宇 新建 V0.1 2012-7-3 孙铁权 调整文档结构和内容 V0.5 2012-8-3 孙铁权 调整口令认证,接口编码规则。新增错误编码原则。 V1.0 2012-10-16 孙铁权、甘旺根 调整口令认证,细化接口内容,增加日志,异常等功能和非功能说明,区分服务类接口设计,重构文件接口设计,重构表结构设计 V1.1 2 引言 2.1 编写背景 为提升软件质量,提升内外部客户感知,系统架构管理工作已列为部门工作重心,通过架构调整推动系统性能和稳定性的提升、系统灵活性和扩展性的提升,延长系统生命周期。 2.2 适用范围 本规范重点从业务和技术角度出发,给出了我省IT系统内部子系统间和与外系统间的接口建设要求,供我省信息技术部内部和厂商共同使用;适用于我省IT系统工程的建设。 本文档所提到的系统接口是指我省IT系统内部子系统间和与外系统间之间的接口,多个系统相互配合共同完成完整的业务流程,系统接口的梳理和标准化定义是实现系统远期规划目标的重要保障。 2.3 参考文档 《中国移动浙江公司信息系统梳理(2012年)-V 1.5.vsd》 3 接口设计要求 3.1 接口设计原则 为了保证我省IT系统的完整性和健壮性,系统接口应满足下列基本要求: l 高性能 对系统间的接入提供企业级的支持,在我省IT系统的高并发和大容量的基础上提供安全可靠的接入,为系统持续高效运行提供保障。 l 可伸缩性 保证在充分利用系统资源的前提下,实现接口能力的平滑移植和扩展,同时在访问并发量增加时提供接口能力的动态扩展,以保证接口的稳定性。 l 高可用性 实现企业级7×24小时的高可用性,具备异常处理能力,支持多机集群的部署方式,并能提供必要的日志,监控,告警能力。 l 可扩展性 在新业务扩展和新系统接入中,提供快速、方便和准确的实现方式。 l 健壮性 提供可靠的运行环境,保证系统在内部、外部的不可预知的出错情况下,能够提供正确的容错处理机制,防止数据丢失。 l 安全性 提供完善的信息安全机制,以实现对信息的全面保护,保证系统的正常运行。 l 可管理性 提供良好的接口管理机制,保证可在接口的运行过程中提供给管理员方便的管理方式,以处理各种情况。 l 可监控性 提供有效的接口监控机制,使得接口的运行情况可监控,便于及时发现错误及排除故障。 3.2 接口设计方法要求 接口设计要遵循五步方法论,如下图所示: l 确定功能边界:以需求分析结果作为接口设计的输入件,明确相关系统各自的功能范围,划分系统间的功能边界,功能边界是确定系统间集成关系的基础。 l 分析共享数据分布:分析接口相关的系统交互时所需共享数据的系统归属,定义接口共享数据模型,明确数据实体、实体间关系、实体属性。 l 归纳跨系统业务流程:根据业务功能以及数据分布的要求,并结合实际的业务流程运转情况和要求,确定所有跨系统业务流程中接口涉及系统的业务流程,业务流程用时序图来表示系统间的业务数据交互情况,关注系统间和具体实现技术无关的数据交互。 l 确定系统集成关系:将跨系统业务流程进行整合归并得到IT系统内部和与外部的集成关系图,并汇总系统间的交互的主要数据。 l 确定系统间接口:根据系统集成关系图,分析系统间接口的数据要求和技术要求,给出接口技术实现建议,并提供参考接口列表。 4 接口集成技术 4.1 传输控制设计 传输控制指利用高速数据通道技术实现把前端的大数据量并发请求分发到后端,从而保证应用系统在大量接口调用方同时请求服务时,能够保持快速、稳定的工作状态。这种控制模式可以降低接口网络负担,提高接口吞吐能力,保证系统的整体处理能力。 4.2 动态资源管理设计 接口根据具体需求应能提供负载均衡、伸缩性与动态配置管理、网络调度等资源管理功能,保证接口连接的稳定可靠。它主要体现在以下几个方面: l 负载均衡 为了确保接口服务吞吐量最大,接入层自动地在系统中完成动态负载均衡调度。 l 伸缩性与动态配置管理 可以由系统自动伸缩管理方式或动态配置管理方式实现数据依赖路由管理、网络用户管理、队列管理、存取资源管理,以及接口应用的恢复处理等。 l 网络调度 在双方接口之间设置多个网络通道,实现接口的多数据通道和容错性,保证当有一网络通道通讯失败时,可进行自动的切换,实现接口连接的自动恢复。 注:对于以上3点要求,如果已经通过负载均衡器、路由服务器、中间件、多网卡等方式实现,就不作要求。 4.3 接口服务封装设计 接口服务封装过程应遵循简洁、实效和使用方便的原则。且必须具备以下特点: l 底层原子服务封装尽量单元化,服务之间不重叠,不交叉。 l 服务响应及时,具备高效的特点。 l 接口逻辑内敛,不冗余,出入参数清晰。 l 日志记录齐全。 另外,接口服务作为客户端访问服务的通道,也需要保护底层实现逻辑和部署,使得后端实现机制不暴露给客户端,客户端只需要关心业务实现,而无法获取底层实现。 4.4 接口集成方式 4.4.1 接口技术分析 系统接口总体架构遵循的原则是: l 系统间的接口交互可以通过ESB方式来实现。在ESB方式实现条件不具备或者在某些特别情况下,如大文件和大数据量的传输,建议使用FTP和表接口。 l 跨系统间的小数据量事务交互接口实现技术,可推荐使用Web Service技术、Socket技术和消息队列技术。应该采取各种安全技术加强数据传输安全和权限限制的要求。 l 为保证合理可靠的完成系统集成接口要求,集成接口应该满足的接口技术要求。 接口技术选择时应根据每个技术的特性,将其应用在最合适的业务场景和技术场景。对于常用的接口技术应遵循以下的应用原则: l WebService:小数据量的实时、非实时传递,适用于大范围开放给外围系统并且有安全要求的业务,适于设计外部接口间的接口。 l ATMI:同步实时小数据量传递,适用于交易方式面向客户的实时交易的业务,适于设计系统内部系统的接口。 l J2EE/EJB/JCA:适用于接口调用性能、实时性要求非常高的地方,包括事务一致性也要求非常高的地方,适于设计系统内部子系统之间的接口。 l FTP:异步非实时传递,适用于交易数量大、实时性要求不高、不直接面向客户的批量业务或后台业务,适于设计系统内部子系统之间的接口。 l HTTP:小数据量的实时、非实时传递,适用于大范围开放给外围系统并且有安全要求的业务,适于设计外部接口间的接口。 l Socket:大数据量、小数据量的实时、非实时的传递,较适宜接口性能要求更高、但对负载和安全性要求不是很高的场景,适于设计系统内部子系统之间的接口。 l 接口表:大数据量的实时、非实时传递,适用于交易数量大、实时性要求不高、不直接面向客户的批量业务或后台业务,适于设计系统内部子系统之间的接口。 4.4.2 接口技术适用场景 根据以上的接口归纳和分类,现将主要的一些接口应用场景进行比对和简要分析,以便能够对系统间的接口需求,选择合理的接口技术应用。 接口聚类 业务应用场景 建议接口技术 建议接口结构 同步实时小数据量 系统间需要实时进行小数据量的交互,主要应用于完成特定业务的跨系统数据交互,如业务开通等。系统间的数据交互,无论是获取数据还是反馈数据,都需要能够保持系统间的交互和链接,直到在第一时间获取相关系统反馈数据。 n 优点: 在各相关系统稳定运行基础上,数据交互效率高,系统集成高度集中,故障定位方便快速。对于实时性要求很高,基于联机事务的控制和回滚较合适。 n 缺点: 各个环节之间的数据流衔接受制于相关系统数据的输入、输出。依赖于各个系统稳定运行的基础之上,一旦相关数据流中的某个系统发生故障,整个系统体系架构出现数据滞留和停顿,系统体系架构的耦合性较高。 WebServie/Socket/ATMI XML 同步实时大数据量 系统间需要实时进行大数据量的交互,主要应用于一些短信、彩信、资源等大批量数据的交互。系统间的数据交互,无论是获取数据还是反馈数据,都需要能够保持系统间的交互和链接,直到在第一时间接口返回才允许继续执行任务。 接口表 表记录 n 优点 具备完善的控制,可保证大数据量的可靠、完整传送,并且大数据量交互的实时性相对高。 n 缺点 同步实时大数据量交互资源消耗大,容易造成性能和稳定性的问题,对业务系统的正常运行存在一定的影响。 异步非实时小数据量 系统间非实时小数据量的交互,主要应用于一些业务开通等一系列完成一个特定业务的跨系统单据间的数据交互。系统间的数据获取或者数据反馈,通过一套可以实时的数据通讯方式进行控制,不必长时间保持系统间的数据连接和交互来获取相关系统的数据输入、输出。 n 优点 系统间的耦合性较低,数据交互不依赖于周边系统状态,通过一套可以非实时的异步通讯方式来进行数据间的交互链接。不受异构系统数量影响,可以不关注多个异构系统架构进行系统间的集成。在某个节点系统发生故障时,不影响其他系统运行状况约束。 n 缺点 系统间的数据传递需要有完备的体系,保障数据可以快速、稳定传送。并支持交互数据的重发等一系列的异常情况处理。由于采用了异步非实时接口,因此系统间数据流的反馈有可能不在第一时间到达各个系统,产生业务响应相对滞后的隐患。 JMS+消息队列 XML 异步非实时大数据量 系统间需要交互大量的数据,这些大数据量的交互不论对需要更新的目标系统还是发送的远数据系统,都会产生性能等多方面的影响。主要应用于一套数据副本在各个系统间保持数据一致,或者各个系统边界重叠交互数据的一致。系统间的数据交互,可以通过一个合理的时间点设定来确定数据交互的周期和时间,而不会产生大数据量交互对系统带来的影响。同时各个系统能够在时间点之外独立稳定运行。 n 优点 可以实现异地大文件的传输,特别是话单文件,局数据文件的传递,系统耦合度较低。是不同系统间有效的数据传递方式。 FTP FILE n 缺点 异步非实时大数据量的时间点设定需要综合考虑各个系统参数和体系结构因素。一旦时间点设置不合理会产生一系列的连锁反应,导致各个系统数据无法一致,影响系统间的交互重叠数据的一致性。大数据量的传送需要能够有完善的异常处理机制和通信稳定性的保障,避免重复的大数据量交互或者只完成部分的不完全交互。 FTP XML+FILE 4.4.3 接口的归纳与分类 接口是系统间数据交互的传递,是一个成体系系统业务正常流转的核心构件。现将系统间接口的接口调用方式、交互方式、接口数据量和交互的频繁程度进行简要的归纳和分类: l 接口调用方式 Ø 同步:调用方在调用接口后必须在接口的结果返回后才可以继续执行自己的任务; Ø 异步:调用方在调用接口后不需要等待接口的结果返回,可以继续执行自己的任务; l 接口交互方式 Ø 实时:接口的响应速度有很高的要求,通常要求接口处理能在秒级完成,比如用户界面访问,告警数据传递等; Ø 非实时:调用者对接口执行速度要求不太高。 l 接口数据量 Ø 大数据量:指大量数据传输,通常是批量数据 Ø 小数据量:接口数据量偏小,一般小于100K的数据包(实际情况跟机器性能、网络情况、交易频度有关)。 l 接口频率 Ø 周期:接口按固定周期,比如按日、按周、按月、按小时、按分钟或其他频率交互。 Ø 非周期:接口不按固定周期交互,通常为时间触发,比如查询。 5 服务类接口设计 5.1 接口功能架构设计 接口设计功能流程图: 说明: l 会话解析:对会话进行解析,获取IP信息。 l 流量控制:为减少后端服务压力,网络传输压力,进行必要的服务请求控制,业务请求管理,和传输技术的使用。 l 参数解析:参数包括公共信息,鉴权信息,业务信息的解析。 l 安全控制:包含口令认证,权限控制等措施。 l 业务逻辑:进行业务数据检查,业务参数解析和组装,后端服务调用,完整性管理等,完成部分异常请求的隔离。 l 返回参数封装:对返回参数进行组装,包含业务办理完毕正常返回和发生异常的错误信息返回。 l 异常处理:包含系统级和业务级的异常处理,包括连接中断,服务超时,服务僵死,业务类型错误,业务办理冲突,信息缺失,业务无效,用户无权限,流量超过阀值等异常事件的处理。 l 日志:包含业务日志与错误日志。日志记录需要符合审计、维护、告警监控等要求。 5.2 接口功能设计 5.2.1 会话解析 接口在接收请求后,需先进行会话解析,通过会话解析获取客户端的真实IP。为后续的安全控制,日志记录等获取必要信息。 会话解析的标准方法,需要以公共函数方式提供。 遇到前端有负载均衡的情况,可根据需求获取VIP信息或真实IP。需要获取客户端真实IP的,可由负载均衡侧进行调整,透传真实IP,而不是传给服务端VIP信息。 5.2.2 流量控制 在接口设计层面,为降低服务端压力,网络负担,接口必须具备流量控制能力,流量控制包含并发量控制,批量业务请求管理,数据压缩等内容。 l 对于服务进程,需要有正常业务请求和异常业务请求最高并发量的控制。 Ø 对于单个服务进程,需要有正常业务请求的最高并发量的控制,超过最高并发量的请求直接返回“系统繁忙”等友好提示信息。并需要有异常最高并发量的控制,短时间内出现大量异常的请求,根据实际情况,对客户端或者用户进行拦截,保证服务端的稳定运行。 Ø 对于同一类服务,可在中间件上实现总流量的控制,控制方式与单个服务进程的方式相同。 Ø 表接口和文件接口,需要在客户端进行控制,不能过度访问。服务端增加监控措施,防止表接口和文件接口I/O过大,访问频率过高,影响接口响应时间。 l 在服务请求中只接受单笔业务请求,对于某些业务中需要提交批量数据的,由业务调用方控制完成相应的多次业务调用,或采用文件接口、表接口,来完成批量业务请求。 l 接口根据具体的需求应提供数据压缩/解压功能,以减轻网络传输压力,提高传输效率。 在使用数据压缩/解压功能时,应具体分析每一类业务的传输过程、处理过程、传输的网络介质、处理的主机系统和该类业务的并发量、峰值及对于所有业务的比例关系等,从而确定该类业务是否需要压缩/解压处理。对于传输文件的业务,必须压缩后传输,以减轻网络压力,提高传输速度。 在接口中所使用的压缩工具(函数)必须基于通用无损压缩技术,压缩算法的模型和编码必须符合标准且高效,压缩算法的工具函数必须是面向流的函数,并且提供校验检查功能。 注:以上流量控制措施,可以在接口集成里实现,如采用中间件配置最高并发数等。 5.2.3 报文获取与解析 5.2.3.1 控制参数设计 接口控制参数控制接口报文的读取,验证请求和报文是否传输完毕。设计需简短,避免在接口控制层解析数据报文来确认请求数据传输的完整性。控制参数设计可使用以下方式: l 在报文前端添加报文长度信息,接口解析后按此长度读取报文。 l 在报文结尾添加报文结束标记,接口读取报文时验证结束标记。 5.2.3.2 公共参数解析 公共参数是客户端请求服务时,报文内携带的客户端基本信息和操作员信息参数。 接口入参设计中必须包含公共信息部分,此部分信息可在报文头中体现,也可在xml报文体节点中体现。 接口对公共信息进行解析,获取操作员相关信息,客户端相关信息,以进行下一步的安全控制。 接口公共信息的设计,避免了业务参数在未经过鉴权时就进行解析,增加业务请求的透传效率。且对于鉴权不通过的请求,可由接口拦截,避免大量无效业务信息的解析,并降低服务端压力。 接口公共参数解析的标准方法,需要以公共函数方式提供。 公共信息参数设计时,必须包含以下参数: 参数 参数约束 备注 操作员账号 必填 操作员密码 必填 建议加密方式 操作员组织 必填 操作员ID 可选 操作员登陆组织 可选 操作员登陆时的组织,对于全省通的用户权限,可切换到地市组织进行登陆。 操作员归属地区 必填 发起请求的地区 访问请求IP 可选 发起请求IE、终端IP 访问请求主机名 可选 发起请求的IE、终端主机名 客户终端号 可选 终端编号 渠道信息 必填 渠道信息。 5.2.4 安全控制 提供完善的信息安全机制,以实现对信息的全面保护,保证IT系统的安全运行,各种接口都应该保证其接入的安全性。 接口的安全是系统安全的一个重要组成部分。保证接口的自身安全,通过接口实现技术上的安全控制,做到对安全事件的“可知、可控、可预测”,是实现系统安全的一个重要基础。 根据接口连接特点与业务特色,制定专门的安全技术实施策略,保证接口的数据传输和数据处理的安全性。 系统应在接口的接入点的网络边界实施接口安全控制。 接口的安全控制在逻辑上包括:口令认证、权限控制、加密等内容。 5.2.4.1 口令认证 接口用户登录,一般采用口令认证方式,口令认证应具备防猜测机制,限制客户端连续尝试的次数。 l 接口接收请求时,需要对操作员进行口令认证。一次口令认证只对当前请求有效,下一次服务请求需要重新认证。 l 对个人客户开放的应用,可采用动态的口令认证机制,将动态密码发送到个人手机上进行登陆认证。 5.2.4.2 权限控制 权限控制指对用户可访问服务的限制,包括IP访问限制,权限限制: l IP访问限制,即某项服务只有某个特定的IP可访问或不可访问。需要采用可配置形式进行设计,IP列表可存放文件,数据库等方式。 l 权限限制,主要指接口操作员可调用的接口权限控制。针对不同渠道,不同类别的操作员,支持开放不同的服务列表,有权限的用户才能访问,保证各系统服务的专有性和安全性。对于权限控制,可在接口系统建设时自行设计,也可调用统一的权限控制系统进行控制,但必须做到可配。 5.2.4.3 加密 加密主要包含报文加密,用户密码加密等。 l 报文加密:主要适用于服务类接口的报文。对xml报文,fml报文等进行加密或转义,加密算法建议使用加密包、动态库等方式,在业务实现代码中调用,方便加密算法的变更与替换。 l 用户密码加密:指在报文传输过程中对报文中的用户密码信息进行加密,对存放在配置文件中的用户密码进行加密,对存放在数据库中的用户密码进行加密。 5.2.4.4 其他安全设计 接口的其他安全措施,包括二次密码验证,防外挂设计等。 二次密码验证:在部分查询接口内,包含客户隐私信息,敏感信息,如详单查询接口,需要加入二次密码验证。 防外挂设计:服务端具备智能行为分析能力,防止外挂程序植入。 5.2.5 业务逻辑 5.2.5.1 业务参数设计 接口业务参数,对于基础数据,枚举值等,需要以配置形式实现,参数在客户端和服务端进行翻译,便于减少报文大小,降低消息传输压力,并减少开发同类接口的难度和出错率,提升开发效率。在基础数据和枚举值变更时,无需修改代码,只需要调整配置即可实现,方便快捷。 原则上服务类接口报文设计在10K以下,超过10K小于100K的报文,需要单独建立大报文通道,超过100K的可走表接口或者文件接口,特殊实时性要求比较高的大报文需走服务类接口的,需经过评审。 5.2.5.2 业务逻辑处理 接口业务逻辑处理,主要是对业务参数处理。业务参数,即用户办理业务时,需要的业务相关信息,如产品订购业务,包含手机号码,产品编号,生效时间,失效时间等。 业务逻辑处理主要包含业务参数解析与组装、后台服务或函数调用以及返回业务参数封装。 l 业务参数解析与组装:从报文中获取业务办理参数,并组装成后端服务或函数所定义的格式报文; l 服务或函数调用:调用后台服务或函数,根据业务报文进行业务处理; l 返回业务参数封装:对服务或函数返回的业务参数进行封装,并返回给参数输出层。 5.2.5.3 业务数据检查 接口应提供业务数据检查功能,即对接收的数据进行合法性检查,对非法数据和错误数据则拒绝接收,以防止外来数据非法入侵,减轻IT系统处理负荷。 对于接口,其业务数据检查的主要内容有以下几个方面: l 数据格式的合法性:如接收到非预期格式的数据,包括接收的数据长度,类型,开始结束标志等。 l 数据来源的合法性:如接收到非授权接口的数据。 l 业务类型的合法性:如接收到接口指定业务类型外的接入请求。 对于业务数据检查中解析出非法数据应吐出满足报警、统计、分析要求日志信息,并返回异常信息。 5.2.5.4 完整性管理 完整性管理设计要求保证数据传输的完整性,保证交易的完整性。 数据传输的完整性要求数据传输不遗漏,数据传递可靠: l 消息包中,在报文前端记录报文长度,或在报文尾添加结束标记。 交易完整性要求服务提供事物管理模式,对于接口请求的处理必须完整: l 接口内部存在多环节处理时,有任意环节处理失败,必须保证其他环节回退。 Ø 通过系统应用控制回退操作,当服务请求处理失败时,通过系统应用程序,分析服务请求办理轨迹和日志信息,对接口操作进行回退。如某套餐办理失败,系统应用程序根据当前用户的套餐状态,和日志中进行的操作,对用户状态进行更新,达到回退的目的。 Ø 提供回退接口,反向调用业务接口进行回退。如某套餐办理,提供一个套餐办理接口,再提供一个套餐办理回退接口,当套餐办理失败时,可调用套餐办理回退接口进行业务办理的回退。 接口事务性管理,需要进行必要的服务请求办理轨迹,操作步骤,日志的详细记录。表接口和文件接口处理方式与服务类接口一致。 5.2.6 输出参数封装 5.2.6.1 公共参数封装 接口业务请求正常处理完毕,接口需返回处理完毕的提示信息。若请求未正常处理,接口需要返回处理失败的提示信息,且在返回信息中添加错误编码。 返回参数作为业务受理结束后,返回给客户端的信息。除业务信息外,至少需要包含以下信息: 参数 参数约束 备注 返回码 必填 0:表示业务正常受理成功; 非0:错误编号,表示业务失败,失败原因在错误信息和提示信息描述。 错误信息 可空 当失败时,必填,系统的错误信息,该信息不能直接返回给界面,而是系统查问题使用。 提示信息 可空 当失败时,必填,提示给客户的信息,如系统忙等。 5.2.6.2 返回参数打包 将返回公共参数和业务参数按照接口报文协议进行组装,返回给客户端,完成业务请求处理。 返回参数打包的标准方法,需要以公共函数方式提供。 5.2.7 异常处理 需要在接口架构的每个层次加入异常捕获,发生异常时记录详细的异常代码,异常信息,包括代码和日志,以保障服务进程的健壮运行和维护分析。 接口异常包括系统级异常(错误)、业务级异常(错误)、代码级异常(错误)。所有异常,均需记录详细的异常日志,吐出日志内容需符合告警监控要求。且根据不同的异常信息,可选择不同的处理方式。 l 系统级异常:指接口运行的基础系统出现异常,与业务办理无关。包括数据库连接中断,服务端连接中断,超时等。在接口设计层面遇到以下异常,除进行必要的日志记录外,还要进行异常的判断和处理: Ø 数据库连接中断:指接口调用数据库时发生的会话中断。需要重建数据库连接,根据具体的业务要求再进行业务的重处理,或直接返回连接恢复信息。 Ø 服务端连接中断:指接口调用后端业务服务的连接中断。根据后端资源配置情况,选择重建服务端连接,或切换到其他负载均衡节点。并根据具体的业务要求再进行业务的重处理,或直接返回连接恢复信息。 Ø 超时:在接口调用后端服务时,由于服务无响应,繁忙,僵死等情况可能出现服务请求无法正常返回,需要有超时机制,超时时长可配置。在请求超时后,对于可回收请求需尝试重处理,重处理次数实现可配。对于少量且不重要的业务请求,可记录日志后忽略。设计、维护人员可根据日志事后分析,根据需要调整设计、部署和配置。 l 业务级异常:指异常发生在业务办理过程中,由于业务办理要素不具备、不齐全、不正确导致业务办理失败的异常信息。包括: Ø 业务指令错误:接口服务接收到无法处理的业务指令,如在密码变更接口里发送密码重置指令; Ø 业务办理冲突:重复办理同一类业务,或办理两类相互冲突的业务,如用户已加入家庭亲情网,再申请加入其他家庭亲情网; Ø 信息缺失:业务办理要素不齐全或用户资料不完整; Ø 业务限制:根据用户资料状态,限制不能受理某些业务,如全球通用户不能办理动感地带的产品; 业务级错误,一般根据实际情况,记录业务异常日志信息,并在返回报文中标注错误类型和原因。 l 代码级异常:在代码层面可捕获的异常,分为可预知或不可预知的异常。 Ø 可预知异常:需进行逻辑判断,以防止异常发生。如对查询条件或查询结果进行空指针判断处理。 Ø 不可预知异常:在内部函数调用时,无法预测函数是否异常等情况下,需在调用层加入异常捕获机制,防止服务进程CORE掉。 5.2.8 日志设计 为了保证接口的安全和维护管理,接口日志作为接口设计的一个重要组成部分,必须做到只要服务端能接受到客户端请求,无论业务处理成功或失败,就必须有日志输出。并要求对接口通信服务器的系统日志、接口应用服务器的应用日志进行实时记录。 日志的记录方式,包括文件方式,表方式: l 文件方式:将日志记录在文件中。日志内容格式、文件命名规则,存储路径要求可配置。文件命名规则要求:服务进程名称+PID+YYYYMMDDHH_nnnn.log,其中: PID:进程ID; YYYYMMDDHH:年月日时(24小时制),每小时生成一个文件,如2012090622; nnnn:为序列,当文件记录已满时,采用序列号递增方式,如0000,0001。 l 表方式:将日志记录在表中。表设计时需按地市年、月、日分表,建表格式可使用XXX_NNN_YYYYMMDD,XXX可自定义,NNN表示地市编码,取值包含570-580,YYYY表示年份,如2012,MM表示月份,DD表示日期。建表时是否细分到年、月、日,需要根据接口信息量大小和业务需求制定。 日志输出还必须符合日志中心建设的相关要求,安全审计的相关要求,集团规范的相关要求。 5.2.8.1 日志参数设计 对应服务类接口日志,必须包含接口信息,客户端信息,业务信息,以及日志信息等,日志项如下: 日志信息 日志项 参数约束 说明 接口信息 接口编号 必填 参考《中国移动浙江公司IT系统接口清单.xlsx》 接口名称 可空 参考《中国移动浙江公司IT系统接口清单.xlsx》 服务IP 必填 服务端口 可空 业务类型 必填 1:查询类 2:受理类 3:验证类 4:数据流转类 0:其他 客户端信息 渠道来源 必填 填写具体的请求渠道来源。具体的渠道编码和名称可参考接口编码规则渠道接入域相关信息。 操作员 必填 操作员组织 必填 操作员地市 必填 操作员登陆组织 可空 客户端IP 必填 业务信息 请求时间 必填 接口服务请求的时间,精确到年月日时分秒,毫秒可选 响应耗时 必填 接口服务从请求到处理完毕返回的时长,单位毫秒 错误编码 必填 正常处理完毕填写0,异常的接口请求,填写具体的错误编码 用户标识 可空 业务代码 可空 输入参数 必填 输出参数 可空 对返回文件流等情况,可视情况填空。其他情况需要填写。 业务状态 可空 根据具体的业务处理环节填写,处理完毕填写0,其他可根据业务定义 日志信息 日志类型 必填 0:业务日志 1:错误日志 日志级别 必填 0:错误级别日志 1:普通级别级别 2:调试级别日志 日志记录时间 必填 年,月,日,时,分,秒 5.2.8.2 日志记录方式 服务接口日志记录方式包括文件方式和表方式: l 文件方式:将日志信息记录在文件中,需要使用标准的XML等可扩展格式。文件方式适合大量日志的记录。 l 表方式:将日志记录在表中,表设计时,需要预留字段。少量统计分析需要日志可使用表方式记录。 5.2.8.3 日志备份 日志备份包括定期备份,不定期备份,不备份: l 定期备份:按照每天,每周,每月等特定的周期备份日志。 l 不定期备份:根据日志容量,系统建设,业务需求等要素,不定期的备份日志。 l 不备份:对于不重要的日志可不进行备份,或采用轮旬覆盖的方式。 5.3 接口功能流程 从接口业务请求发起,到业务请求处理完毕的标准流程: 5.4 配置要求 为提高接口开发,维护效率,便于统一管理和应用集成,接口必须具备一定的配置功能,主要包括接口清单,调用关系,错误编码,业务参数等。 l 接口清单:配置接口的清单,包括接口编号,接口名称,隶属系统,接口描述,功能说明等。 参数 参数约束 备注 接口编号 必填   接口名称 必填   隶属系统 必填 填写接口所在系统,可填内容参考接口编码中对系统的定义。 接口功能 必填 填写接口的功能 接口描述 可空 可对接口进行详细描述 l 调用关系:配置接口的调用关系,包括操作员,接口编号,调用IP,服务地址等。 参数 参数约束 备注 操作员 必填   接口编号 必填   访问IP 可空 填写可访问接口的IP,不填表示不限制 服务地址 必填 填写具体的服务地址。比如FTP填写FTP地址,HTTP协议填写url地址等。 可访问时间 可空 接口访问开放时间,有时间限制的具体的时间,比如8:00~20:00,也可分两个字段进行配置。不填表示无时间限制。 l 错误编码:配置接口发生异常的错误编码清单,包括错误类别,错误编码,错误描述等。 参数 参数约束 备注 错误编码 必填   错误类别 可空   错误描述 必填   l 业务参数:业务参数的配置设计,需要根据实际使用情况设置。包括业务类型枚举值,品牌枚举值,渠道枚举值,办理状态枚举值,正常业务请求并发阀值配置,异常业务请求并发阀值,日志内容格式,日志记录级别,文件命名规则,日志文件存储路径等。 6 表接口设计 接口表作为系统间以及系统内部模块间异步数据交互一种重要方式,需对表接口设计进行规范。 6.1 表接口分类 按表数据在整个业务流程环节中的交次数:单环节接口表、多环节接口表。 l 单环节接口表:业务应用程序将数据写入接口表后,后续只有一种客户端读取处理数据,并将数据归档,接口在整个业务环节中,只出现一次。特点业务处理时间较短,数据一致性较高。 l 多环节接口表:接口表被写入数据后,后续有多种客户端业务进程根据接口表数据状态依次处理数据,并更新接口表数据,接口在整个业务环节中,多次出现。特点业务处理时间较长,数据一致性较低。如下图: 按组合方式:单表,多表组合。 l 单表方式:使用一张表保存业务处理过程中使用的所有数据。特点效率高,比较适合效率要求高的业务场景,如停复机工单接口; l 多表组合方式:多张接口表组合方式协作一起完成业务数据交互,一个工单交互需要访问多张接口表。这种方式一般包括通知表和业务数据表,通知表与业务数据表通过键值关联。特点效率比较低,比较适合业务实时性不太强的业务场景,如资料同步。 按数据存储方式:增量方式,全量方式。 l 增量方式:每次将变化数据写入接口表,接口表保存过程数据。特点效率高,存储内容少,但客户端逻辑处理要高。 l 全量方式:每次增量更新接口表的数据,保障接口数据完整,接口表保存全量业务数据。特点数据完整性好,对客户逻辑处理要求低。 6.2 表接口适用场景 各类接口表特点主要适用场景。在具体应用中,根据业务场景,按交互次数,组合方式,存储方式联合使用。 应用场景描述 交互次数维度 组合方式维度 存储方式维度 单环节 多环节 单表方式 多表组合 增量方式 全量方式 业务较简单、流程处理短,只需一个步骤即可完成该接口表数据的使命。如CRM送开通接口表。 n 业务复杂,业务流程长,需要多个步骤依次处理才能完成业务数据流转。如充值接口表。 n 业务数据量要求少,如停复机类 n 业务数据量大,如资料同步类 n 接口表数据在整个业务环节的作用是临时性的、过程性的、过期无效的数据 n 接口表数据在整个业务环节的作用为一直有效的,需要一直维护的。 n 6.3 表接口设计要求 表设计参考数据库设计规范《【JSGF-SJ-100】中国移动浙江公司IT系统数据库设计规范(V1.0).doc》表设计规范章节。 表设计除需遵守数据库设计规范外,接口表设计需包含字段设计规范。接口表字段主要有三部分组成:公共字段<必选> + 业务数据字段<必选> + 处理结果字段<可选>。 l 公共字段:在进行业务受理时操作场景。主要包括操作时间(时间)、渠道(地点)、操作员(人物)、业务编码(事件)等相关字段; 公共字段: 字段 字段约束 参考字段名称 备注 业务流水号 必选 DONE_CODE 业务流水号(用于核查问题,进行前后关联) 业务编码 必选 BUSINESS_ID 业务受理时间 必选 DONE_DATE 业务处理时间 必选 DEAL_DATE 业务归属地市 可选 REGION_ID 一般为用户地市,取值570~580 操作员ID 可选 OP_ID 操作员组织 可选 ORG_ID 渠道类型 可选 CHANNEL_TYPE l 业务数据字段:数据流转过程中需要的业务数据。包括被操作对象,操作数据,数据属性等; l 处理结果字段:客户端处理完数据后,需回写的内容。包括处理结果、结果描述等。这主要是针对多环节交互的业务场景。单环节交互的业务场景可选。 以下列举字段: 字段 字段约束 参考字段名称 备注 状态 必选 STATE 枚举值定义限制: 0:初始值; 1:环节一处理完成后的状态; 2:环节二处理完成后的状态; … N:环节N处理完成后的状态。 按照业务环节顺序,依次定义枚举值。 处理结果 必选 RESULT 枚举值定义限制: 0:成功 1:失败 错误码 可选 ERR_CODE 错误编码 处理结果描述 必选 RESULT_MSG 处理结果描述,可填写: 成功时提示性的描述, 失败时错误描述。 6.4 表接口访问要求 6.4.1 业务处理要求 针对客户端业务进程设计要求需遵守 接口设计原则 外,在对大批量业务处理时,需关注以下几点: l 隔离性设计:如果客户端多个进程处理同一张接口表数据时,需考虑同一条记录多个进程竞争情况。且需要将同一用户或账户的数据分配到同一进程或线程内处理,从设计角度隔离死锁发生。如停复机工单。 l 工单顺序处理设计:根据业务特性,部分业务需按工单的先后次序进行处理。如资料同步,开通工单等。 6.4.2 归档要求 针对过程性接口表数据,提出以下要求: l 当接口表数据完成使命后,需将结果数据按照处理结果分别归档,成功进入历史表,失败进入错误记录表。 l 按月分表的接口表,可以考虑将当前表作为过期后历史表,但工单竣工状态需要更新,以免被重复执行,但失败工单数据,仍需要进错误记录表,以备监控和处理。 6.5 数据库设计要求 接口表作为数据库中的对象,需要遵守数据库设计规范,参考数据库设计规范《【JSGF-SJ-100】中国移动浙江公司IT系统数据库设计规范(V1.0).doc》。 针对表接口的特殊和关注点,提出以下要求。 6.5.1 命名规则要求 针对接口表附加要求如下: l 接口表名以“I_”开头。I:表示INTERFACE。如I_SYN_BOSS_RECORD。 l 接口表完成使命后的归档表以接口表模板表为基础,新增“_H”作为成功历史表模板表;新增“_ERR”作为错误记录表模板表。如I_SYN_BOSS_RECORD_H,I_SYN_BOSS_RECORD_ERR。 6.5.2 清理机制 l 针对过期的不再使用的业务数据(主要是过程性的工单,业务数据),需申请加入实现数据处理机制和清理策略。 7 文件接口设计 7.1 文件分类和使用场景 7.1.1 文件类型 接口文件类型,一般采用按条记录格式和xml格式 l 按条记录格式:文件内容由一条条记录组成,记录之间使用回车换行进行分隔。适用于话单记录,清单记录,日志记录等。 l xml格式:文件内容符合xml格式规范,通过解析xml节点获取实际内容。适用于实时接口,业务办理接口等。 7.1.2 生成方式 根据实际情况,文件接口一般采用固定数据量,固定时间,固定业务分类等,提供单个或者批量文件进行数据传输,也可由这几种方式组合产生文件进行数据传输。 l 固定数据量:每个文件包含固定的记录,或者固定的大小,超出部分记录下一个文件。比如每个文件包含1000条话单记录等。 l 固定时间:每天在固定时间生成文件。比如接口每隔15分钟生成一个文件。 l 固定业务分类:按具体的业务种类,或者服务类型,接口名称等生成文件。比如按普通语音详单,短信清单等区分文件。 7.1.3 采集方式 客户端进行文件采集,需要有文件清单,防止文件重复采集和重复处理。对于多个客户端共同使用的文件传输接口,客户端采集以后,不可删除服务端文件,由服务端控制文件的清理。对于一对一的文件接口,客户端在采集文件以后,可直接删除服务端文件。 7.2 文件设计 7.2.1 文件命名 文件接口的文件,需要按照统一方式的命名。文件名包括个四字段,字段使用“_”分隔: l 第一字段,位长为1,填写F。 l 第二字段,建议小于20位。填写具体的业务相关信息,可自定义。 l 第三字段,位长为8,填写日期信息YYYYMMDD l 第四字段,位长大于3位,填写文件序号。对于每日文件数少于1000,的,统一3位长度,取值从000~999。日文件数大于1000的,根据实际需要设置位长。 对于长流程处理文件接口, 可使用文件名,或者目录名对文件进行区分: l 文件名:在文件名的第二字段,标识所处的流程环节,比如解码标识format,分析标识settle等。 l 目录名:将长流程中不同阶段的文件,存放在不同的目录,比如解码文件路径,分析文件路径等。 7.2.2 文件大小 文件接口建立前,需要对大小进行评估,根据实际情况划分文件: l 对于32位系统,单个文件设计必须小于1G,对于64位系统,不建议文件大于1G。 l 对于需要入库的文件,建议单个文件记录不超过1000条。 7.2.3 文件内容 文件内容至少应该包含业务记录信息,建议使用首记录和尾记录,方便对文件进行校验: l 首记录,记录文件名等相关信息,便于应用进行校验,确定文件内容正确。 l 业务记录,按照约定的格式,填写实际业务相关内容,可根据需要填写多行。 l 尾记录,业务记录填写完毕后,填写尾记录。尾记录应包含业务记录的总条数,关键业务信息比如充值金额统计等信息。 具体格式,可在接口设计时根据业务需要自行定义。 7.2.4 分隔符 XML格式文件,使用标准的XML节点进行分隔。按条记录格式的文件中,各记录字段分隔符,可根据需要自行定义,但一般建议采用以下方式进行字段分隔: l 分号:使用“;”进行分隔。字段位长根据需要设定。 l 逗号:使用“,”进行分隔。字段位长根据需要设定。 l 特殊符号:比如使用“|”,“&”等进行分隔。字段位长根据需要设定。 l 固定位长分隔:根据固定的位长进行分隔。比如前10位为编号,10-20为业务信息等。字段不足位长,约定左补或右补空格,“0”等符号,以满足格式要求。 7.2.5 基本数据格式 文件中包含的内容,必须满足基本的数据格式要求: l 数字格式 Ø 在接口文件中,数字的表示必须规范,小数点的前后必须有数字,如:0.01或34.0,不能用“.01”或“34.”表示; Ø 符号处理:数字最高位的左边第一位为符号位。对于负数,符号位为“-”,正数不用加符号位。 l 日期类型 Ø 日期类型统一采用YYYYMMDD格式,不允许出现空值,且YYYYMMDD必须为有意义的日期: a) YYYY为四位数字,必须是有效的年份 b) MM为两位数字,必须是有效的月份(01-12) c) DD为两位数字,必须是有效的日期(01-31) Ø 对于不符合日期约束规则的日期值,处理方式存在以下两种情况: a) 无值的日期或者无意义的日期,这时在接口中一律以“00010101”(公元元年1月1日)填充; b) 接口中的“失效日期”在表示“未失效”含义时,一律以“29991231”(公元2999年12月31日)填充。 l 时间类型 Ø 统一采用HHMMSS格式: a) HH为两位数字,必须是有效的小时(00-23),24小时制; b) MM为两位数字,必须是有效的分钟(00-59); c) SS为两位数字,必须是有效的秒(00-59)。 7.3 功能设计 7.3.1 业务数据检查 参考服务类接口设计 7.3.2 完整性检查 文件接口必须进行文件完整性检查,包括 l 文件传输中,在文件头或者文件尾处提供记录条数等统计信息,便于进行校验; l 对于多文件传输接口,需要有文件清单。 7.3.3 安全控制 对于包含重要业务,敏感信息的文件接口,必须进行文件加密。加密算法建议使用加密包、动态库等方式,在业务实现代码中调用,方便加密算法的变更与替换。 7.3.4 文件压缩 接口根据具体的需求应提供数据压缩/解压功能,以减轻网络传输压力,提高传输效率。 在使用数据压缩/解压功能时,应具体分析每一类业务的传输过程、处理过程、传输的网络介质、处理的主机系统和该类业务的并发量、峰值及对于所有业务的比例关系等,从而确定该类业务是否需要压缩/解压处理。对于传输文件的业务,必须压缩后传输,以减轻网络压力,提高传输速度。 在接口中所使用的压缩工具(函数)必须基于通用无损压缩技术,压缩算法的模型和编码必须符合标准且高效,压缩算法的工具函数必须是面向流的函数,并且提供校验检查功能。 7.3.5 文件处理 对于不同处理阶段的文件,需要做相应的隔离和备份: l 处理过程中的临时文件存放在临时目录,或者在文件名后追加_tmp字样进行区分。 l 正常处理完毕的文件,转存到历史备份目录。若文件已有原始的压缩备份版本,则处理完毕后可直接清除文件,防止文件占用过多的存储。 l 文件未正常处理,生成错误文件,错误文件可在原文件上加“_err”标记。话单级错误,需要在错误文件中增加错误信息,如在每条话单前或者话单后添加错误编号。错误文件存放在错误文件目录中。 7.4 日志设计 日志记录方式,日志备份方式,可参考服务类接口设计。 8 编码规则 8.1 接口编码规则 编码规则主要定义每个接口的唯一标识的生成规则,目的是对接口编码进行规范,便于查询与引用,编码共分5个部分,字段之间使用“_”分隔。如“B_RHJF_T_0_0001”、“B_ZWGL_F_1_0001”、“C_TYJC_H_2_0004”等。 接口编码规则说明: l 第1部分:域编号,位长为1。如“B”代表BOSS做为接口提供方,“C”代表CRM做为接口提供方。具体的域编号详见下表: 缩写 系统名称 B BOSS系统 C CRM系统 J 渠道接入 Q 渠道协同 S 基础能力 l 第2部分:一级接口编码,即系统编号,接口编码中唯一一个可以变长的字段,位长3~5位。如“RHJF”为融合计费子系统,“ZWGL”为帐务管理子系统,“TYJC”为统一接触子系统。具体的系统编号详见下表: 序号 域名称 域编号 系统清单 编号 1 渠道接入 J 特约商户 TYSH 2 渠道接入 J 营业厅现场管理 XCGL 3 渠道接入 J 营业厅电子签章 DZQZ 4 渠道接入 J 营业厅客户互动 KHHD 5 渠道接入 J 营业厅多媒体播控 DMTBK 6 渠道接入 J ESOP ESOP 7 渠道接入 J 自助终端 ZZZD 8 渠道接入 J 掌上营业厅 ZSYYT 9 渠道接入 J 门户网站 MHWZ 10 渠道接入 J 网上营业厅 WSYYT 11 渠道接入 J 电子商务 DZSW 12 渠道接入 J 集团客户自助门户 JTKH 13 渠道接入 J 渠道网厅 QDWT 14 渠道接入 J 短信营业厅 DXYYT 15 渠道接入 J 客服接入(10086) KFJR 16 渠道接入 J 客服业务 KFYW 17 渠道接入 J 12580综合信息服务 ZHXX 18 渠道接入 J 集中外呼 JZWH 19 渠道接入 J 电话经理(10088) DHJL 20 渠道接入 J 省内语音充值平台 YYCZ 21 渠道接入 J 统一短信管理平台 TYDX 22 渠道接入 J 语音催缴 YYCJ 23 渠道控制与协同 Q 渠道控制与协同 QDXT 24 CRM C 融合CRM RHCRM 25 CRM C 营销管理 YXGL 26 CRM C 有价卡管理 YJKGL 27 CRM C 终端管理 ZDGL 28 CRM C 统一营销资源管理 TYYX 29 CRM C 远程写卡 YCXK 30 CRM C 统一接触 TYJC 31 CRM C 统一产品管理 TYCP 32 CRM C PBOSS PBOSS 33 CRM C 统一开通 TYKT 34 BOSS B 账务管理 ZWGL 35 BOSS B 账详单查询 ZXDCX 36 BOSS B 综合采集 ZHCJ 37 BOSS B 融合计费 RHJF 38 BOSS B 欠费风险控制 QFFX 39 BOSS B 实时账务 SSZW 40 BOSS B 综合结算 ZHJS 41 BOSS B 社会渠道管理 SHQD 42 BOSS B 集团SA管理 JTSA 43 基础能力 S 服务请求 FWQQ 44 基础能力 S 知识库 ZSK 45 基础能力 S 质检 ZHIJ 46 基础能力 S 培训考试 PXKS 47 基础能力 S 信息公告 XXGG 48 基础能力 S 任务管理 RWGL 49 基础能力 S 统一日志管理 TYRZ 50 基础能力 S 统一认证和权限 TYQX 51 基础能力 S 生产报表 SCBB 52 基础能力 S 软电话 RDH l 第3部分:接口方式缩写,位长为1。具体的接口方式缩写详见下表: 缩写 接口方式 描述 F FILE 文件接口 T TABLE 表接口 A ATMI ATMI接口 S SCOKET SCOKET接口 H HTTP HTTP接口 W WS WEBSERVICE接口 E EJB EJB接口 R RMI RMI接口 M MQ 消息队列 l 第4部分:业务分类编号,位长为1。具体的业务分类编号详见下表: 编号 说明 描述 1 查询类 2 受理类 3 验证类 4 数据流转类 0 其他 l 第5部分:具体接口编码,位长为4。取值从“0001”到“9999”之间的阿拉伯数字,为顺序流水号,如:“0001”代表详单查询接口, “0012”代表退费交易接口。此类编号可由各子系统和接口开发人员自行定义。

下载文档到电脑,查找使用更方便

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 8 金币 [ 分享文档获得金币 ] 2 人已下载

下载文档