数据接口标准规范

1　范围
接口规范定义了与其他系统进行数据交换的数据规范和报文规范。
2　规范性引用文件
下列文件中的条款通过本标准的引用而成为本部分的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本部分，然而，鼓励根据本部分达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本部分。
GB/T 1.1 标准化工作导则 第1 部分：标准的结构和编写
GB/T 35778—2017 企业标准化工作 指南
GB/T 5271.8-2001 信息技术 词汇 第8部分：安全
GB/T 18811-2002 电子商务基本术语
DL/T 485—2018 电力企业标准体系表编制导则
DL/T 800—2018 电力企业标准编写导则
DL/T 1004 电力企业管理体系整合导则
3　接口服务描述规范
3.1　概述
接口服务描述是业务服务的集中描述，包含其提供的功能以及如何进行调用；是在电力安全系统发布的服务提供方和服务调用方之间的规约。接口服务描述必须包含对各个方面的人员有意义并可理解的信息，接口服务描述要包含概要和详细服务信息，使用平台/技术实现无关的语言进行描述以业务为导向。
接口服务描述主要由2部分组成：接口服务属性和接口服务规约。
3.2　接口服务属性
接口服务属性是业务接口服务的描述，它提供组织和性能相关要求，是接口服务提供方和接口服务消费方之间服务协议的依据。定义一个接口服务应该包含的属性如下所示：
 服务编码（必选）：能体现出接口服务的业务含义的唯一识别编码，应遵循统一的编码规则，具体定义请参考交易服务代码规范；
 接口服务中文名称（必选）：能体现接口服务的意义，简单概括，应少于30个汉字；
 接口服务描述（必选）：清晰描述接口服务的业务功能；
 服务提供方（必选）：提供此接口服务的业务系统；
 服务消费方（可选）：可能会使用到此接口服务的业务系统；
 服务等级（必选）：分为紧急、普通和低级；
 报文XSD文件名：指请求报文XSD文件名和响应报文XSD文件名；
 数据量（必选）：运行期间单次访问的数据量均值和范围，比如均值为200K，范围：100K-300K；
 运行效率（可选）：单次访问的响应时间均值和范围；
 支持并发（可选）：此接口可支持的并发访问量；
 是否可重（可选）：接口是否能被多次重试调用；
 超时说明（必选）：提供超时时间及其说明。
 返回码说明（必选）：业务上需提供返回码和返回信息给服务消费方。
 技术方式（必选）：明确此接口的技术方式，其技术方式必须为《电力安全系统接入规范》中规定的技术方式；
 调用说明（必选）：提供调用此接口服务的必要条件。根据《应用平台接入规范》中定义的接入技术方式：
（1）Web Service：WSDL文件或者WSDL地址；
（2）EJB：EJB访问地址，链接用户名/密码，JNDI名称，EJB的jar文件；
（3）JMS：请求和返回结构的定义文件，JMS链接地址，Queue或者Topic的JNDI 名字。例如：jms//hostname:port/ConnectFactory/ObjectJNDI。
 安全要求（必选）：描述此接口服务的安全要求。
按照接口服务定义规范生成的《接口服务列表模板》文档，各系统可参考此文档定义并提交接口。
 接口服务调用权限（必选）：描述此接口服务的调用权限。
 描述该接口可以被哪些系统调用，即服务的调用权限。
3.3　接口服务规约
接口服务规约是接口及参数的技术描述，定义所有绑定和传输信息，以及所有支持的操作及相关输入、输出的格式，EJB或JMS等以XSD格式描述；而Web service协议通常以WSDL形式存在，被称为服务WSDL。接口服务规约包含：详细接口服务操作描述、数据类型、消息格式和结构、绑定的传输协议和服务的位置。
4　接口服务实现规范
4.1　设计规范
 接口服务命名要遵循一致的服务命名规范，参见下一章；
 接口服务应该遵守统一的报文规范，参见下一章；
 接口服务为了重用可以适当提高接口的颗粒度；
 接口服务的设计和定义应该与接口的实现分阶段进行；
 接口服务中传输的报文要求都是经过校验的，符合业务规则的，否则不符合报文会被返回；
 接口服务应充分考虑到扩展性，例如-在定义数据结构时多个字段封装为一个可扩展的对象；
 接口服务应尽可能通用，对于同一业务对象，应避免为不同系统开发不同接口服务。
