大家是怎么做APP接口的版本控制的？欢迎进来看看我的方案。升级版的Versioning

背景

APP不同于网站，网站程序一发版，所有用户看到的都是最新的页面、调用最新的接口，没有新老版本一说。APP一旦下载到用户手机上，用户不更新你拿他一点办法都没有，但是随着业务的调整，同一个接口的请求参数和输出JSON有变化的话，就需要考虑老版本的兼容问题了。

举个例子：某APP的1.0.0版，服务端用户信息接口（api/User/UserInfo）输出的JSON如下

{
  "status": ,
  "message": "ok",
  "data": {
    "userId": ,
    "userNickName": "oppoic",
    "userName": "汪杰",
    "userEmail": "oppoic@163.com",
    "userBlog": "https://www.cnblogs.com/oppoic/",
    "userPic": "https://pic.cnblogs.com/avatar/401362/20180415232220.png"
  }
}

1.0.0版上线之后，产品迭代增加需求：一级菜单加一个付费用户入口，APP一打开就要动态判断当前用户是否付费。几个研发一商量，把用户是否vip的状态放到用户信息接口最合适。修改后服务端用户信息接口（api/User/UserInfo）输出如下

{
  "status": ,
  "message": "ok",
  "data": {
    "user": {
      "id": ,
      "nickName": "oppoic",
      "name": "汪杰",
      "email": "oppoic@163.com",
      "blog": "https://www.cnblogs.com/oppoic/",
      "pic": "https://pic.cnblogs.com/avatar/401362/20180415232220.png"
    },
    "vip": true
  }
}

修改前后的JSON有如下变化：

1）增加了是否vip字段；

2）为了结构更清晰，原来的userId、userName、userPic等属性移到到user对象下；

接口改好了之后APP端通过data.vip就可以判断当前用户是否vip了，同时也把原来data.userName改成了data.user.name等等。都改好后升了一个版本号，由原来的1.0.0改成了1.0.1发到了各大商店。

但是一上线就出问题了：升级1.0.1的用户打开个人信息页面正常，但是未升级的1.0.0用户打开个人信息页面报错

VM211:1 Uncaught TypeError: Cannot read property 'name' of undefined
at <anonymous>:1:16

原因是服务端个人信息接口的输出JSON改了，只能适配1.0.1的新版APP，无法满足老用户了。

有人说需求变了我就改服务端接口名称，老用户调老接口，新用户调新接口。这个方法是可以，但是接口多了简直就是一场灾难，项目从此无法维护。

路由方案

通过配置路由来区分不同版本的接口

config.Routes.MapHttpRoute(
            name: "DefaultApiWithVersion",
            routeTemplate: "api/v{version}/{controller}/{action}/{id}",
            defaults: new { id = RouteParameter.Optional }
);
config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{action}/{id}",
            defaults: new { id = RouteParameter.Optional }
);

APP端请求：api/v1/User/UserInfo，这种方案缺点如下：

1）版本号通常都是三段式的，例：1.0.1，硬套这个的话，服务端要建个命名空间带“.”的文件，C#对“.”支持不太友好。如果要改成1_0_1或1-0-1服务端是可以了，但APP端又得转下格式，怎么都有点别扭；

2）这个路由配得太死，1.0.1就是1.0.1的路由，APP端带1.0.2来就调不通。实际场景中后端没法完全对应APP版本，APP甚至连审核不通过重新提交都需要修改版本号，后端必须能向前兼容；

3）最后一个问题最致命：方法不可以复用，1.0.1版本的UserController里写了10个方法，1.0.2版只改了其中1个方法，还得把其他9个方法都原样搬过来。

理想的效果应该是这样：APP请求接口的时候把版本号（这个版本号就是上架各大商店的版本号）放到请求header里，服务端根据版本号找控制器，找到了直接调用，没有的话就向前找；同时方法也要向前找，带着这些需求寻找解决方案。

versioning

找下网络上的方案，aspnet-api-versioning用的最多，原来不止我一个人有这个需求。这个Versioning是微软出的，同时支持Core，简直靠谱，建个Web API项目试试

NuGet安装

Web API：Install-Package Microsoft.AspNet.WebApi.Versioning

Core：Install-Package Microsoft.AspNetCore.Mvc.Versioning

