完整的接口解决方案说明书Word文件下载.docx
《完整的接口解决方案说明书Word文件下载.docx》由会员分享，可在线阅读，更多相关《完整的接口解决方案说明书Word文件下载.docx（61页珍藏版）》请在冰豆网上搜索。
内容
1引言
1.1编写目的
本文档为XX电信工程外部协作系统（以下简称外协系统）与电信工程施工单位内部系统（以下简称施工系统）接口技术解决方案，以此作为外协系统与施工系统实施接口的技术方案依据和项目设计标准。
1.2覆盖范围
XX电信工程外部协作系统项目组
施工系统接口开发技术组
1.3预期读者与阅读建议
XX电信企业信息化部
XX电信工程建设部
XXXX公司开发人员
施工系统开发人员
1.4文档约定
粗体正文表示强调内容
红色正文表示未完成或需要今后考虑的内容
蓝色正文表示待讨论内容
1.5术语与缩略语
术语、缩略语
定义
外协系统
XX电信工程外部协作系统
施工系统
电信工程施工单位内部系统
PECS
XX电信工程外部协作系统英文简称
1.6参考文献
（XXXX）
2概述
建设XX电信工程外部协作系统的目标，是在工程项目的管理、建设、使用和实施单位之间搭建起数据交换和协同工作的信息平台，延伸与拓展工程建设管理信息化的应用范围，实现通信工程建设过程的信息化管理，促进工程项目的管理部门、建设部门、实施部门和使用部门之间业务流程协调有序地开展，实现工程项目设计、施工、监理管理功能，将相关的设计、施工、监理单位纳入到工程建设管理中，完善工程项目建设过程管理体系，通过信息化推动管理的规范化，在信息化的应用过程中不断探索市场环境下工程建设管理的新思路和新方法。
根据工程部业务工作的实际情况，项目首先满足工程建设管理中应用最广泛、问题最突出的基本需求。
项目功能需求包括：
Ø
建立工程外部协作系统与MSS等系统的接口；
建立设计协作服务、监理协作服务、施工协作服务模块，为邮电设计院、电话监理公司和电信工程公司提供工程部所需的协作服务，保证工程建设实施流程的开展；
在建立工程协作服务模块的基础上，建立工程外部协作系统与邮电设计院、电话监理公司、电信工程公司信息系统的接口，实现工程部与三家实施单位的信息交互与业务协作；
本技术解决方案就是针对实现工程建设部与三家实施单位信息交互与业务协作接口中施工单位接口的技术解决方案的组成部分。
在接口的调用过程中，存在施工系统调用外协系统接口的情况，这时候，施工系统作为客户端，外协系统作为服务端；
也存在外协系统调用施工系统的情况，这时候，外协系统作为客户端，施工系统作为服务端。
本方案中，除了特殊另外说明外，不考虑外协系统和施工系统角色换位的问题。
如果一方发起了调用，那么它就是客户端，另一方就是服务端。
反之亦然。
4接口方式
◆工程外协系统与施工系统之间的接口采用WebService接口形式来进行业务数据的交互。
◆接口数据传输采用XML数据交换格式，utf-8编码。
◆在外协系统中提供WebService的API接口。
提供由施工系统调用获得信息；
并且提供施工系统提交信息的API接口。
◆同样，在施工系统中提供WebService的API接口。
提供由外协系统提交信息的API接口。
◆考虑到工程外协中的数据信息不仅包括了XX电信工程公司的数据而且还包含了其他的施工单位的数据信息。
而这些单位也各有其各自工程应用系统。
这样，外协系统对各个施工单位系统所提供的接口API及其参数信息、格式均是统一的。
同时，也要求各个施工单位所提供的接口API及其参数、格式等也必须要求统一。
外协系统与施工系统属于一对多的关系。
◆外协系统要求能够有目的，信息有过滤的把业务信息通过接口正确的发送给相应施工系统接口。
非相关的信息不要发送给对应的施工系统。
◆施工系统建立用户映像对照表、字典对照表、单位对照表等数据映像，传递给外协的数据使用的是映像中转换后的外协系统能够识别数据；
同时，接收到的数据也根据对照表转换成各自能够解释的数据格式。
◆数据初始化的时候，由施工系统主动调用外协系统的接口，以获得用户信息、字典信息、单位信息、项目信息等基础信息。
以后，一旦发生数据的变动，由外协系统主动往施工系统发送信息。
◆外协系统不主动请求施工系统获得数据，但是外协系统会主动请求施工系统发送数据。
◆施工系统主动请求外协系统获得数据，也会主动请求外协系统发送数据。
4接口安全
4.1接口认证
调用认证：
虽然接口双方都是存在于电信内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。
所以，从接口调用上，必须考虑调用的认证安全问题。
◆本方案中的接口，在客户端调用服务端的时候，必须经过调用身份认证。
考虑施工系统的开发平台的多样性，但同时接口服务运行平台都是Windows的情况，本方案采用Windows安全身份认证的方式。
即在访问接口所在的服务的时候，都必须进行资格审查（使用Credentials发送认证信息）。
◆另外，接口采用SOAP协议，因此在接口配置上面需要屏蔽HTTPGET和HTTPPOST等其他协议。
◆在接口中审核并进行日志的记录。
◆使用最低权限的进程帐户运行Web服务（通过Machine.config中的<
processModel>
元素来配置）。
◆接口不支持动态生成WSDL,因此作为服务端，应该禁止文档协议。
◆在服务端禁用跟踪，禁用调式编译
业务用户认证：
由于接口涉及电信工程中的各个不同的业务，有获取字典、获得项目信息、发送开工报告等，所以，建立一套业务的用户认证机制是必须的。
不同的用户，所具备有的授权不一样，所能执行的业务也不一样。
同时，业务用户认证中的用户信息也是记录接口日志中的重要组成部分。
本方案采用的是在接口信息中包含业务认证用户信息的方式来进行认证。
服务端在收到请求的时候，应先验证业务的授权用户，如果该业务用户没有执行当前业务的权限，应终止业务的执行，并给出非法用户的警告信息反馈回客户端。
一般情况下，业务认证的用户是系统中的用户。
业务认证其实就是应用系统认证的组成部分。
业务认证的用户信息经过加密之后包含在要发送的信息（XML体）中，即在发送的信息中包含业务用户的信息（参见下面的数据格式说明）。
4.2数据安全
数据的安全表现为如何保证数据在网络传输过程中不会被截获并被解析其中的内容而引起信息泄露与如何保证数据在传输的过程中的数据的完整性两个方面。
WebService采用XML数据格式来传输信息。
所以，无论是发送数据还是返回结果，都要求采用对XML数据加密之后来传输。
至于采用何种方式的加密技术，本方案为了保密，只能在开发的时候由开发人员口头告知。
涉及到加密技术就要涉及到加密的密钥问题。
目前，外协系统和施工系统接口上有很多种类型的业务，到底是每种类型的业务采用不同的密钥，还是按分组来采用同一种密钥的方式，还是所有的业务全部采用同一种的密钥的方式，按照需求各有不同的选择。
本方案采用的是最后一种的方式。
密钥的发布由作为服务方来发布，由客户端获取。
密钥的发布方式待定。
为了保证数据的完整性，首先：
方案采用数据签名（SOAPSecurityExtensions:
DigitalSignature）。
利用XML的数字签名（XMLDigitalSignaturesyntax[XML-Signature]）对SOAP进行扩展，在SOAP的头元素中定义签名属性（<
SOAP-SEC:
Signature>
）来实现。
其次：
限制并验证Web方法输入的类型、长度、格式和范围，验证对XML输入数据的验证是基于已协商的架构等。
5事务处理
事务是一组相关的任务，作为独立于其他任务的独立单元成功（提交）或失败（中止）。
分布式事务是影响多个资源的事务。
要提交分布式事务，所有参与者都必须保证对数据的任何更改是永久的。
不论系统崩溃或是发生其他无法预料的事件，更改都必须是持久的。
即使只有一个参与者无法保证这一点，整个事务也将失败，在事务范围内对数据的任何更改均将回滚。
外协系统和施工系统是处于网络之上的两个分布式接口，使用的是分布式事务。
要启用分布式事务，可能需要通过网络启用MSDTC（考虑外协平台和施工平台都是运行在Windows上），以便在使用应用了最新的ServicePack的较新操作系统（例如WindowsXP或Windows2003）时使用分布式事务。
如果启用了Windows防火墙（WindowsXPServicePack2的默认设置），必须允许MSDTC服务使用网络或打开MSDTC端口。
接口中的服务端和客户端的环境事务始终相同，客户端创建的事务上下文并应用对于服务端的当前的事务，以便对于该事务上下文是当前的。
这样的事务会造成性能损失，因为可能需要继承原来的上下文，但是，这样的事务确保了在数据库操作的时候信息的完整性。
接口中事务的发起总是由客户端发起的，并负责事务的提交和回滚等控制。
6性能考虑
在接口设计的时候就应该考虑性能上面的问题，不要在事后再加入性能。
同时，在项目的开发过程要反复进行测试，可以从机器的吞吐量和响应时间两个基本的指标来衡量接口的性能。
接口上面的性能考虑主要从下面几个方面来优化：
◆使用一次连接，多次调用，优化连接资源。
◆对于并行的接口调用使用异步的调用方式。
◆优化线程池减少竞争。
◆考虑使用XML压缩。
◆如果不需要返回，考虑使用单工通讯的方式。
◆适当的设置（如果有代理）代理超时，页面超时，WebService超时。
◆设计"
大块头"
的接口减少往返。
◆基于消息的编程而不是远程过程调用（RPC）。
◆使用XML字串作为参数。
◆尽量使用原始数据类型参数。
◆避免在调用之间维护服务器状态。
◆考虑为复杂的WebMethod提供输入校验。
◆考虑对WebMethod的结果使用缓存。
◆选择适用的大数据包传送方式。
◆避免调用本地的WebService。
7容错处理
客户端向服务端发送数据，服务端解析数据，反馈信息给客户端，这中间的环节只要某一个环节出现问题，都会造成接口的失败。
按照失败产生的环节分类，我们可以从三个方面来处理接口的失败。
◆网络连接失败：
在调用接口的时候，由于网络不通，造成数据不能正常传输。
这样，客户端应该能够记录发送的日志，按照一定的时间间隔重试发送。
本方案定为重试发送20次，每次时间间隔2小时。
如果一直发生网络不通的情况，该发送日志被保存下来，待后手工发送。
所以，客户端系统应该实现手工发送数据的功能。
◆反馈错误信息：
服务端在解析数据包，执行数据包业务的时候，可能会发生异常。
所以，服务端应当能够捕捉异常信息，比如“非法XML格式”等，然后反馈给客户端。
客户端在接受到这类的错误信息之后，应当进行日志记录，能够自动或手工分析异常的信息。
◆网络连接正常，但是无信息反馈：
这种情况下，一般是服务端出现了异常，但是又没有捕捉到的情况下发生。
这种情况下，客户端把这种错误当作“网络连接失败”来处理。
服务端应能够实现相同数据包重新发送过来的处理机制。
8数据格式
在WebService的调用过程中，无论是外协系统还是施工系统，都有发送数据和接收数据的要求，也即双方系统同时作为客户端又作为服务端。
我们统称这些传递的数据为报文。
客户端发送报文，属于调用；
服务端接收报文，属于被调用。
客户端和服务端互相之间通讯的请求报文和结果报文遵循XML格式。
客户端发送请求报文，服务器解析调用报文，执行报文中所在接口对应的服务功能。
生成结果报文，以xml格式页返回给请求者。
请求者拿到结果报文，进行解析，然后再进行相应的处理。
8.1约定
◆报文中所有的字典信息（比如性别1-男，2-女），都以代码的值（1或者2）来传递。
施工单位向外协系统发送的报文中的代码都需要转换成外协的代码，外协系统向施工系统发送的报文中的代码无需转换。
◆报文中的其他数据类型，比如货币、RowID,自定义对象类型等，根据需要转换成文本、数值或二进制（最终转换成Base64字符）的数据类型。
◆报文中数值信息，转换成文本，如：
<
ItemCount>
50<
/ItemCount>
ValueSum>
12368.36<
/ValueSum>
◆报文中数值不支持科学计数的方式。
报文中数值的单位使用国标的单位，比如货币使用“元”，长度使用“米”等。
无国标的单位以约定为准。
◆报文中的日期信息，转换成YYYYMMDDHHmmss文本格式（24小时制）。
如果是空日期，则转换成空文本。
◆报文中的true和false数据类型，转换成0（表示false）、1（表示true）
◆报文中的二进制数据，转换成Base64字符方式发送。
◆报文中的记录集，放在<
Records>
标签中；
报文中一条记录，放在<
标签中。
◆报文中如果存在多条记录，则在<
Records>
标签中就包含多个的<
Record>
标签。
如果报文中仅有一条记录，则<
标签中只包含一个<
标签.如果没有记录，则仅仅包含一个<
标签,没有<
◆如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用分页返回数据集的方式分批返回数据（每次返回最多100条记录）。
服务端提供分批结果返回的功能。
至于如何使用分页查询的功能，参见下面的XML框架说明。
8.2施工系统向外协系统发送请求
施工系统向外协系统发送请求的数据目前有几点需要考虑：
◆如何请求查询一个业务数据
◆如何新增一条记录，新增之后如何点到记录的键值
◆如何修改一条记录
◆如何删除一条记录
◆文档如何上传
◆一条记录中一个FileID的字段如何上传多个文件
◆如何在一条记录中补充上传文档
◆如何在一条记录中删除一个文档
◆如何获得文档的基本信息
◆如何获得文档的所有兄弟信息
◆如何获得文档的所有父亲信息
◆如何下载一个文档
针对这些问题，接口方案的解决方法如下：
8.2.1请求查询一个业务数据
施工系统针对外协系统发送的业务数据查询请求根据业务类型有很多种。
为了简化接口，而不是在接口上进行业务操作，所以，外协系统将施工系统发起的数据查询请求看作是数据下载的一种方式，而不为了复杂的业务查询请求提供复杂的条件解析。
外协系统提供的数据查询接口是从数据下载和数据延期性来考虑的。
为了满足数据的下载，外协系统提供了按照某一个表的主键来下载数据和按照记录的变更时间范围来下载数据的两种方式查询请求。
请求报文：
?
xmlversion="
1.0"
encoding="
utf-8"
?
>
XmlData>
UserInfo>
<
User>
ZhangSan<
/User>
PassWord>
123456<
/PassWord>
/UserInfo>
Description>
RowID>
0<
/RowID>
KeyValue>
123<
/KeyValue>
QueryBeginTime>
20061018153000<
/QueryBeginTime>
QueryEndTime>
20061019153000<
/QueryEndTime>
/Description>
/XmlData>
响应报文：
100<
Field1>
Value1<
/Field1>
Field2>
Value2<
/Field2>
Field3>
Value3<
/Field3>
Field4>
Value4<
/Field4>
/Record>
/Records>
报文说明：
标签名
说明
报文数据主体
报文头部信息
记录集合
一行记录
业务认证的用户信息
业务用户登录名
业务用户验证口令
第一次请求的时候，客户端RowID发送0，表示从第0条记录开发返回。
服务端根据条件查询，发现结果超过100条记录，则在返回的结果中，RowID的值为99，表示服务端当前的记录位置处在第100条的位置上，后面还会有剩余的记录。
客户端检查返回的结果，如果发现RowID大于0,则继续发送请求进行查询。
但是，客户端第二次发送请求继续查询的时候，RowID的值要赋值为第一次返回的值，即RowID=99。
服务端第二次收到请求的时候，发现RowID是99,则从第100条返回结果。
以此类推循环调用，直到服务端达到记录的末尾，这时候，服务端在返回的结果中RowID=0.客户端发现服务端RowID=0，终止循环调用。
字典、用户信息、单位信息，因为返回的字段比较少，不受100条记录返回的限制。
一次调用，就返回全部的结果。
查询时主键的值。
这个<
和下面的<
是互斥的。
如果在请求的时候提供了主键的值，表示客户端要求服务器按照主键的值查询一条记录。
如果客户端提供了主键的值，则服务端将忽略<
中的值。
字典、用户信息、单位信息，因为没有查询时间范围，所以<
即表示字典类型。
查询时时间段范围。
是起始时间，<
是结束时间。
表示客户端要求服务端查询在这个时间范围之内所有变更过的记录（包括新增、修改、删除）。
在外协中，一条记录新增的时候，它的创建时间和最后修改时间是一样的，以后修改记录的时候，创建时间不变，改变的仅仅是最后修改时间。
同时，外协系统中删除记录仅仅在“记录是否删除”字段中标记“1”，并不是真正的物理删除记录。
这里的时间指的是记录变更的时间，不是记录中的某个业务时间。
如果用户需要按照业务时间来查询数据，则施工系统把外协系统的数据获取到本地进行保存，在施工系统中提供按照业务时间查询的功能。
和<
如果客户端需要按照时间范围来查询，则必须<
空。
一行记录中的英文字段名称。
实际中，这些标签都是字典的英文名。
字段的标签全部是大写。
具体的字段名称请参见提供的数据模型
8.2.1新增一条记录，得到记录的键值
为了简化数据模型的处理，本方案不考虑主从表的并发处理情况。
如果存在主从表的数据需要上传，那么，在一个事务中，施工单位首先先上传主表的记录，从反馈信息中获得主表的主键值。
然后，把刚刚获得的主表的主键值赋值给从表的对应外键，再上传从表数据，得到从表的主键值。
如果不是主从表，而是单表，则直接上传数据，从反馈信息中得到主键值。
这种情况的优点是：
数据和表相关，施工单位可以灵活的控制表之间的关系；
同时，数据包中的报文比较简单，容易解析；
接口上面比较清晰，与业务的耦合比较低。
缺点是：
一个业务涉及的主从表不能在同一个报文中（这个缺点可以通过施工系统灵活的控制表之间关系来解决）；
一个业务中可能会使用到两个或两个以上的接口，造成业务完整性上面的分离（这种缺点可以通过把业务放在一个事务中来解决）；
键值的返回：
在调用新增接口之后，外协会按照记录的顺序返回外外协中所生成的键值。
施工单位获得键值之后，可以在本地表中更新记录的主键值。
Note>
开工报告<
/Note>
KeyField>
/KeyField>
NormalField1>
/NormalField1>
NormalField2>
/NormalField2>
NormalField3>
/NormalField3>
NormalField4>
/NormalField4>
encoding
升级会员 