XX市XX应用软件开发技术规范.docx

1、XX市XX应用软件开发技术规范1 应用软件技术规范一、 实施技术规范的目的与适用范围通过实施应用软件技术规范使苏州交通系统各类新建和已建的应用软件能够有效地实现资源共享和数据交换，为应用软件可持续、可扩展的开发建设奠定基础，为今后的应用整合做好准备。本规范适用范围：2010年后新建的应用软件必须实现本规范定义的技术要求，2009年底以前建成的应用软件在今后的升级改造中要实现本规范定义的技术要求，目前在建的软件系统要有条件的实现本规范定义的技术要求。二、 实施技术规范的目标本规范实施之后开发的应用软件必须能够实现本方案定义的系统接口、编制本方案规定的数据规范和应用本方案提出的组织结构管理要求。通

2、过实现统一的接口技术规范，使所有应用软件可以实施统一的管理，使应用软件之间可以进行数据交互；通过使用特定的XML格式设计的数据规范，使应用软件能够开放数据资源，做到数据内容、服务方式和实现技术的无关性，增强了应用软件开发和组合的灵活性；通过应用统一的组织结构管理要求执行身份验证和角色分配操作，降低了应用软件建设的复杂性，简化了用户身份的管理工作。通过实现数据流转功能实现不同应用软件之间的数据共享，实现办事信息通知的发送。三、 接口技术规范所有应用软件在底层都可以细分为对数据的增加、删除、修改和查询四项操作，为此对应用软件制定了统一的接口技术规范，明确了写入、读取和查询三项操作。1. 接口的功能

3、说明通过调用写入操作让应用软件执行元数据的增加、删除和修改操作。元数据是指应用软件中的最基本数据，如果一个数据被拆开后在整个应用软件中不再具备其他意义，那么这个数据就叫做元数据。元数据以外的其他数据是不会调用写入操作的。通过调用读取操作获取应用软件中的具体数据。读取操作可以获取元数据或具有固定数据标识和类型的单项数据。通过调用查询操作检索应用软件中的相关数据。查询操作可以包含大量的查询条件，应用软件将系统中符合条件的数据检索出来后返回给调用方。2. 接口的参数和返回值说明写入操作主要参数有：用户标识、应用标识、数据标识、数据类型、符合数据规范格式的XML数据。参数含义如下：用户标识用UserI

4、D表示，使用应用软件接口时首先提供身份验证信息，通过认证后将获取用户标识，在以后的访问中使用UserID表示访问接口的用户身份，结束接口使用必须执行用户标识注销操作。用户标识获取和注销操作参见第五节“身份认证和管理规范”。应用标识用TaskGuid表示，随着系统整合的实施今后一个应用软件可以包含多项专业应用，通过TaskGuid参数值可以让接口在被调用时能够区分出不同的应用。TaskGuid采用标准的GUID格式，TaskGuid的值由系统建设主管单位统一定义，在数据规范文档中描述，一项应用只能定义一个应用标识。数据标识用DataGuid表示。每个唯一的数据必须具备一个唯一的标识，使用该标识区

5、分不同的数据。由于数据的增加、删除和修改操作都是以DataGuid作为关键字的，不同的系统都要按照GUID标准统一生成DataGuid，以保证数据在不同的系统和平台中不被其他数据覆盖。数据类型用DataType表示。每一项数据规范都要定义一个唯一的数据类型，应用软件是按照DataType对应的数据规范解析写入的数据，不同应用的数据类型可以重复。符合数据规范格式的XML数据用XmlData表示。表示写入的具体数据，如果与数据类型对应的数据标识的元数据不存在，就执行数据增加操作；如果与数据类型对应的数据标识的元数据已存在，就执行数据更新操作；如果XmlData是空值或是没有子节点的XML数据，就将

6、数据标识对应的元数据删除； 写入操作的返回结果表示数据在软件中的写入情况。返回0表示数据写入操作成功，返回-1表示数据格式不符合要求，返回-2表示写入数据的逻辑不对，表示返回-3表示没有数据写入权限，返回其它值可以查询“数据写入操作错误信息”来获取具体含义，查询时使用读取操作，其中TaskGuid参数为应用标识，DataGuid参数固定为c61ed474-e8b1-4fb4-8975-74b356caa22b，DataType参数为“ErrorList。返回数据格式统一为： 错误信息描述 错误信息描述 错误信息描述 错误代码要求大于100或小于负100，正负100之间的错误码作为保留值不能使用

