1. 程式人生 > >ASP.NET Core 3.0 實戰:構建多版本 API 介面

ASP.NET Core 3.0 實戰:構建多版本 API 介面

第一次在部落格寫分享,請多多捧場,如有歧義請多多包含! 因為業務需求發展需要,所以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=1 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

 

最終執行效果如下:

 

如果是對您有幫助,而您又比較慷概的請微信打賞下(後續回有更多的分享):