修改WebApiConfig.cs

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.MapHttpAttributeRoutes();

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{action}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );

        config.AddApiVersioning(c =>
        {
            c.ReportApiVersions = true;//是否在请求头中返回受支持的版本信息
            c.ApiVersionReader = new HeaderApiVersionReader("version");//header里版本号的键名
            c.AssumeDefaultVersionWhenUnspecified = true;//请求没有指明版本的情况下是否使用默认的版本
            c.DefaultApiVersion = new ApiVersion(, );//默认的版本号
        });
    }
}

新建两个UserController

代码

namespace webApiVersioning.Controllers.v1
{
    [ApiVersion("1.0")]
    public class UserController : ApiController
    {
        [HttpGet]
        public string Get()
        {
            return "1.0";
        }
    }
}

namespace webApiVersioning.Controllers.v2
{
    [ApiVersion("2.0")]
    public class UserController : ApiController
    {
        [HttpGet]
        public string Get()
        {
            return "2.0";
        }
    }
}

header里version分别传1.0和2.0效果如下

 

从输出来看，前端调用相同的接口，通过传递不同的version参数触发了服务端不同控制器的方法。但是缺点明显：

1）版本号没法配置成三段式的，现在所有商店里APP的版本都是三段式的；

2）跟上面的路由方案一样，没法向前找控制器。verson传3.0，不会自动找到2.0的控制器，不够灵活；

3）更不支持向前找方法。。。

终极方案

微软出的Versioning既然不能满足需求就自己实现一个，难点就一个：根据APP端传来的版本号触发对应的控制器。

版本号好获取，控制器也可以建个User{version}Controller，那怎么做到APP端带101的版本号请求UserController，服务端根据传的101自动转到UserController呢？

利用搜索引擎找到了System.Web.Http.Dispatcher命名空间下的DefaultHttpControllerSelector类，下面有个GetControllerName方法

// 摘要:
//     获取指定 System.Net.Http.HttpRequestMessage 的控制器的名称。
//
// 参数:
//   request:
//     HTTP 请求消息。
//
// 返回结果:
//     指定 System.Net.Http.HttpRequestMessage 的控制器的名称。
public virtual string GetControllerName(HttpRequestMessage request)

根据请求request获取指定控制器名称，那岂不是可以请求UserController，实际触发User101Controller了。建一个CustomHeaderControllerSelector继承DefaultHttpControllerSelector类，重写下GetControllerName方法试一试

public class CustomHeaderControllerSelector : DefaultHttpControllerSelector
{
    public CustomHeaderControllerSelector(HttpConfiguration cfg) : base(cfg)
    { }

    public override string GetControllerName(HttpRequestMessage request)
    {
        var controllerRequest = base.GetControllerName(request);//User
        return controllerRequest + "";//User101
    }
}

注册到Global.asax里

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
        GlobalConfiguration.Configuration.Services.Replace(typeof(IHttpControllerSelector), new CustomHeaderControllerSelector(GlobalConfiguration.Configuration));
    }
}

新建一个User101Controller

public class User101Controller : ApiController
{
    [HttpGet]
    public string UserInfo()
    {
        return "";
    }
}

项目里并没有UserController，请求下试试

可以看出，请求的是UserController，触发的是User101Controller，完美了。再建一个User102Controller

public class User102Controller : ApiController
{
    [HttpGet]
    public string UserInfo()
    {
        return "";
    }
}

完善下GetControllerName方法

public override string GetControllerName(HttpRequestMessage request)
{
    var controllerRequest = base.GetControllerName(request);
    if (request.Headers.Contains("version"))
    {
        var headerVersion = request.Headers.GetValues("version").First();
        if (string.IsNullOrEmpty(headerVersion))
            return controllerRequest;
        else
            return controllerRequest + headerVersion.Replace(".", "");
    }
    return controllerRequest;
}

分别请求下试试

至此，已经实现了和微软的Versioning一模一样的功能，并且还支持了三段式的版本号。

下一个问题：如何向前找控制器？例：APP版本号到了1.0.2，但是1.0.2这个版本服务端只改了一个控制器的，大部分控制器都没有1.0.2版，如何调用1.0.2实际触发1.0.1呢？

场景：APP 1.0.1版上线，服务端有两个控制器 User101Controller、Employee101Controller。1.0.2版User控制器有接口变化，加了一个User102Controller，Employee控制器无变化不加，1.0.2上线后服务端就有3个控制器了，APP端调所有接口传的都是当前版本号1.0.2，访问User触发的是UserController，访问Employee触发的是EmployeeController，这就是所谓的向前兼容。