7、。读取操作主要参数有：用户标识、应用标识、数据标识和数据类型。参数含义如下：用户标识用UserID表示，具体含义与写入操作参数相同。应用标识用TaskGuid表示，具体含义与写入操作参数相同。数据标识用DataGuid表示，每个唯一的数据必须具备一个唯一的标识，使用该标识区分不同的数据。读取操作中数据标识表示需要读取的唯一数据。数据类型用DataType表示。每一项数据规范都要定义一个唯一的数据类型，应用软件是按照DataType对应的数据规范生成读取的数据，不同应用的数据类型可以重复。读取操作的返回结果是符合数据规范格式的XML数据。如果对应的数据不存在也必须返回符合数据规范格式并包含所有节

8、点的空数据。返回空值表示无对应数据的读取权限或者是应用软件不支持该类型的数据。查询操作主要参数有：用户标识、应用标识、符合数据规范格式的XML查询命令。参数含义如下：用户标识用UserID表示，具体含义与写入操作参数相同。应用标识用TaskGuid表示，具体含义与写入操作参数相同。符合数据规范格式的XML查询命令用XmlTransform表示。在查询操作中包含需要查询的条件。查询操作的返回结果是符合查询条件的具体数据。大批量数据的返回要实现数据分页的查询操作。即使查询结果没有符合条件的数据也必须返回符合格式的数据，返回空值表示无对应数据的查询权限或者是应用软件不支持对应的查询操作。3. 接口的

9、实现方式考虑到不同层面的对接要求系统接口的实现定义了网页、Web服务和Socket三种方式，应用软件至少需要实现其中一种接口方式，具体实现哪几种接口方式，将由建设单位明确。 网页方式。该方式是专供JaveScript调用的一种方式，使用浏览器的XMLHttpRequest对象向对应的网页发出请求或发送数据可以调用应用软件的写入、读取和查询操作。写入操作使用 “POST”方式将符合数据规范格式的XML字符串发送到提供写入操作的网页上。用户标识、应用标识、数据标识、数据类型等参数通过在网页后面跟上字符串：?UserID=&TaskGuid=&DataGuid=&DataType=的方式传递，返回值

10、为数值型的字符串。读取操作使用“GET”方法调用提供读取操作的网页。用户标识、应用标识、数据标识和数据类型，等参数通过在网页后面跟上字符串：? UserID=&TaskGuid=&DataGuid=&DataType=的方式传递，返回值为符合数据规范格式的XML字符串。查询操作使用“POST”方式将符合数据规范格式的XML查询命令发送到提供查询操作的网页上。用户标识、应用标识等参数通过在网页后面跟上字符串：?UserID=&TaskGuid=的方式传递，返回值为符合数据规范格式的查询结果字符串。提供写入、读取和查询操作的网页可以通过一个网页文件来完成对应的功能。 Web服务方式。该方式是提供给

11、函数方式调用的一种接口，凡是能够支持Web服务调用的软件都可以使用这种接口调用应用软件的写入、读取和查询操作。Web服务必须遵循附件一的WSDL定义，实现下面三个函数： 写入操作调用Web服务的SetData函数，参数按照函数的方式传递，返回值为数值型。函数原型如下：SetData ( UserID As string , TaskGuid As string , DataGuid As string , DataType As string , XmlData As string ) As int 读取操作调用Web服务的GetData函数，参数按照函数的方式传递，返回值为符合数据规范格式的

12、XML字符串。函数原型如下：GetData ( UserID As string , TaskGuid As string , DataGuid As string , DataType As string ) As string 查询操作调用Web服务的TransformData函数，参数按照函数的方式传递，返回值为符合数据规范格式的查询结果字符串。函数原型如下：TransformData ( UserID As string , TaskGuid As string , XmlTransform As string ) As string Socket方式。该方式是采用通讯端口方式进行操作

