几天前，我和我的朋友们使用 ASP.NET Core 开发了一个API ，使用的是GET方式，将一些数据返回到客户端 APP。我们在前端进行了分页，意味着我们将所有数据发送给客户端，然后进行一些data.length操作，以获得items count用于分页逻辑。为了减少HTTP请求的负荷，我们决定在后端（服务器端分页）实现逻辑。在我们这样的情况下，这是没有任何问题的，因为我们在客户端能快速实现。我们在客户端和服务端修改了所有逻辑，并且快速完成所有功能。
但是，您可能会有其他客户端在使用，因为只提供了一个数据源（API）。在一个API中引入突破性的变化可以支持一个客户端，但同时破坏了其它客户端。例如，假设您的手机团队正在度假，并且您的 Web 团队正在为了支持该服务器端分页功能开展工作。为了支持Web团队，您在API中做了一个简单的更改。这个变更，您和您的Web团队都很高兴（如果感到幸福你就拍拍手）。噩梦开始了，您会发现因为一个很简单(其实是突破性)的变化，数百万移动客户端不工作，用户会卸载APP。当您发现你们都不是移动应用程序开发人员，也没有访问源代码权限时，更多的恶梦来了。现在您只能选择降级您的 API 和 Web 应用程序，但是，Web 应用程序的开发团队现在也去度假了。因为更多的恶梦会接踵而至，所有的事情都只能停滞不前。
也许（不是也许，就是！）API版本控制是在这种情况下，是一个非常不错的选择。使用 API 版本控制，您不仅可以安全地针对这些突破性的更改，还可以支持这些更改，这对每个人都是双赢的。
我们来看一看如何在 ASP.NET Core 中配置 API 版本。
注意：我正在使用一个空的 ASP.NET Core Web API 项目（.NET Core 1.1）
通过 NuGet 安装此软件包：Microsoft.AspNetCore.Mvc.Versioning。现在，在Startup.cs类的ConfigureServices()方法中配置服务(services.AddApiVersioning())：
public void ConfigureServices(IServiceCollection services){
services.AddMvc();
services.AddApiVersioning();
}
当您使用的是Microsoft.AspNetCore.Mvc.Versioning 的1.1.1版本时，只需要使用app.UseApiVersioning()方法：
public void Configure(IApplicationBuilder app, IHostingEnvironment env,
ILoggerFactory loggerFactory){ /* garbage code removed */
app.UseMvc();
app.UseApiVersioning();
}
接下来，您必须使用ApiVersion定义要支持 API 版本控制的控制器（多个版本）。同样，您还必须使用MapToApiVersion定义特定Action API版本号：
[ApiVersion("1.0")]
[Route("api/[controller]")]public class ValuesController : Controller{ // GET api/values
[MapToApiVersion("1.0")]
[HttpGet] public IEnumerable<string> Get() { return Json(new string[] { "value1", "value2" });
}
}
现在通过GET方式的调用Action，您必须指定 API 版本，暂时使用查询字符串版本控制方式。这样，您将直接在查询字符串中指定 API 版本。例如这个：http://localhost:5000/api/values?api-version=1.0。
如果您将 API 版本控制添加到现有的API项目中，则可以告知 ASP.NET Core 将默认的控制器和Action视为版本1.0。为此，配置AddApiVersioning()服务如下所示：
services.AddApiVersioning(options => options.AssumeDefaultVersionWhenUnspecified = true);
现在可以像这样 http://localhost:5000/api/values 调用API ，不会导致任何错误。
可以通过三种方式指定API版本：
-
查询字符 （已经讨论过）
-
URL路径
-
媒体类型（Media Type）
通过URL路径的方式，您可以将版本号作为URL路径的一部分传递。像这样的例子 http://localhost:5000/api/v1/values 。顺便说一句，您必须修改您的路由属性以适应版本段，如下所示：
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]public class ValuesController : Controller{
[HttpGet, MapToApiVersion("1.0")] public IActionResult Get() { return Json(new string[] { "value1", "value2" });
}
}
请注意，字母v不是强制要添加在版本号之前，这只是一个惯例。
最后，您可以将服务配置为从特定的媒体类型（默认情况下，从content-type媒体类型读取，您可以配置自己的媒体类型）读取API版本号。如下所示，配置您的服务，以激活媒体类型版本控制：
public void ConfigureServices(IServiceCollection services){ // Add framework services.
services.AddMvc();
services.AddApiVersioning(options =>
{
options.ApiVersionReader = new MediaTypeApiVersionReader();
options.AssumeDefaultVersionWhenUnspecified = true;
options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
});
}
现在，当您发送HTTP请求时，在请求头中content-type指定API版本号，如下所示（content-type: application/json;v=2.0）：
顺便说一句，使用CurrentImplementationApiVersionSelector，如果没有在content-type媒体类型中定义版本，将使用最新的API版本。在下面的示例中，我没有提到任何版本号，所以它在所有版本中使用最新版本。
这不是全部的功能，还有其它很酷的功能，您可以在 Microsoft 的 Microsoft's ASP.NET API Versioning git存储库中找到这些功能：https://github.com/Microsoft/aspnet-api-versioning/wiki。