4.2　检查规范
接口服务抽取后要对服务的交互进行检查，通过此检查来发现该接口服务是否合理。以下列出的是对接口服务进行检查的指导性原则，这些原则在运用的时候可以根据具体的项目情况进行裁减和选择。
 业务服务能否可以被一个以上的流程使用；
 业务服务是否是灵活和完整的；
 业务服务是否是与业务相关、有业务含义并被业务人员所能理解的；
 该服务在多大程度上依赖于其它业务服务；
 该服务是否是无状态的服务；
 该服务的描述是否和其它服务的描述相冲突；
 是否没有类似或重复的服务存在。
5　报文规范
5.1　报文组织格式
报文在组织形式上划分为技术报文和业务报文两个部分，目的是将一些技术控制信息与业务信息分离开来，一方面可使逻辑上更加清晰，一方面可以提高系统处理的效率。
根据应用集成标准的要求，为使不同应用系统能够直接有效的进行集成，电力安全系统主要使用XML格式报文。无论在何种传输协议上，如EJB、Web Service、JMS、MQ、FTP等，不同系统之间面对的报文格式需要尽量统一，提高处理的效率。同时为了保障EJB集成的高效，电力安全系统同时提供EJB协议下的标准开放的JavaBean对象格式报文。无论是XML格式还是JavaBean对象格式，只是报文数据的表现形式不同，要求这2者在语义上必须等价。
5.2　业务报文
业务报文表达了业务服务的业务语义，包含业务逻辑所需要的业务属性。
业务报文包括业务请求报文和业务响应报文，对应业务服务的输入参数和输出参数。电力安全系统需要能够根据要求配置这些服务参数是否进行业务语义上的校验，需要能够按照标准通用开放的形式定义业务报文格式及其效验格式。具体定义分别参见下面的XML报文和JavaBean报文中的业务报文规范。
5.3　XML报文规范
采用XML方式来传输接口数据，XML报文满足通用性和扩展性原则，能满足业务的各种需要，而且方便开发人员应对不断变化的业务需求，方便新交易的开发。

1. XML报文结构
   XML从报文结构上体现技术报文和业务报文，如下图：

 service为技术报文根节点；
 head为技术报文头信息；
 body节点为报文体，业务报文填写在此节点中。
XML的结构是以XSD形式定义，需配套提供技术报文和业务报文的XSD定义，具体见下面2个章节。
2. 技术报文及XSD
技术报文的定义结构如下：

技术报文对应的XSD格式定义如下：

xs:sequence

xs:annotation
xs:documentation交易服务ID

xs:simpleType




xs:annotation
xs:documentation渠道ID

xs:simpleType






xs:annotation
xs:documentation交易流水号

xs:simpleType






xs:annotation
xs:documentation交易日期

xs:simpleType






xs:annotation
xs:documentation交易时间

xs:simpleType






xs:annotation
xs:documentation交易返回代码

xs:simpleType







xs:annotation
xs:documentation文件路径

xs:simpleType






xs:annotation
xs:documentation服务版本号

xs:simpleType









xs:annotation
xs:documentation参数列表类型



xs:annotation
xs:documentation参数属性名

xs:simpleType




xs:annotation
xs:documentation参数值

xs:simpleType






xs:annotation
xs:documentation返回信息

xs:sequence

xs:annotation
xs:documentation返回码小类代码

xs:simpleType






xs:annotation
xs:documentation返回信息

xs:simpleType




xs:annotation
xs:documentation原因及处理办法

xs:simpleType






xs:annotation
xs:documentation根节点

xs:complexType
xs:sequence


xs:annotation
xs:documentation报文体






3. 业务报文及XSD
业务报文包含请求报文和响应报文，是描述业务服务输入输出的关键结构，在语义描述上必须明确唯一，这是服务数据描述的业务关键内容。请求报文XSD和响应报文XSD定义将会在电力安全系统上进行管理，可以根据需要对传输的报文进行XSD格式的业务语义效验。其定义规范要求及XSD定义请参考下一章的业务报文定义规范。
在对XML内容传输时，对于统一入口参数的，将技术报文和业务报文组装成一个报文进行传递，为了避免电力安全系统或某些场景对业务报文的不必要解释处理，把业务报文内容放置在“body”节点的内包裹以提高系统效率，根据W3C组织标准，CDATA关键字内部的XML报文是不会被XML解析器解析。例如：。
而对于EJB或Web Service的多入口访问，技术报文和业务报文是分别2个参数传递，则业务报文内容不使用包裹，直接将技术报文XML和业务报文XML进行传递。
4. 扩展报文编写方法
扩展属性放在技术报文的expand节点中，每增加一个扩展属性，则需要增加一个expand节点，如下身份密码、人员和机关有3个扩展expand节点并行编写。

