ASP.NET Core 3.0 實戰：構建多版本 API 接口

本文轉載自查看原文 2019-01-05 18:34 3969 .Net Core/ Swagger/ Microsoft.AsoNetCore.Mvc.Versioning/ API/ Asp.Net

第一次在博客寫分享，請多多捧場，如有歧義請多多包含！

因為業務需求發展需要，所以API接口的變更升級是必不可少的事情，而原有的接口是不可能馬上停止使用的。例如：Login接口為例，1.0版本之返回用戶的基本信息，而2.0版本的迭代下，要把用戶祖宗十八代信息都要返回到客戶端，這時候1.0 vs 2.0版本的返回信息有一點信息上的差異，如果在不進行版本控制的情況下，在原1.0的版本下優化，那么會出現一個比較嚴重的問題，如果還有在使用原1.0版本的終端豈不是GG了，所以如何能魚與熊掌兼得，同時為1.0、2.0版本的終端考慮，所以一般常見的幾種解決方案如下：

1、使用不同API名稱（常見同時最為惡心）

這種是非常簡單粗暴，非靈活處理方案，例如：1.0=Login 2.0=NewLogin 相對於來說是可以有效兼顧到各版本的終端用戶，但是還是不夠靈活，可配置度有點低。

1.0版本 https://****.com/Login

2.0版本 https://****.com/NewLogin

2、請求時帶參數（這里就不詳細說了）

1.0版本 https://****.com/Login?version=1

2.0版本 https://****.com/Login?version=2

3、Header中標識版本信息

終端調用API接口時，在Header中添加參數來表明請求的版本信息

4、在URL中標識版本信息

1.0版本 https://****.com/v1/Login

2.0版本 https://****.com/v2/Login

這里主要介紹的是第四種方案的項目搭建（網上有很多類似的文章描述）

1、建立web api項目

2、NuGet集成以下組件

SwashBuckle.AspNetCore 4.0.1

Microsoft.AspNetCore.Mvc.Versioning 3.1.1

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 3.1.0

Microsoft.Extensions.PlatformAbstractions1.1.0 （選擇性集成，如果不需要API XMl文檔生成的可以去除）

以上組件的描述、作用請各位google、baidu下去了解，這里不詳細說明了

3、項目、代碼上的設置/改動

在Startup->ConfigureServices方法中添加以下代碼

　　　　　　　services.AddApiVersioning((o) =>
            {
                o.ReportApiVersions = true;//可選配置，設置為true時，header返回版本信息
                o.DefaultApiVersion = new ApiVersion(1, 0);//默認版本，請求未指明版本的求默認認執行版本1.0的API
                o.AssumeDefaultVersionWhenUnspecified = true;//是否啟用未指明版本API，指向默認版本
            }).AddVersionedApiExplorer(option =>
            {
                option.GroupNameFormat = "'v'VVVV";//api組名格式
                option.AssumeDefaultVersionWhenUnspecified = true;//是否提供API版本服務
            }).AddSwaggerGen((s) =>
            {
                //填充UI內容
                var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
                foreach (var description in provider.ApiVersionDescriptions)
                {
                    s.SwaggerDoc(description.GroupName,
                         new Info()
                         {
                             Title = $"體檢微服務接口 v{description.ApiVersion}",
                             Version = description.ApiVersion.ToString(),
                             Description = "微服務框架-切換版本請點右上角版本切換",
                             Contact = new Contact() { Name = "榮少（黎更榮） WeChat:186***** QQ:157537648", Email = "*******@hotmail.com" }
                         }
                    );
                }
                //生成API XML文檔
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml");
                s.IncludeXmlComments(xmlPath);
            });

以上代碼其中option.GroupNameFormat = "'v'VVVV";//api組名格式，各位可以嘗試玩玩~~~~

在Startup->Configure方法中添加以下代碼

            app.UseSwagger().UseSwaggerUI((o) =>
            {
                foreach (var description in provider.ApiVersionDescriptions)
                {
                    o.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
                }
            });

其中在Startup->Configure方法中缺少了IApiVersionDescriptionProvider provider參數，自己手動補上即可

//項目自動生成的版本
public void Configure(IApplicationBuilder app, IHostingEnvironment env)

//參數補上后的版本 
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)

以上配置基本上算時完成了，那么Web Api要怎么寫法呢？

在WebApi項目中Controllers下建立v1、v2倆個文件夾

namespace WebApplication1.Controllers.v1
{
    [ApiVersion("1.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "v1", "v1" };
        }
    }
}

namespace WebApplication1.Controllers.v2
{
    [ApiVersion("2.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "v2", "v2" };
        }
    }
}

這里的路由設置了配置的標簽{version:apiVersion}，其中ApiVersion中有各類的屬性字段，例如：棄用（不代表停用，就好像巨硬上已經過時的方法）該版本API-ApiVersion("1.0", Deprecated = true)]，該[ApiVersionNeutral]標簽就是表明停用，不需要該版本。

配置完成后，可以直接用url訪問不同版本的接口地址：

https://localhost:44383/api/v1/Values

https://localhost:44383/api/v2/Values

最后的配置，因為項目默認啟動的是api/Values接口地址，需要修改項目Properties->launchSettings.json