通用转换接口设计
目录
- 转换接口的定义
- 转换接口的作用
- 转换接口的使用
- 转换接口的实现
1. 转换接口的定义
接口是系统内部与第三方系统协议数据的相互转换处理过程，转换接口以XML配置的形式把这种处理过程描述出来，方便接口的开发与维护；
2. 转换接口的作用
- 增加开发效率，转换接口抽象出通用的转换处理，开发只需组装对应转换操作即可，减少了重复开发的工作，增加开发效率；
- 降低出错率，统一协议转换之外的处理，接口开发只需配置相应的转换处理，减少代码量，降低出错概率；
- 减少维护成本，接口配置化后，对接口协议的调整，只需要针对接口配置修改即可；
3. 转换接口的使用
接口配置以XML文件描述，XSD文件定义节点结构，节点分为转换接口和扩展节点，转换节点用于做数据转换处理，可拥有多个子节点，一般先执行父节点，后执行子节点，执行方式有顺序、选择、循环，子节点如果出现异常，父节点可捕获做处理；扩展节点用于对接口配置或转换节点扩展使用；
3.1 接口配置说明
转换定义文件：有XSD文件表示，定义具体转换节点，需描述节点名称、参数名称，参数类型和转换处理类；
<!--MD5加密-->
<xsd:element name="md5">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="nestedConverterType">
<!--MD5处理类-->
<xsd:attribute name="clazz" type="xsd:string"
fixed="com.nnk.ecsys.interfaceConverter.converter.Md5Converter"/>
<!--加密字符串-->
<xsd:attribute name="value" type="paramType" use="required"/>
<!--编码类型-->
<xsd:attribute name="charsetType" type="paramType" use="optional"/>
<!--大小写类型-->
<xsd:attribute name="caseType" type="caseType" use="optional"
default="LowerCase"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
转换节点：由XML节点表示，做具体的转换处理，可有多个输入参数和一个输出参数，输入参数由具体转换节点定义，属性name表示输出参数，转换结果以name值作为名称存入【上下文变量】；
输入参数：值可直接用字符串表示，如需引用【上下文变量】则使用${变量名}表示，还可以相互组合， 如：value="${参数2} AAA ${参数2}"，如需要引用对象的参数，则使用${变量名.参数名}表示，基本用法和EL表达式类似；
扩展节点：可自定义扩展节点，针对接口配置或转换节点做处理，现有扩展节点，import可导入其他接口配置，loadProperty可加载properties文件变量；
示例：
interface-trade.xml
<?xml version="1.0" encoding="UTF-8"?>
<converter xmlns="http://www.007ka.com/schema/converter"
xmlns:extend="http://www.007ka.com/schema/converter/extend"
xmlns:interface="http://www.007ka.com/schema/converter/interface">
<!--导入配置文件-->
<extend:loadProperty location="properties/common.properties"/>
<!--定义请求对象-->
<getRequest name="request"/>
<!--组装请求报文-->
<interface:tryException errorCode="CEC_FAILED" errorMsg="请求报文组装异常">
<!--转换参数-->
<set name="orderReq" value="${request.reqeustParam}" />
<interface:mapget name="cardType" key="${orderReq.providerId}" mappingName="providerMap"/>
<!--组装协议-->
<set name="orderInfo"
value="${nnk_merId}|${orderReq.orderId}|${cardType}|${orderReq.unitCount}|"/>
<interface:md5 name="sign" value="${orderInfo}|${inter_channelKey}"
charsetType="${inter_charset}"/>
<interface:newInstance name="httpParam" value="java.util.HashMap">
<set name="httpParam.Orderinfo" value="${orderInfo}"/>
<set name="httpParam.Sign" value="${sign}"/>
</interface:newInstance>
</interface:tryException>
<!--调用http接口-->
<interface:tryException errorCode="CEC_UNKNOWN" errorMsg="网络异常">
<interface:http name="httpResponse" url="${inter_interUrl}"
paramMap="${httpParam}" charsetType="${inter_charset}"/>
</interface:tryException>
<!--解析响应报文-->
<interface:tryException errorCode="CEC_UNKNOWN" errorMsg="响应报文解析异常">
<!--解析报文-->
<interface:xmlToMap name="mapRes" value="${httpResponse}" />
<set name="mapRes" value="${mapRes.root}"/>
<!--协议验签-->
<interface:verifyMd5 charsetType="${inter_charset}" sign="${mapRes.Sign}"
value="${mapRes.MerID}|${mapRes.OrderID}|${mapRes.TranStat}|${inter_channelKey}"/>
<!--组装响应对象-->
<interface:newInstance name="orderRes"
value="com.nnk.ecsys.database.mapper.order.entity.ExternOrderOrderInfo">
<set name="orderRes.orderId" value="${mapRes.OrderID}"/>
<set name="orderRes.partnerOrderId" value="${mapRes.TranOrder}"/>
<set name="orderRes.partnerOrderReceiveErrorCode" value="${mapRes.TranStat}"/>
<set name="orderRes.partnerOrderReceiveErrorMsg" value="${mapRes.TranInfo}"/>
</interface:newInstance>
</interface:tryException>
<!--返回响应结果-->
<setResponse value="${orderRes}"/>
</converter>
TestMain.java
//接口配置资源
Resource resource = ResourceUtils.getResource("interface-trade.xml");
//转换构建器
ConverterStackerBuilder converterStackerBuilder = new DefaultConverterStackerBuilder();
//创建转换器
ConverterStacker converterStacker = converterStackerBuilder.buildConverterStacker(resource);
//执行转换
Order.ExternOrderInfo tradeRequest= Order.ExternOrderInfo.getDefaultInstance();
ExternOrderOrderInfo tradeResponse = (ExternOrderOrderInfo) converterStacker.invoke(tradeRequest);
4. 转换接口的实现
4.1 配置文件的解析与扩展
DefinitionReader // 配置读取类，读取解析接口配置文件
NamespaceHandler // 命名空间处理类，包含命名空间内每个节点的解析对象
NamespaceHandlerResolver // 命名空间管理类，管理每个命名空间的XSD文件路径和处理类
DefinitionParser // 节点解析类，解析具体的转换节点或扩展节点
ConverterDefinition // 转换节点定义信息类，包含返回值名称，参数列表，转换执行类名，子节点列表等信息
ConverterDefinitionContext // 转换定义上下文信息类，包含转换节点结构信息，常量参数对象等信息
处理流程：
1.DefinitionReader读取接口配置，递归解析节点信息，
2.根据节点命名空间调用NamespaceHandlerResolver获取指定NamespaceHandler处理
2.NamespaceHandler内部根据节点名称获取对应的DefinitionReader
3.DefinitionReader解析完成后把ConverterDefinition返回DefinitionReader，并存入ConverterDefinitionContext中
4.递归解析完成后最后得到ConverterDefinitionContext对象
扩展说明：
1.添加扩展节点解析类DefinitionParser，解析方法可获取ConverterDefinitionContext对象，可自定义转换节点，或对接口配置或转换节点做扩展处理；
2.添加命名空间处理类NamespaceHandler，描述节点名称与DefinitionParser解析类对应关系
3.添加扩展配置信息，在目录META-INF.converter下添加扩展配置：XSD文件、handlers.properties、schemas.properties，在NamespaceHandlerResolver对象初始化的时候，会读取运行环境下所有Jar下此目录的扩展文件；
XSD文件：定义扩展节点结构信息，以及指明命名空间名称
handlers.properties：描述命名空间与之对应的NamespaceHandler类
schemas.properties：描述命名空间与之对应的XSD文件路径
4.2 转换器的构建
ConverterDefinitionContext // 转换定义上下文信息类，包含转换节点结构信息，常量参数对象等信息
ConverterStacker // 转换器，执行具体的转换操作
Converter // 转换节点执行类
ConverterStackerBuilder // 转换器构建类
处理流程：
1.通过DefinitionReader读取接口配置，得到ConverterDefinitionContext；
2.ConverterStackerBuilder递归遍历ConverterDefinition，通过ConverterDefinition实例化Converter对象；
3.在Converter实例化过程，将会把Converter参数列表中存在的部分常量引用， 根据ConverterDefinitionContext常量列表设置为具体的值；
4.遍历完成后，每个Converter对象会有一个父节点喝多个子节点，形成树形架构的Converter集合；
5.最后使用Converter集合构建ConverterStacker对象；
4.3 转换器执行过程
ConverterStacker // 转换器，执行具体的转换操作
Converter // 转换节点执行类
ConverterRequest // 转换请求对象，作为执行过程中变量存储对象
处理流程：
1.接受转换请求，组装ConverterRequest；
2.执行开始，把根转换节点倒序放入执行栈中，然后循环出栈执行Converter；
3.在执行的过程中，根据ConverterRequest变量集合，实例化Converter的参数列表，如过程中存在未实例化的参数，将会抛出异常；
4.参数列表实例化完成后， 把变量列表传给Converter执行转换方法，完成后把结果以name为变量名把结果存入ConverterRequest；
5.转换执行完成后，获取当前Converter的后续节点倒序存入执行栈中，注意：获取后续节点的逻辑将由Converter本身实现，超类默认实现是获取子节点，但如果像选择、循环之类的结构，此方法逻辑将会重写；
6.如在Converter执行过程中出现异常，则会进入异常捕获处理分支，详情看代码；
7.循环执行到执行栈为空时，返回结果对象
4.4 上下文变量管理
ConverterRequest // 转换器请求对象
ConverterDefinitionContext // 转换定义上下文信息类，包含转换节点结构信息，常量参数对象等信息
AssemblyParam // 装配参数对象
处理流程：
详情看代码