identityType
4432b7c8a61243f0a62813f01e47a1bb


sjry
24406060733


sjjg
14406820018

5. XML报文示例

SWZJ.HXZG.SB.CXSPHM GDGS.ZJNB.HXQD eea4ff11269045068f421dd3d654804e 20120416 083231475 identityType 4432b7c8a61243f0a62813f01e47a1bb sjry 24406060733 sjjg 24406820018 aaaaaaaaaaaStringStringString]]>

5.4　JavaBean对象报文规范

1. JavaBean对象定义要求
   JavaBean对象报文是XML格式的对象表达形式，包括技术报文对象和业务报文对象。其在语义上等价于XML报文，使用Java平台语言定义，是POJO对象，不能依赖于某个私有框架，应具有通用性和开放性。
   对象报文包含涉及到的所有对象（技术报文对象和业务报文对象）及其子对象都必须实现序列化接口Serializable，同时都需要显示的定义serialVersionUID以解决序列化兼容问题。这些对象的定义应只包含与本业务服务相关的属性，不能包含与后台处理相关的属性。
2. 技术报文对象定义
   技术报文对象包含报文根对象、报文头对象、报文体对象，等价于XML报文的技术报文XSD定义。
   报文根对象包含2个对象属性即报文头对象和报文体对象。
   报文头对象包含交易服务、渠道系统、交易流水、交易日期和时间等简单属性；如果有扩展属性，则需要有扩展对象集合，以key/value形式展现；对于交易服务的返回，则还需要包含返回对象，包含交易返回码以及交易失败时的错误原因信息。
   报文体对象则是业务报文对象的展现形式，需要通过序列化二进制形式作为报文体对象的属性，这是为了避免电力安全系统对其中的业务报文对象的序列化反序列化，提高系统的处理效率和避免业务报文对象依赖的部署发布影响。业务报文对象定义则具体参见下一节。
3. 业务报文对象定义
   业务报文对象是业务服务的输入输出参数对象，包含请求报文对象和响应报文对象，分别等价于业务请求报文XSD定义和响应报文XSD定义，XSD定义规范要求请参考下一章的业务报文XSD定义规范。
   考虑到业务报文对象及其结构关系和数据类型的多样性及复杂性，以及对象与XSD之间和XML之间转换以及语义效验的通用标准性，建议业务报文对象遵守业界公开普及的JSR 222标准规范，该规范已经作为Java6内置标准OXM规范，采用Java6内置的JAXB工具即可实现XSD/XML和对象之间的正向反向转换映射。
   6　业务报文XSD定义规范
   6.1　元数据和数据元的要求
   元数据规范要求，同一个业务含义的字段在各个系统中命名要保持一致。数据元需要遵循的数据元规范，数据元公共报文名为TaxMLpublic.xsd，供所有业务报文引用。
   6.2　业务报文分类
   业务报文从不同角度存在多种分类方式：
4. 从交易过程分：请求报文、响应报文和非交易报文（消息类报文）。
5. 从交易类型分：提交类报文和查询类报文和校验类报文。
6. 从报文内容分：表单类报文和非表单类报文。
   6.3　业务报文XSD文件命名
   电力安全系统业务报文XSD文件命名定义为多级字符串，总层级结构为六级，可包括大写字母和数字，各级间通过“_”进行相连。对于统一的业务服务，业务报文XSD文件命名由统一制定；对于其他自行增加的非统一的业务报文，可按照下述规范制定文件命名规范，，但总层级结构不能超过六级，总长度不能超过100位字符。
7. 业务报文XSD命名规范第一级
   1、所有业务报文文件均以“TaxMLBw”作为命名前缀，其中TaxML做为行业标准要求，Bw为报文的简称。
   2、表单类业务报文编制时，每一张表单对应一个表单类业务报文，如果是依附于主表存在的附表报文，定义报文时要与主表业务报文放在同一目录下，其命名规范如下：
   TaxMLBd_表证单书编号_版本号
   3、表证单书编号详见GxB政务信息系统建设项目工程《代码集》。