如何实现呢？还是在GetControllerName方法里做文章

如图DefaultHttpControllerSelector里还有另一个虚方法GetControllerMapping，这个方法可以获取当前项目里所有的控制器名称。这就简单了：获取到的是User101、User102，如果请求来的是User102直接返回User102，如果请求来的是User103，那么挨个比大小，还是返回User102。此方法可行，但是思考了一下，每次请求过来都要做如下操作：

1）获取项目所有控制器；

2）截取控制器名称后的版本号；

3）排序；

4）比大小。

步骤多，有点浪费性能，而且还容易出错。直接使用配置的方式，只比大小，其他步骤都省略。新建PublicConst.cs，把项目所有的控制器和对应的版本号都写到VersionList这个全局变量里

public class PublicConst
{
    public static List<Vsn> VersionList
    {
        get
        {
            return new List<Vsn>()
            {
                //注：版本必须【由小到大】添加
                new Vsn() { Controller = "User", Ver = "1.0.1" },
                new Vsn() { Controller = "User", Ver = "1.0.2" },
            };
        }
    }
}

public class Vsn
{
    public string Controller { get; set; }
    public string Ver { get; set; }
}

现在请求过来是1.0.3，从配置里拿到了1.0.1和1.0.2，常规做法是根据“.”分割，然后挨个比数字大小，还要考虑4段、5段以及段数不一样的版本号比大小，这样代码写着就没边了，还容易出bug。System命名空间下有Version类，调方法就可以比大小，用起来

public static string CompareVersion(string version, List<string> vsns)
{
    var newestVersion = string.Empty;
    if (string.IsNullOrEmpty(version) || vsns.Count == )
    {
        return newestVersion;
    }

    Version verCurrent = new Version(version);
    for (int i = vsns.Count - ; i >= ; i--)//倒叙查提高效率：新版的用户比老用户多
    {
        if (verCurrent >= new Version(vsns[i]))
        {
            newestVersion = vsns[i];
            break;
        }
    }
    return newestVersion;
}

按照上面的思路继续改造下GetControllerName方法

public override string GetControllerName(HttpRequestMessage request)
{
    var controllerRequest = base.GetControllerName(request);
    var controllerWithVersion = controllerRequest;
    if (request.Headers.Contains("version"))
    {
        var headerVersion = request.Headers.GetValues("version").First();
        if (!string.IsNullOrEmpty(headerVersion))
        {
            controllerWithVersion = controllerRequest + headerVersion.Replace(".", "");
            if (!GetControllerMapping().ContainsKey(controllerWithVersion))
            {
                var lsVersion = PublicConst.VersionList.Where(x => x.Controller == controllerRequest).ToList().ConvertAll(t => t.Ver);
                var newestVersion = Utils.CompareVersion(headerVersion, lsVersion);
                if (!string.IsNullOrEmpty(newestVersion))
                    controllerWithVersion = controllerRequest + newestVersion.Replace(".", "");
                else
                    controllerWithVersion = controllerRequest;
            }
        }
    }
    return controllerWithVersion;
}

调用试试

由图可见，已经能向前找控制器了。还剩一个问题：如何向前找方法？场景：APP已经更新到1.0.3了，但是有一个方法一直没有修改，还在1.0.1的控制器里面，1.0.2里面都没有这个方法。这个时候直接调1.0.3的控制器可以定位到1.0.2控制器没问题，但是1.0.2控制器下没有这个方法，如何转到1.0.1控制器，并调用其下面的这个方法呢？

回头看看刚才的接口配置对象VersionList

public static List<Vsn> VersionList
{
    get
    {
        return new List<Vsn>()
        {
            //注：版本必须【由小到大】添加
            new Vsn() { Controller = "User", Ver = "1.0.1" },
            new Vsn() { Controller = "User", Ver = "1.0.2" },
        };
    }
}

在这个里面配置每个版本控制器里面包含的方法，每次对比版本的时候判断下方法是否存在即可

public static List<Vsn> VersionList
{
    get
    {
        return new List<Vsn>()
        {
            //注：版本必须【由小到大】添加
            new Vsn() { Controller = "User", Ver = "1.0.1", Actions = new List<string>(){ "Get","Test"} },
　　　　　　  new Vsn() { Controller = "User", Ver = "1.0.2", Actions = new List<string>(){ "Get"} }, 
　　 　　}; 
　　} 
}

