ASP.NET Core API 版本控制

几天前，我和我的朋友们使用 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("2.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。发现一篇同类型的文章，讲解的更详细，供大家参考：http://www.talkingdotnet.com/support-multiple-versions-of-asp-net-core-web-api/。

原文地址：http://www.cnblogs.com/tdfblog/p/asp-net-core-api-versioning.html
.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注