8. 业务报文XSD命名规范第二级（系统标识）
   参见本文5.2.2.2章节 服务命名规范（系统标识）
9. 业务报文XSD命名规范第三级（主题类型）
   参见本文5.2.2.3章节 服务命名规范（主题类型）
10. 业务报文XSD命名规范第四级（服务序号）
    服务序号采用5位数值型标识，初始值为00001，顺序累加1，服务序号一经使用，不得更改。
11. 业务报文XSD命名规范第五级
    所有请求报文都以“Request”作为标识；所有响应报文都以“Response”作为标识；
12. 业务报文XSD命名规范第六级（版本号）
    所有版本号前缀采用大写字母“V”标识，版本号采用两位数值型，中间使用字符串“.”进行连接，初始值为1.0，数序，如XSD报文有版本变更或升级，版本号顺序累加0.1。
13. 业务报文XSD命名示例
    以GxB政务信息系统建设项目核心征管系统消费申报事前监控及获取期初数据业务报文为例，其XSD业务报文命名为：
    请求报文：TaxMLBw_HXZG_SB_00001_Request_V1.0.xsd
    响应报文：TaxMLBw_HXZG_SB_00001_Response_V1.0.xsd
    6.4　业务报文XSD编制
14. 基本原则
     业务报文编制时，对于已存在数据元或聚合数据元的部分，应该引用数据元或聚合数据元；
     在满足交换需求的前提下，尽可能利用已有的数据集合或业务报文，避免重复编制；
     所有业务报文都需要包含（include）TaxMLpublic.xsd文件，从中引用数据元；
     业务报文的第一层结构中，只能使用“复杂类型”（complexType），不得使用“element”、“group”等其他类型；
     所有数据集合之下只能存在一层结构，若需要嵌套多层结构，必须抽象成多个数据集合（complexType），再进行引用。
15. 业务报文的前导说明
16. 字符集：encoding属性值为“UTF-8”。
17. 命名空间：依据SW/T XX—201X《基于XML的数据交换格式设计规则》，
    XML的命名空间定义为：http://www.chinatax.gov.cn/dataspec/。
18. 前导说明示例：参照《SW/T XX—201X基于XML的数据交换格式设计规则》，如：

targetNamespace=”http://www.chinatax.gov.cn/dataspec/”
xmlns=”http://www.chinatax.gov.cn/dataspec/”>
应在前导说明部分以注释的形式说明以下内容：
——数据交换格式的名称；
——数据交换格式的版本；
——XML模式编写单位或编写人；
——XML模式完成时间。
3. 表单类业务报文
按照通常的表单样式，表单类业务报文通常存在几个数据集合：
 “xx表单业务报文”：这是表单类业务报文的根元素数据集合，命名通常为“表单名称”+“Ywbw”，此集合下只添加一个元素，这个元素引用“xx表单”集合；
 “xx表单”：这是实际的业务表单内容，包括表头和表体集合；
 表头：对应表单上除表体具体内容外的通用类信息，例如编制方、时间等等；
 表体：对应表单上各行、列等具体内容。
表单中业务含义明确的集合可以抽取为数据集合。
例如，所有申报表业务报文的“表头”中都应使用聚合数据元中的“申报表公共表头”（SBBHead），若在该集合之外表单上还有其他的表头信息，应将其他的表头信息组成一个“私有表头”集合，与“公共表头”组合成为该申报表的“表头”集合。
申报表业务报文中的“xx申报表”集合中，除表头和表体之外，可增加一个可空的“预留：附属表体”（BodyAffix）元素，类型设置为“xs:anySimpleType”。
申报表表体的编制依据表样可横向抽取明细信息或纵向抽取表列信息。
一般来说，在编制申报表的标准时，也会同时编制申报表提交和申报表明细查询的接口，这两类接口都有固定的请求、响应报文模式，申报表提交的请求报文和申报表明细查询的响应报文都应直接引用申报表表单业务报文进行编制。
4. 非表单类业务报文
非表单类业务报文可根据实际的数据交换需求内容编制，其中存在多行重复的内容可抽取为数据集合。编制中应尽量使用聚合数据元。