几天前,我和我的朋友们使用 ASP.NET Core 开发了一个 API ,使用的是 GET 方式,将一些数据返回到客户端 APP。我们在前端进行了分页,意味着我们将所有数据发送给客户端,然后进行一些
操作,以获得
- data.length
用于分页逻辑。为了减少 HTTP 请求的负荷,我们决定在后端(服务器端分页)实现逻辑。在我们这样的情况下,这是没有任何问题的,因为我们在客户端能快速实现。我们在客户端和服务端修改了所有逻辑,并且快速完成所有功能。
- items count
但是,您可能会有其他客户端在使用,因为只提供了一个数据源(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();
- }
接下来,您必须使用
定义要支持 API 版本控制的控制器(多个版本)。同样,您还必须使用
- ApiVersion
定义特定
- MapToApiVersion
API 版本号:
- Action
- [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
,您必须指定 API 版本,暂时使用查询字符串版本控制方式。这样,您将直接在查询字符串中指定 API 版本。例如这个:http://localhost:5000/api/values?api-version=1.0。
- Action
如果您将 API 版本控制添加到现有的 API 项目中,则可以告知 ASP.NET Core 将默认的控制器和 Action 视为版本
。为此,配置
- 1.0
服务如下所示:
- AddApiVersioning()
- services.AddApiVersioning(options = >options.AssumeDefaultVersionWhenUnspecified = true);
现在可以像这样 http://localhost:5000/api/values 调用 API ,不会导致任何错误。
可以通过三种方式指定 API 版本:
通过 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 请求时,在请求头中
指定 API 版本号,如下所示(content-type: application/json;v=2.0):
- content-type
顺便说一句,使用
,如果没有在
- CurrentImplementationApiVersionSelector
媒体类型中定义版本,将使用最新的 API 版本。在下面的示例中,我没有提到任何版本号,所以它在所有版本中使用最新版本。
- content-type
这不是全部的功能,还有其它很酷的功能,您可以在 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