关于APP端接口设计的几点思考

对于做服务端开发的人来说，一般只关注接口的入参擦传入和数据的组装返回，以前在做web系统时，一般会根据页面展示数据的不同去实现不同的接口，有新的业务就做新的接口设计，有需要修改的旧业务，就在以前的接口里去更新业务逻辑。

但是这套做法不适用于针对APP端的接口，原因就在于APP的业务需要靠升级去呈现出不同的功能以及不同的数据，

举个例子：获取用户信息接口getUserInfo在V1.0.0里和在V2.0.0里可能就需要返回不同的数据，这个时候服务端的接口怎么去实现呢？因此这篇文章就是一些个人的思考，怎么去设计针对APP端的接口。

一、有几点在设计时需要考虑下：

1. 接口安全（token或者sign应该怎么去设计），这里的设计不是说考虑什么加密方式，而是考虑服务端验签代码放在哪儿？

2. 版本控制，服务端怎么控制每个版本才更加清晰，利于维护，另外,怎么根据不同的版本去调用不同的接口呢？

二、实际例子：

考虑的话比较抽象，举个例子吧，比如

1. 服务端有个接口： 获取用户信息getUserInfo(String userId)，

2. APP端在V1.0.0时访问getUserInfo(String userId)返回10条数据。当V2.0.0时，这个接口需要额外增加20条数据返回做其他业务操作，但是针对V1.0.0---V.2.0.0之间的版本的用户需要保持原样，只有V2.0.0的用户才有额外20条数据返回。

如果一开始没有设计好接口版本的话，就可能出现下面的情况，比如服务端在一开始写的时候直接就是：

getUserInfoV1.0.0(String userId) --->返回10条数据。当后续1.2.0,1.4.0版本时，由于接口数据没有变化，所以你会和APP端的人说这边业务没变，你们还调用getUserInfoV1.0.0(String userId)这个接口就行了。

因此可能就是

APP1.0.0 --- > getUserInfoV1.0.0

APP1.2.0 --- > getUserInfoV1.0.0

APP1.4.0 --- > getUserInfoV1.0.0

这样以后的话，根本没法交流，第一服务端的人不知道这个接口是给哪些版本在用，第二客户端的人还需要问服务端V几版本去调用哪一个接口是对的？太麻烦。

因此针对这种问题我想最好的情况是APP端只关注他的版本，比如V1.0.0，V2.0.0将这个作为参数传递过来，服务端呢？解析版本去调用对应的接口就行了，这样就能解耦开两边不一致的情况，服务端可以更好的知道这个接口哪些版本在使用。

那么怎么设计呢？

1. 版本怎么设计，怎么区分V1.0.0和V2.0.0呢？

这边可以采用Java自带的注解，我们可以设计一个Version注解，里面放入min和max字段标注最小版本和最大版本，这样就解决了服务端某个接口支持哪些版本的问题了

package com.wayne.biz;

import com.wayne.Constant;
import com.wayne.VersionConstant;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;

/*
 * @Description: 注解类，用于biz内方法级别版本的控制
 * @Author: wayne
 * @Date: 2019/3/7 14:55
 */