13、的接口。通过向通讯端口发送指定格式的数据实现对应用软件的写入、读取和查询操作。 写入操作发送如下格式的数据到通讯端口： 用户标识 应用标识 数据标识 数据类型 /符合数据规范格式的XML数据 返回值是数值型的字符串。 读取操作发送如下格式的数据到通讯端口： 用户标识 应用标识 数据标识 数据类型 返回值是符合数据规范格式的字符串。 查询操作发送如下格式的数据到通讯端口： 用户标识 应用标识 /符合数据规范格式的XML查询命令 返回值是符合数据规范格式的查询结果字符串。4. 批量数据处理由于系统接口采用XML作为传输数据的格式，在实际应用中发现传输数据的时间要比处理数据的时间大很多，在大数据交互

14、应用中如果每个写入、读取和查询操作只写入或反馈一个数据将会大大影响系统效率，为此定义了批量数据处理方式来满足大数据量应用的要求。批量数据以Documents作为根节点，内含一组符合数据规范的Document子节点。数据格式如下： 写入操作中使用批量数据表示对数据中的每个Document都执行一次独立的写入操作，写入每个Document时使用其包含的应用标识、数据标识和数据类型代替TaskGuid、DataGuid和DataType参数，批量写入操作中提供的这三个参数忽略。读取和查询操作中使用批量数据可以根据实际逻辑定义批量数据反馈格式。四、 数据格式规范要想让同一种数据在不同的软件接口中使用，

15、必须让数据遵循共同的描述方式，为了让数据通俗易懂便于计算机处理和人理解特采用XML格式作为所有数据的标准格式，按照特定的XML格式定义的数据描述称做数据规范。采用数据规范后应用软件的功能实现就具备一定的灵活性数据规范在应用软件接口中涉及写入和读取操作中的“XML数据”，查询操作中的“XML查询命令”和“XML查询结果”。大型应用软件的数据规范聘请专业单位进行独立设计，小型应用软件的数据规范由软件开发单位负责设计。1. 数据规范的基本结构基本的数据规范必须符合下面的基本格式： 属性值 根节点命名为Document表示这是一个按本文数据规范定义的数据。应用标识表示数据规范与哪一个应用有关。在某项应

16、用的数据规范设计中必须首先明确应用标识采用的值。例如：0690f841-7773-445c-9f48-a7a0427686d5就表示是组织结构管理功能的数据。一个应用软件可以包含多个应用，不同应用具备独立的应用标识，可以独立开发。数据标识表示数据的唯一值，对于元数据应用软件就是依靠该值执行增加、删除和修改操作。在数据规范设计中该值不要明确具体的内容，在实际数据生成时必需按照GUID的标准生成具体值，这样可以保证不同的系统生成的数据不会重复。数据类型表示数据对应哪一个类型，一个应用可以包含多个数据类型，相同类型的数据必须遵守相同的格式。调用系统接口的软件和系统接口实现的软件都依靠数据类型来确定数

17、据的分析和生成方法。文档根节点还可以叠加与整个文档有关的其他属性，具体可以根据不同的设计方案扩展。属性节点表示数据属性，一个数据有多少个属性就列多少个属性节点。属性节点名称可以重复，名称相同的属性值可以存在次序关系，不同属性名称的节点不存在先后次序关系。类型表示属性节点的具体类型。类型及其表示方式将在第2节中详细介绍。属性值表示属性节点的具体内容。属性节点还可以叠加与属性相关的其他内容，具体可以根据不同的设计方案扩展。2. 数据类型描述 标准数据类型及其格式。标准数据类型共定义八种，主要有：LOGICAL、LONG、DOUBLE、CURRENCY、DATE、BINARY、TEXT、GUID。它

18、们的含义、取值范围、格式和默认值如下：LOGICAL 逻辑型，值为：true或false，不能为空且必须为小写，默认值false。LONG 整数型，数据位数在设计时不限长度，不能为空，默认值0。DOUBLE 小数型，数据位数和小数位数在设计时不限长度，不能为空，默认值0.0。CURRENCY 货币型，仅含两位小数的数据，不能为空，默认值0.00。DATE 日期型，格式为“YYYY-MM-DD HH:MM:SS”，默认值为空。BINARY 二进制型，二进制数据的BASE64编码，默认值为空。TEXT 文本型，长度不限，默认值为空。GUID 数据标识型，格式“7adab85a-e2cd-4a17-