弊端：方法多了，维护太费劲，怎么能实现自动向前找方法呢？这里就要返璞归真了，想想面向对象三大特征：继承、封装和多态

使用继承的方式即可。第一个版本全是虚方法，后面每个版本继承上一个版本，如果接口有修改就override上一个版本的接口即可。

User101Controller代码：

public class User101Controller : ApiController
{
    [HttpGet]
    public virtual string UserInfo()
    {
        return "";
    }

    [HttpGet]
    public virtual string Test()
    {
        return "Test:101";
    }
}

User102Controller代码：

public class User102Controller : User101Controller
{
    [HttpGet]
    public override string UserInfo()
    {
        return "";
    }
}

请求下试试

根据VersionList维护的版本号，没有User103就找User102，但是User102下面并没有Test方法，Test方法在User101下面，这个时候由于User102继承了User101，也可以找到User101下的Test方法。

APP 1.0.3版本User控制器没有变化就不建控制器，1.0.4的时候User控制器加了一个Test2方法继续virtual，等待被下一个版本override

public class User104Controller : User102Controller
{
    [HttpGet]
    public virtual string Test2()
    {
        return "Test2:104";
    }
}

记得维护到VersionList里

public static List<Vsn> VersionList
{
    get
    {
        return new List<Vsn>()
        {
            //注：版本必须【由小到大】添加
            new Vsn() { Controller = "User", Ver = "1.0.1" },
            new Vsn() { Controller = "User", Ver = "1.0.2" },
            new Vsn() { Controller = "User", Ver = "1.0.4" },
        };
    }
}

看下最终成果

至此，大功告成。

以上是我的方案，仅抛砖引玉，欢迎大家补充。 本文地址：https://www.cnblogs.com/oppoic/p/13367878.html

思考

看下核心的GetControllerName方法

 public override string GetControllerName(HttpRequestMessage request)
 {
     var controllerRequest = base.GetControllerName(request);
     var controllerWithVersion = controllerRequest;
     if (request.Headers.Contains("version"))
     {
         var headerVersion = request.Headers.GetValues("version").First();
         if (!string.IsNullOrEmpty(headerVersion))
         {
             controllerWithVersion = controllerRequest + headerVersion.Replace(".", "");
             if (!GetControllerMapping().ContainsKey(controllerWithVersion))
             {
                 var lsVersion = PublicConst.VersionList.Where(x => x.Controller == controllerRequest).ToList().ConvertAll(t => t.Ver);
                 var newestVersion = Utils.CompareVersion(headerVersion, lsVersion);
                 if (!string.IsNullOrEmpty(newestVersion))
                     controllerWithVersion = controllerRequest + newestVersion.Replace(".", "");
                 else
                     controllerWithVersion = controllerRequest;
             }
         }
     }
     return controllerWithVersion;
 }

本方案向前找控制器是通过对比版本大小实现的，如果接口访问频率超高（比如APP日活百万），有个优化方案：看看上面代码11行，如果当前请求的控制器不存在就向前找，把线上APP最新版本的控制器都建一遍，直接继承上一个控制器，不需要重写任何方法，这样就不用对比版本了，提升了性能。

另外再看版本号维护类VersionList

public static List<Vsn> VersionList
{
    get
    {
        return new List<Vsn>()
        {
            //注：版本必须【由小到大】添加
            new Vsn() { Controller = "User", Ver = "1.0.1" },
            new Vsn() { Controller = "User", Ver = "1.0.2" },
            new Vsn() { Controller = "User", Ver = "1.0.4" },
        };
    }
}

版本号对比是挨个对比，没法集中对比，所以必须按顺序维护起来，但是如果哪天粗心搞错了，或者添加了重复的版本号怎么处理？在Application_Start项目启动的时候检测下这个VersionList即可。

最后说下版本号，UserCotroller到底表示哪个版本？11.1.0还是1.11.0，这块也可以优化下，建成User1_11_0Controller就可以了。

环境

Visual Studio 2017  .NET Framework 4.5.2  Web API

参考

https://www.cnblogs.com/linhuiy/p/12668535.html

https://www.dotnetcurry.com/aspnet/1185/aspnet-web-api-versioning-angularjs-app

https://github.com/aspnet/AspNetWebStack/blob/master/src/System.Web.Http/Dispatcher/DefaultHttpControllerSelector.cs