前端接口联调工具

作者介绍

黄仲萍，达达-京东到家-移动研发部iOS研发。曾在外企工作并有驻PaloAlto经历，有多年iOS开发经验，对iOS应用程序架构设计与组件封装有一定的经验与见解。目前负责“京东到家商家版”iOS的开发相关工作。

背景

京东到家App开发过程中，非常重要的一个环节是前端App与后端服务的接口联调，在多人协调的开发过程中，常常出现前、后开发同学对相同接口的理解不一致，导致了联调过程非常缓慢且复杂。为解决这个问题，在京东到家，我们提出前后端“接口确认次数”指标，来衡量接口联调效率，本文我们将分享京东到家在减少“接口确认次数”的一些实践经验。

面临的问题

在接口联调过程中的问题集中反应如下：

• 接口难自测：因为公共参数过多导致难以自测。

• 复杂功能测试效率低：因为复杂功能涉及输入过多，导致测试效率偏低。

• 直观验证难：无法直观验证接口是否正常部署。

解决方案

通过分析上面的三个问题，把问题的解决期望设为实现目标，再以目标为导向，逐一反推解决。

目标

• 模拟公共参数，辅助后台开发人员校验接口。

• 提供参数复制功能，提高测试人员测试效率。

• 优化测试流程，提高自测通过率，减少确认次数。

下面将针对上面提到的三个问题逐一进行说明。

接口难自测的解决思路

在开发过程中，导致服务端接口难自测有两个客观原因：

1. 服务端公共参数过多且难模拟，特别是其中的密钥值存在有效期。

2. 服务端的网络环境依赖。

如上图所示的“接口联调过程”中，后端需要前端确认点主要集中在两处：

1. 接口是否正常部署到服务器环境？

2. 接口输出是否符合业务需求？

这里若有一个接口工具能校验上述的两个“确认点”，就可以供后台开发人员自行确认。如下图所示增加了一个“接口自测”环节：

改进思路：

场景模拟：

1. 后端使用此工具能够验证自己开发的接口已正常部署；

2. 这个工具可以校验接口输出，并确认是否满足“前端接口文档”的要求；

预期界面设计

为了解决上面场景的第一个问题，就需要这个工具有模拟服务端公共参数的功能。由于在工具是运行应用程序内部，所以可以较轻松模拟公共参数：

+ (NSMutableDictionary *)generateGatewayParams:(NSDictionary *)params
{
    NSMutableDictionary * gatewayHttpParams = [NSMutableDictionary dictionary];
    NSMutableDictionary *bodyParams = [NSMutableDictionary dictionary];
    ....
    生成公共参数
    ....
    return gatewayHttpParams;
}

创建公共参数

工具界面如下图：

上图的{"sc":"菜"}为请求此接口的私有参数

如上图所示，进行一次“接口自测”的流程如下：

1. 在“接口选择”，选择要确认的接口;

2. 自动展现出所选接口所需的非公共参数-“私有参数”;

3. 点击“请求接口” 模拟公共参数，发起接口请求;

4. 对比“结果json”与“预期json”的json结构，若有问题给出修改建议;

服务端开发人员或测试人员，只能在“京东到家商家”app应用内的预发布环境下，使用此工具，而正式环境下此功能不可见。

系统实现

接口配置： 按版本配置接口文件，配置内容如下图所示包含：“接口名”、“预期json”、“参数json”等信息。所以此处需要一个可用的文件服务器，让前端可以动态获取配置信息。

上图是接口版本的配置文件格式，其中functions节点里是当前版本需要测试的接口列表。此处对其中一个数组节点元素进行说明：

key: 接口名称；
expectJson:此接口期望的json输出；
funcId: 接口标识；
params: 此接口需要的私有参数，可以为null，也可以按需修改。如上图的type参数就可以进行自定义修改；

接口Response校验

结果校验目的是为后台开发人员在遇到接口错误时，能给出原因说明与修改建议。而这一部分是此工具实现难点，因为需要递归遍历json节点中所有key，以及对应的数据值与类型是否满足需求，若有问题，则给出修改建议。其中主要步骤说明如下：

1.模拟请求： 模拟一次网络数据请求，然后在请求成功后，把返回数据与“预期json”输出到界面。

...
//模拟网络请求
#pragma mark - JDHttpBaseApiDelegate
//网络请求成功返回数据
- (void)apiExecuteDidSuccess:(JDHttpBaseApi *)api{
    ....
    NSString *compareResult = [expectDict compareWithDict:api.resultData];
     //JSON结构结果对比
    ....
}
//网络请求错误返回数据
- (void)apiExecuteDidFailed:(JDHttpBaseApi *)api{
    ...网络请求失败的处理
}

2. JSON结构对比算法说明

代码实现如下：

- (NSString*)compareWithDict:(NSDictionary *)targetDict{
    NSString *res = @"";
    for (id key in self){//遍历当前字典所有key
        NSObject *targetObj = [targetDict objectForKey:key];
        if (targetObj == nil )
            res = [NSString stringWithFormat:@"预期key:%@在结果JSON未找到; \n%@"，key，res];
        else{
            NSObject *value = [self objectForKey:key];//查找本字典的值
            /*各种数据类型较验*/
            //字符串校验
            ...
            //值类型校验
            ...
            //字典递归校验
            if ([value isKindOfClass:[NSDictionary class]]){
                if ([targetObj isKindOfClass:[NSDictionary class]]) {
                    //字典递归遍历
                    NSString *subRes = [(NSDictionary *)value compareWithDict:(NSDictionary *)targetObj];
                    .....
            }
          }
        }
    }
    return res;
}

复杂功能测试效率低的改进方案

针对应用内的复杂功能测试，如“商品创建”所涉及到参数较多，高达20个以上，QA为测试此功能而创建参数耗时需要2分钟以上，那如何来提升创建参数的效率呢？ 所以此工具提供了参数拷贝的功能，参数拷贝就是对接口联调列表里的接口，进行参数“监听”，只要应用内涉及到此接口的UI交互，那么就会自动拷贝此接口请求的最后一次参数。如：在应用内操作了一次“品牌搜索”，就会默认记录该接口最近一次请求所需的参数。如下图所示：下次再进入此工具界面时，只需修改少许参数就可以进行接口模拟。这样对复杂功能进行测试，如“商品创建”，只要稍微调整所复制参数就可以进行“商品创建”的测试了，而无需像上面那样一个一个的进行输入，从而提升了复杂功能的测试效率。

直观验证难的处理方法

针对服务端无法直观验证自己所开发的接口，自己开发的接口是否正常部署到网络环境上或是否符合业务需求？此工具通过以“预期json”的内容为标准，对接口请求返回后“结果json”进行校验，有数据错误就给出说明：

上图里的Function[0000092]是服务端错误码， 错误码：为服务端针对接口输出失败，而定义的错误说明字符串。

上图所示的“结果对比”，是“结果json” 与“预期json”在进行json结构对比后，给出的校验输出。此时出现了“错误码”，此时服务端根据工具界面里给的提示，得知自己开发的接口未正常部署到服务器环境，经过修改配置后再重新部署程序再进行校验。而此流程中是不需要与前端进行确认，这样就达到了降低沟通次数的目的。

总结：

此工具通过应用内模拟公共参数解决了“接口难自测”的问题，使用了参数拷贝解决了复杂功能的测试效率低的问题。最后通过输出接口校验结果解决了服务端的接口验证问题。通过几轮测试工具真实使用情况来看，后端在有使用此接口测试工具的情况下。双方接口确认次数从原来平均4.3次左右，降到0.6次。在很大程度上提升了提升工作效率。