19、a23b-4044b0d72560”小写格式，每一位必须是0-9，a-f十六个字符之一，按照标准GUID算法生成的内容。 扩展数据类型及其格式。扩展数据类型在本文中先定义四种，今后将根据情况进行补充，主要有：文件数据、附件数据、枚举数据和组织结构数据。 文件数据。文件数据以二进制的方式读入内存后转换成BASE64的字符串写入文档中。文件数据包含文件名，扩展名，MIME信息等属性。数据格式例子：二进制的BASE64编码 附件数据。用于描述一组文件数据，由于涉及多个文件数据，附件数据由两级节点组成。数据格式例子：文件数据的二进制的BASE64编码文件数据的二进制的BASE64编码 枚举数据。用于描

20、述一组字符串，实际数据只能是这组字符串数据中的一个。数据格式例子：枚举值一|枚举值二|枚举值三| 组织单元数据。用于描述单个组织单元信息。组织单元数据包括：标识、名称、类型、所属单位标识等信息。数据格式例子：其中类型定义了Company（单位）、Branch（部门）、Member（人员）、Group（群组）、Application（应用软件）等五种。 组织单元列表数据。用于描述一组组织单元信息。数据格式例子： 3. 常用数据规范设计原则在这里列举了一些常用数据规范的设计方式，一般情况下需要遵循这些方式设计数据规范。 元数据的规范设计。元数据是指信息系统中的最基本数据，如果一个数据被拆开后在整个

21、信息系统中不再具备其他意义，那么这个数据就叫做元数据。在系统完成功能设计后就可以初步分析出系统建设需要的各类元数据，系统开发和系统试运行过程中元数据可能会存在一些变化，系统投入正式运行前元数据基本可以固定下来。元数据以Document为根节点的，元数据包含的子节点就是具体的数据属性，如果属性过多（20个以上）并且可以进一步分类那么可以多设计一层子节点，但是一般不要超过三层节点。下面是组织结构管理模块中的人员数据定义： 人员标识 人员名称 部门标识 联系电话 移动电话 移动电话 电子邮件 账户名称 口令 序号 账户锁定状态应用标识统一为：0690f841-7773-445c-9f48-a7a04

22、27686d5，人员标识由生成人员数据的模块按标准GUID算法生成，数据类型为：Member，数据属性中的Guid和DataGuid取同一个值，适度的属性冗余可以用来验证数据完整性。其他数据属性是描述人员信息需要提供的附加内容。从这个例子可以看出，任何一个属性独立出来后在组织结构管理功能中都不在具备其它意义，因此人员数据可以认为是元数据。元数据中的属性可以引用其它元数据，但是不能包含其它元数据，如果包含其它元数据那么它本身就不是元数据。元数据可以包含状态属性，状态属性在设计文档中可以定义多种状态，但是在元数据的实例中状态属性只有一个值。元数据中相同名称的属性如果存在多个那么对应的属性值是有先后

23、次序的，不同名称的属性是不存在先后次序的，下面两个数据规范可以认为是同一个规范。 人员标识 人员名称 部门标识 联系电话 移动电话 移动电话 电子邮件 账户名称 口令 序号 账户锁定状态规范一 人员标识 人员名称 电子邮件 账户名称 口令 序号 账户锁定状态 部门标识 联系电话 移动电话 移动电话规范二元数据的实例可以包含元数据定义的节点以外的其他数据节点，只要数据规范定义的节点数据都存在依旧可以认为是一个符合元数据规范的实例数据。元数据主要用于写入和读取操作，执行写入操作时应用标识、数据标识和数据类型在参数和数据中要同时出现并且值要相同，应用软件负责符合性检查，如果值不相同应用软件可以不执行写入操作。读取操作时返回的元数据包含应用标识、数据标识和数据类型与读取参数要相同。数据标识和类型相同的元数据表示同一个元数据，写入操作执行时老的数据会被覆盖。 数据集合的规范设计数