需求

API接口版本管理，對(duì)于一些規(guī)模稍大的企業(yè)應(yīng)用來(lái)說(shuō)，是經(jīng)常需要關(guān)注的一大需求。盡管我們的示例程序TodoList很簡(jiǎn)單，但是我們也可以通過(guò)這個(gè)應(yīng)用程序，來(lái)實(shí)踐一下如何管理API接口版本。

目標(biāo)

實(shí)現(xiàn)API接口版本管理。

原理與思路

要實(shí)現(xiàn)API版本管理，我們需要這個(gè)庫(kù)：Microsoft.AspNetCore.Mvc.Versioning。它提供了.NET Web項(xiàng)目接口的版本管理功能。

實(shí)現(xiàn)

添加Nuget Package并配置服務(wù)

向Api項(xiàng)目中添加Microsoft.AspNetCore.Mvc.Versioning包。并添加一個(gè)擴(kuò)展方法：

ApiServiceExtensions.cs

using Microsoft.AspNetCore.Mvc;

namespace TodoList.Api.Extensions;

public static class ApiServiceExtensions
{
    public static void ConfigureApiVersioning(this IServiceCollection services)
    {
        services.AddApiVersioning(options =>
        {
            // 向響應(yīng)頭中添加API版本信息
            options.ReportApiVersions = true;
            // 如果客戶端不顯式指定API版本，則使用默認(rèn)版本
            options.AssumeDefaultVersionWhenUnspecified = true;
            // 配置默認(rèn)版本為1.0
            options.DefaultApiVersion = new ApiVersion(1, 0);
        });
    }
}

在Program中調(diào)用：

Program.cs

// 省略其他...
builder.ConfigureLog();
builder.Services.ConfigureApiVersioning();

實(shí)現(xiàn)API版本控制

方法1: 添加ApiVersion屬性

我們復(fù)制一份TodoItemController到新文件TodoItemV2Controller并修改類(lèi)名和構(gòu)造函數(shù)，其他保持原樣。為了給Controller標(biāo)記對(duì)應(yīng)的API版本號(hào)，我們分別向兩個(gè)Controller上添加屬性：

[ApiVersion("2.0")]
[Route("/todo-item")]
[ApiController]
public class TodoItemV2Controller : ControllerBase
{
    private readonly IMediator _mediator;
    // 省略其他...
}

以及

[ApiVersion("1.0")]
[Route("/todo-item")]
[ApiController]
public class TodoItemController : ControllerBase
{
    private readonly IMediator _mediator;
    // 省略其他..
}

驗(yàn)證1: 請(qǐng)求中不添加任何API版本相關(guān)字段

啟動(dòng)Api項(xiàng)目，執(zhí)行查詢TodoItem的請(qǐng)求：

請(qǐng)求

-** 響應(yīng)**

日志輸出：

結(jié)果返回：

以及響應(yīng)頭信息中包含的api-supported-versions：

驗(yàn)證2: 請(qǐng)求中添加查詢字符串api-version

啟動(dòng)Api項(xiàng)目，執(zhí)行查詢TodoItem的請(qǐng)求：

請(qǐng)求

響應(yīng)

日志輸出：

結(jié)果返回（可以自己嘗試修改內(nèi)部邏輯，這里我懶了沒(méi)改實(shí)現(xiàn)，不過(guò)從日志已經(jīng)能看出請(qǐng)求確實(shí)進(jìn)入了V2版本的Controller）：

以及響應(yīng)頭信息中包含的api-supported-versions

方法2: 通過(guò)請(qǐng)求頭攜帶API版本信息

為了實(shí)現(xiàn)這一點(diǎn)，需要在ConfigureApiVersioning中增加配置：

ApiServiceExtensions.cs

// 省略其他...
// 指定請(qǐng)求頭中攜帶用于指定API版本信息的字段
options.ApiVersionReader = new HeaderApiVersionReader("api-version");

驗(yàn)證3: 通過(guò)請(qǐng)求頭攜帶API版本信息

啟動(dòng)Api項(xiàng)目，執(zhí)行查詢TodoItem的請(qǐng)求：

請(qǐng)求

響應(yīng)日志輸出：

返回結(jié)果就不繼續(xù)貼了，以及響應(yīng)頭信息中包含的api-supported-versions

方法3: 通過(guò)URL路徑訪問(wèn)對(duì)應(yīng)的版本

除了這種之外的以上幾種方法，都不需要修改接口的URI，而這種方式需要修改URI路徑。我們?cè)趦蓚€(gè)Controller上修改URI如下：

[ApiVersion("2.0")]
[Route("/{v:apiVersion}/todo-item")]
[ApiController]
// 省略其他...

驗(yàn)證4: 通過(guò)URI路徑選擇API版本

啟動(dòng)Api項(xiàng)目，執(zhí)行查詢TodoItem的請(qǐng)求：

請(qǐng)求

響應(yīng)日志輸出：

返回結(jié)果就不繼續(xù)貼了，以及響應(yīng)頭信息中包含的api-supported-versions：

一點(diǎn)擴(kuò)展

有的時(shí)候我們需要標(biāo)記一個(gè)版本的請(qǐng)求為deprecated，但是還不想完全刪除這個(gè)Controller，可以用下面的方式進(jìn)行標(biāo)記，這樣返回頭中會(huì)指出這個(gè)版本的API已經(jīng)處于deprecated狀態(tài)了。

[ApiVersion("2.0", Deprecated = true)]
[Route("/{v:apiVersion}/todo-item")]
[ApiController]
// 省略其他...

或者在ConfigureApiVersioning中使用Convention進(jìn)行標(biāo)記：

// 省略其他...
// 使用Convention標(biāo)記deprecated
options.Conventions.Controller<TodoItemV2Controller>().HasDeprecatedApiVersion(new ApiVersion(2, 0));

我們?cè)僬?qǐng)求2.0版本的API時(shí)，仍然可以獲取數(shù)據(jù)，但是得到的返回頭中信息如下：

對(duì)比使用Convention方式標(biāo)記的返回頭

總結(jié)

在本文中我們使用多種方式實(shí)現(xiàn)了管理API版本的需求，可以根據(jù)具體的需要選擇一種進(jìn)行實(shí)現(xiàn)。

以上就是.NET 6開(kāi)發(fā)TodoList應(yīng)用之實(shí)現(xiàn)API版本控制的詳細(xì)內(nèi)容，更多關(guān)于.NET 6實(shí)現(xiàn)API版本控制的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論