@Documented
@Target({METHOD,TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Version {

    //默认最小版本为0.0.1
    int min() default VersionConstant.V0_0_1;

    //默认最大版本为99.99.99
    int max() default VersionConstant.V99_99_99;

}

package com.wayne;

/*
 * @Description: 版本常量
 * @Author: wayne
 * @Date: 2019/3/7 15:17
 */
public class VersionConstant {

    //初始版本
    public static final int V0_0_1 = 1;

    //v0.0.2
    public static final int V0_0_2 = 2;

    //V0.2.1
    public static final int V0_2_1 = 201;

    //V1.0.0
    public static final int V1_0_0 = 10000;

    //V1.1.3
    public static final int V1_1_3 = 10103;

    //V2.1.3
    public static final int V2_1_3 = 20103;

    //最大版本
    public static final int V99_99_99 = 999999;
}

版本的值可以这么设计，比如V1.0.0，服务端可以设计成10000，“点号”用0代替，这样解析和比较大小就方便多了，V2.0.0就是20000 > 10000，可以直接比较出来。

2. 怎么去保存和设计这样一个版本映射接口的方案呢？

我们可以利用Spring的一些现有方案，InitializingBean，我们设计一个公共类比如：BaseBiz，让所有继承它的类都在初始化之后去执行同一个操作，保存版本和接口的映射关系。

package com.wayne.biz;

import com.wayne.Constant;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.InitializingBean;

import java.lang.reflect.Method;
import java.util.TreeMap;

/*
 * @Description: 基础biz类，包含初始化接口数据
 * @Author: wayne
 * @Date: 2019/3/2 16:25
 */
public class BaseBiz implements InitializingBean {

    private static final String ZERO = "0";

    private static final int NUM_INDEX = 6;

    @Override
    public void afterPropertiesSet(){

        Method[] methods = this.getClass().getMethods();

        TreeMap<String,Method> methodMap = new TreeMap<String,Method>();

        String methodName = this.getClass().getCanonicalName();

        Version version;

        for(Method method : methods){
            if(method.isAnnotationPresent(Version.class)){
                version = method.getAnnotation(Version.class);
                //拼接6位min+6位max不足补零(因为只支持到99.99.99)
                methodMap.put(StringUtils.leftPad(String.valueOf(version.min()),NUM_INDEX,ZERO) + StringUtils.leftPad(String.valueOf(version.max()),NUM_INDEX,ZERO),
                        method);
            }
        }
        Constant.METHOD_VERSION.put(methodName,methodMap);
    }

}

package com.wayne;

import java.lang.reflect.Method;
import java.util.*;

/*
 * @Description: 常量
 * @Author: wayne
 * @Date: 2019/3/2 17:03
 */
public class Constant {

    public static final String CODE = "code";

    public static final String SUCCESS = "DEMO001";

    //本地缓存存放接口映射关系
    public static final Map<String, TreeMap<String, Method>> METHOD_VERSION = new HashMap<>();

    /**
     * 返回值
     */
    public enum ReturnCode {

        SUCCESS("DEMO001", "操作成功"),
        FAIL("DEMO999", "操作失败"),
        EMPTY_SIGN("DEMO100", "签名为空"),
        EMPTY_VERSION("DEMO200", "版本号为空"),
        ERROR_SIGN("DEMO300", "签名不匹配"),
        ERROR_VERSION("DEMO400", "需要升级");

        // 编码
        private final String code;

        // 描述
        private final String desc;

        private ReturnCode(String code, String name) {
            this.code = code;
            this.desc = name;
        }

        public String getCode() {
            return code;
        }

        public String getDesc() {
            return desc;
        }

        public static String getDesc(String code) {
            for (ReturnCode c : ReturnCode.values()) {
                if (c.getCode().equals(code)) {
                    return c.getDesc();
                }
            }
            return null;
        }
    }
}

3. 怎么去设计不同版本的接口？

其实上面我们用一个公共的biz就是为了好设计不同版本的接口，有了baseBiz，我们只需要继承它，然后写我们自己的接口就行了。下面的代码是不是就显得很清晰了，版本在方法层级，每一个方法都对应着一个版本区间。

package com.wayne.biz;

import com.wayne.Constant;
import com.wayne.VersionConstant;
import com.wayne.vo.JsonData;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

import java.util.Map;

@Component
public class UserInfoBiz extends BaseBiz{

    /**
      * @Description 查询用户信息V1版本
      * @Author wayne
      * @Param
      * @Date 2019/3/7 17:19
      * @return
     **/
    @Version(max = VersionConstant.V0_0_2)
    public JsonData queryV1(Map<String, Object> param) {
        return JsonData.getSuccess(Constant.ReturnCode.SUCCESS.getCode(),null,
                Constant.ReturnCode.SUCCESS.getDesc());
    }

    /**
     * @Description 查询用户信息V2版本
     * @Author wayne
     * @Param
     * @Date 2019/3/7 17:19
     * @return
     **/
    @Version(min = VersionConstant.V1_0_0, max = VersionConstant.V2_1_3)
    public JsonData queryV2(Map<String, Object> param) {
        return JsonData.getSuccess(Constant.ReturnCode.SUCCESS.getCode(),null,
                Constant.ReturnCode.SUCCESS.getDesc());
    }

    /**
     * @Description 查询用户信息V3版本
     * @Author wayne
     * @Param
     * @Date 2019/3/7 17:19
     * @return
     **/
    @Version(min = VersionConstant.V2_1_3)
    public JsonData queryV3(Map<String, Object> param) {
        return JsonData.getSuccess(Constant.ReturnCode.SUCCESS.getCode(),null,
                Constant.ReturnCode.SUCCESS.getDesc());
    }

}

3. 怎么去设计调用方式呢？

回顾一下1-3，我们做了些啥，我们缓存了biz类里面版本对应的不同接口Map,类似于

<userInfoBiz,{<v1.0.0,method1><v2.0.0,method2>}>,这样我们只要传入两个参数(userInfoBiz,v1.0.0)就能知道我当前需要执行哪一个类里面的哪一个方法了吧。

因此这边可以利用反射去调用吧。另外我们这边顺带解决另一个问题，就是加密问题，APP端需要传入一个加密字段，服务端需要解密这个字段比较是不是授信用户吧，所以我们可以将加密字段sign和版本字段verison合起来设计。

package com.wayne.vo;

/*
 * @Description: 接口入参公共类
 * @Author: wayne
 */
public class ParamVo {

    //版本信息
    //eq. 1.0.1  2.1.0
    private String version;

    //参数签名
    private String sign;

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getSign() {
        return sign;
    }

    public void setSign(String sign) {
        this.sign = sign;
    }

    @Override
    public String toString() {
        return "ParamVo{" +
                "version='" + version + '\'' +
                ", sign='" + sign + '\'' +
                '}';
    }
}

controller里可以定义一个方法，用户接收APP的参数传入问题：（注意加密方式，对接过第三方接口的人应该很熟悉加密方式，我们这边假设是按照字典排序然后加盐值排序，这也是用的最多的一种方式）

package com.wayne.controller;

import com.wayne.biz.UserInfoBiz;
import com.wayne.vo.JsonData;
import com.wayne.vo.ParamVo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.TreeMap;

@Controller
@RequestMapping("/mvc")
public class UserController extends BaseController{

    @Autowired
    private UserInfoBiz userInfoBiz;

    /**
      * @Description 获取用户信息
      * @Author wayne
      * @Param paramVo 公共参数 version && sign
      * @Param userId 用户Id
      * @Param type 请求用户的type类型数据
      * @Date 2019/3/7 17:52
      * @return
     **/
    @RequestMapping("/get")
    @ResponseBody
    public String getUserIno(ParamVo paramVo,String userId,String type) throws Exception{

        //请求参数封装按照字典排序封装成map
        TreeMap<String,String> param = new TreeMap<>();
        param.put("userId",userId);
        param.put("type",type);

        JsonData data = forwardRequest(paramVo,userInfoBiz,param);

        //模拟返回json数据
        return data.toString();

    }

}

最后加解密和反射调用其实就很自然的需要一个公共Controller了，BaseController

package com.wayne.controller;

import com.wayne.Constant;
import com.wayne.biz.BaseBiz;
import com.wayne.vo.JsonData;
import com.wayne.vo.ParamVo;
import org.apache.commons.lang3.StringUtils;

import java.lang.reflect.Method;
import java.util.Map;
import java.util.SortedMap;
import java.util.TreeMap;

public class BaseController {

    //加密字段
    private static final String KEY = "Demo11556677";

    /**
      * @Description 转发此次请求
      * @Author wayne
      * @Param paramVo: 接口公共参数 version | sign
      * @Param baseBiz: 接口方法，反射调用具体版本接口
      * @Param inputMap: 接口其他参数
      * @Date 2019/3/2 16:26
      * @return
     **/
    public JsonData forwardRequest(ParamVo paramVo, BaseBiz baseBiz, Map<String, String> inputMap) throws Exception{

        //验证签名合法性
        JsonData result = verifySign(paramVo, (TreeMap<String, String>) inputMap);

        if(!Constant.SUCCESS.equals(result.get(Constant.CODE))){
            //异常情况直接返回异常结果
            return result;
        }

        //正常情况下获取当前请求的对应版本的方法
        Method method = this.chooseMethodVersion(baseBiz.getClass(), paramVo.getVersion());

        if(method == null){
            return JsonData.getFail(Constant.ReturnCode.ERROR_VERSION.getCode(),Constant.ReturnCode.ERROR_VERSION.getDesc());
        }

        //调用对应版本
        return (JsonData) method.invoke(baseBiz, inputMap);

    }

    /**
     * @Description 验证签名是否合法
     * Key + inputMap 内字段拼接成字符串得到MD5值与前台的sign做匹配
     * @Author wayne
     * @Param paramVo:接口公共参数 version | sign
     * @Param inputMap:接口其他参数
     * @Date 2019/3/2 16:30
     * @return JsonData.getFail("Demo100","签名为空")
     *         JsonData.getFail("Demo200","版本号为空")
     *         JsonData.getFail("Demo300","签名不匹配")
     *         JsonData.getSuccess("Demo000","签名匹配成功")
     **/
    private JsonData verifySign(ParamVo paramVo, TreeMap<String, String> inputMap) {

        // 获取前台传入的签名值
        String sign = paramVo.getSign();

        if(StringUtils.isEmpty(sign)){
            JsonData.getFail(Constant.ReturnCode.EMPTY_SIGN.getCode(),Constant.ReturnCode.EMPTY_SIGN.getDesc());
        }

        // 获取前台传入的版本值
        String version = paramVo.getVersion();

        if(StringUtils.isEmpty(version)){
            JsonData.getFail(Constant.ReturnCode.EMPTY_VERSION.getCode(),Constant.ReturnCode.EMPTY_VERSION.getDesc());
        }

        //参数为空时version参与加密，参数不为空时只做参数加密，version不参与加密
        //此处可以自己定义加密规则
        String targetSign = KEY +
                (inputMap == null ? version : StringUtils.join(inputMap.values().toArray()));

        return sign.equals(this.getMd5Str(targetSign)) ? JsonData.getSuccess(Constant.ReturnCode.SUCCESS.getCode(),null,Constant.ReturnCode.SUCCESS.getDesc())
                : JsonData.getFail(Constant.ReturnCode.ERROR_SIGN.getCode(),Constant.ReturnCode.ERROR_SIGN.getDesc());

    }

    /**
      * @Description  获取md5加密的值
      * @Author wayne
      * @Param
      * @Date 2019/3/7 17:55
      * @return
     **/
    private String getMd5Str(String sourceStr){

        return sourceStr;

    }

    /**
      * @Description 获取调用版本
      * @Author wayne
      * @Param
      * @Date 2019/3/2 17:24
      * @return
     **/
    private  <T extends BaseBiz> Method chooseMethodVersion(Class<T> clazz, String version) {

        if (StringUtils.isEmpty(version) || clazz == null) {
            return null;
        }

        // 格式化后的版本
        // eq. version 1.2.3  --> requestVersion 010203
        StringBuilder requestVersion = new StringBuilder();
        for (String e : version.split("\\.")) {
            requestVersion.append(StringUtils.leftPad(e, 2, "0"));
        }

        // 当前biz内的所有版本
        SortedMap<String, Method> treeMap = Constant.METHOD_VERSION.get(clazz.getCanonicalName());

        // 请求版本
        int curVersion = Integer.parseInt(requestVersion.toString());

        //最小版本
        int minVersion = 0;
        //最大版本
        int maxVersion = 0;

        // 取出适合的版本
        for (Map.Entry<String, Method> entry : treeMap.entrySet()) {
            minVersion = Integer.parseInt(entry.getKey().substring(0, 6));
            maxVersion = Integer.parseInt(entry.getKey().substring(6, 12));
            //接口版本统一[min,max)做适配
            if (curVersion >= minVersion && curVersion < maxVersion) {
                return entry.getValue();
            }
        }

        return null;
    }
}

写在最后：

参考了一些别人的设计理念，加了一些自己的优化，可能不是很完美，但是个人觉得这样设计的话，比较直白和易于维护。