一、适用场景

如下图所示，在做WEB API开发时，当原始接口的请求参数、响应参数不符合请求端的要求时，使用此工具进行请求参数、响应参数的转换：

需要使用的Java类封装在bangbang_common包中，自版本1.0开始含有该工具：

import team.bangbang.common.service.agent.AgentInvoker;
import team.bangbang.common.service.agent.XmlLoader;
import team.bangbang.common.service.agent.data.RestfulAgents;

二、定义

原始接口：真正包含业务逻辑，提供服务的WEB API接口 封装接口：为适配终端的请求数据、响应数据进行转换，并对外提供服务的接口

三、编码

3.1 编码流程

3.2 编码示例

/* 加载XML配置，XML位置放在指定的类class加载路径的相对位置上 */
private static RestfulAgents ras = 
    XmlLoader.load(CarTransactionAction.class, "xml/AppServiceAgent.xml");
……

/* 使用xml配置的agent标记下的name标记获得指定接口调用转发对象 */
AgentInvoker ai = new AgentInvoker(ras.getAgent("saveOutRequest.action"));
/* 传入终端请求参数 */
Map<String, String> params = AgentInvoker.getRequestParameters(this.getHttpRequest());
ai.setRequestData(params);

/* 调用接口服务 */
JSONObject json = ai.invoke();

3.3 配置说明

注意XML位置放在指定的类class加载路径的相对位置上，参见3.2编码示例。

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
使用方法：

  // 1).读取xml配置
  RestfulAgents ras = 
    XmlLoader.load(CarTransactionAction.class, "xml/AppServiceAgent.xml");

  // 2). 使用xml配置中的一个agent构造服务代理对象
  AgentInvoker ai = new AgentInvoker(ras.getAgent("saveOutRequest.action"));
  // 3). 构造Map类型的传入参数
  Map<String, String> params = 
    AgentInvoker.getRequestParameters(this.getHttpRequest());

  ai.setRequestData(params);
  // 4). 调用，获得返回JSON
  JSONObject json = ai.invoke();
-->
<agents>
  <agent>
    <!-- 此name标记用于java代码识别agent配置 -->
    <name>saveOutRequest.action</name>
    <description>添加用车申请</description>
    <!-- 1. method 默认为POST -->
    <!-- 2. url属性中的${}表示一个变量，
        其中的变量名为appliation*.properties文件中定义的key值
    -->
    <forward url="${new.biz.admin.url.prefix}microservice/useApply/useApplyAdd.do"
                 method="POST"/>
    <!-- 3. request只接受application/x-www-form-urlencoded方式传递的参数 -->
    <request>
      <param from="userId" to="user.id"/>
      <param from="orgCode" to="useApply.organizationId"/>
      <param from="useReason" to="useApply.reason"/>
      <param from="usePerson" to="useApply.contacter"/>
      <param from="usePhone" to="useApply.mobile"/>
      <param from="carCategoryId" to="useApply.carTypeCode"/>
      <param from="persons" to="useApply.peopleCount"/>
      <param from="reqTime" to="useApply.startTime"/>
      <param from="useHours" to="useApply.mayHours"/>
      <param from="startPlace" to="useApply.startPoint"/>
      <param from="finalPlace" to="useApply.endPoint"/>
    </request>
    <!-- 4. response只处理json格式的响应参数 -->
    <response>
      <result from="statusCode" to="resCode">
        <map value="100" to="000000"/>
        <map other="F311101"/>
      </result>
      <result from="message" to="resMsg"/>
      <!-- 5. from、to属性的半角点号表示json数据的层级 -->
      <result from="DTO.recordCount" to="total"/>
      <!-- 6. list标记处理json数组 -->
      <list from="DTO.list" to="dataList">
        <result from="id" to="auditId"/>
        <result from="bizNo" to="reqId"/>
        <!-- 7. format属性用于格式化日期类型的数据 -->
        <result from="bizData.startTime" to="reqTime" format="yyyy-MM-dd"/>
        <!-- 8. default属性用于null数据的替换 -->
        <result from="bizData.carType.itemName" to="carCategoryName" default=""/>
        <result from="bizData.startPoint" to="startPlace"/>
        <result from="bizData.endPoint" to="finalPlace"/>
        <result from="bizData.statusFlag" to="status"/>
      </list>
    </response>
  </agent>
</agents>