.Net Core中的Api版本控制

簡介

Api的版本控制是Api開發中經常遇到的問題, 在大部分中大型項目都需要使用到Api的版本控制

在本篇博客中,我們將說明一下如何在.Net Core Api項目中使用Api版本控制。

本篇博客中測試項目的開發環境:

  • Visual Studio 2019
  • .Net Core 2.2 SDK

使用Nuget安裝Api版本控制庫

修改Startup類

       public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddApiVersioning(o => {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(2, 0); //設置默認版本
            });
        }

ReportApiVersion屬性是一個布爾類型,如果設置爲true, 在Api請求的響應頭部,會追加當前Api支持的版本

 

創建多版本Api

    [ApiVersion("1.0")]
    [Route("api/values")]
    [ApiController]
    public class ValuesV1Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "Value1 from Version 1", "value2 from Version 1" };
        }
    }

    [ApiVersion("2.0")]
    [Route("api/values")]
    [ApiController]
    public class ValuesV2Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1 from Version 2", "value2 from Version 2" };
        }
    }

 

如何在查詢字符串(Query String)中使用版本控制

如何使用路由約束中指定請求Api的版本

 

    [ApiVersion("1.0")]
    [Route("api/{v:apiVersion}/values")]
    [ApiController]
    public class ValuesV1Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "Value1 from Version 1", "value2 from Version 1" };
        }
    }

    [ApiVersion("2.0")]
    [Route("api/{v:apiVersion}/values")]
    [ApiController]
    public class ValuesV2Controller : ControllerBase
    {
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1 from Version 2", "value2 from Version 2" };
        }
    }

 

 

如何在請求頭(HTTP Header)中使用版本控制

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddApiVersioning(o => {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(2, 0); //設置默認版本
                o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");//如何在請求頭(HTTP Header)中使用傳入版本參數
            });
        }

一旦你使用o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");,
在查詢字符串中指定版本號的方式將不再可用,如果你希望同時支持2種方式,
請改用o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});

棄用Api(Deprecated)特性

有些時候,我們需要標記一些過時的Api爲棄用狀態,但是我們又不希望完全移除這個版本的Api, 我們可以使用Deprecated特性。

例:我們當前希望棄用ValuesV1Controller, 我們可以指定Deprecated特性的值爲true

header返回1.0版本的Api已經過期了,2.0版本中有相同的Api, 可以換用2.0版本的Api提示。

使用ApiVersionNeutral指定不需要版本控制的Api

    [ApiVersionNeutral]
    [Route("api/[controller]")]
    [ApiController]
    public class HealthCheckController : ControllerBase
    {
        public string Get()
        {
            return "Good";
        }
    }

 

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章