如何在ASP.NET Core中使用API版本控制

最新推荐文章于 2025-10-17 00:57:27 发布

翻译最新推荐文章于 2025-10-17 00:57:27 发布 · 342 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：https://www.infoworld.com/article/3562355/how-to-use-api-versioning-in-aspnet-core.html

文章标签：

#java #vue #linux #c# #python #ViewUI

本文详细介绍了在ASP.NET Core中实现API版本控制的方法，包括安装和配置版本控制包、在控制器中使用版本属性，以及如何通过查询字符串、HTTP头或URL传递版本信息。

在开发API时，应牢记一件事：改变是不可避免的。当API达到需要添加更多职责的程度时，应考虑对API进行版本控制。因此，您将需要一个版本控制策略。

有几种版本控制API的方法，每种方法各有利弊。本文将讨论API版本控制的挑战，以及如何使用Microsoft的ASP.NET Core MVC版本软件包对ASP.NET Core中内置的RESTful API版本进行处理。您可以在上一篇文章中阅读有关Web API版本控制的更多信息。

[ 同样在InfoWorld上：Visual Studio Code与Visual Studio：如何选择 ]

创建一个ASP.NET Core 3.1 API项目

首先，让我们在Visual Studio中创建一个ASP.NET Core项目。假设系统中已安装Visual Studio 2019，请按照以下概述的步骤在Visual Studio中创建一个新的ASP.NET Core项目。

启动Visual Studio IDE。
点击“创建新项目”。
在“创建新项目”窗口中，从显示的模板列表中选择“ ASP.NET Core Web应用程序”。
点击下一步。
在接下来显示的“配置新项目”窗口中，指定新项目的名称和位置。
单击创建。
在“创建新的ASP.NET Core Web应用程序”窗口中，从顶部的下拉列表中选择.NET Core作为运行时，并选择ASP.NET Core 3.1（或更高版本）。我将在这里使用ASP.NET Core 3.1。
选择“ API”作为项目模板以创建新的ASP.NET Core API应用程序。
确保未选中“启用Docker支持”和“配置HTTPS”复选框，因为我们此处将不使用这些功能。
确保将身份验证设置为“无身份验证”，因为我们也不会使用身份验证。
单击创建。

这将在Visual Studio中创建一个新的ASP.NET Core API项目。在“解决方案资源管理器”窗口中选择Controllers解决方案文件夹，然后单击“添加-> Controller…”以创建一个名为DefaultController的新控制器。

用以下代码替换DefaultController类的源代码。

[Route("api/[controller]")]
    [ApiController]
    public class DefaultController : ControllerBase
    {
        string[] authors = new string[]
        { "Joydip Kanjilal", "Steve Smith", "Stephen Jones" };
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return authors;
        }
    }

我们将在本文的后续部分中使用此控制器。

要在ASP.NET Core中实现API版本控制，您需要执行以下操作：

安装ASP.NET Core MVC版本控制包。
在启动类中配置API版本控制。
用适当的属性注释控制器和动作。

安装ASP.NET Core MVC版本控制包

ASP.NET Core开箱即用地支持API版本控制。要利用API版本控制，您所需要做的就是从NuGet安装Microsoft.AspNetCore.Mvc.Versioning程序包。您可以通过Visual Studio 2019 IDE中的NuGet包管理器来执行此操作，也可以通过在NuGet包管理器控制台上执行以下命令来执行此操作：

Install-Package Microsoft.AspNetCore.Mvc.Versioning

请注意，如果您使用的是ASP.NET Web API，则应添加Microsoft.AspNet.WebApi.Versioning程序包。

在ASP.NET Core中配置API版本控制

现在，已经在项目中安装了用于对API进行版本控制的必需软件包，您可以在Startup类的ConfigureServices方法中配置API的版本控制。以下代码段说明了如何实现此目的。

public void ConfigureServices(IServiceCollection services)
{
  services.AddControllers();
  services.AddApiVersioning();
}

当您向API发出Get请求时，将出现如图1所示的错误。

要解决此错误，可以在将API版本控制服务添加到容器时指定默认版本。如果未在请求中指定版本，则可能还需要使用默认版本。以下代码段显示了如果请求中没有可用的版本信息，则如何使用AssumeDefaultVersionWhenUnspecified属性将默认版本设置为1.0。

services.AddApiVersioning(config =>
{
   config.DefaultApiVersion = new ApiVersion(1, 0);
   config.AssumeDefaultVersionWhenUnspecified = true;
});

请注意，在分配默认版本时，主要版本和次要版本如何传递给ApiVersion类的构造函数。属性AssumeDefaultVersionWhenUnspecified可以包含true或false值。如果为true，则在没有可用版本信息的情况下，将使用配置API版本控制时指定的默认版本。

下面提供ConfigureServices方法的完整源代码，以供您参考。

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddApiVersioning(config =>
    {
         config.DefaultApiVersion = new ApiVersion(1, 0);
         config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

由于您未指定任何版本信息，因此所有端点的默认版本均为1.0。

报告您的API支持的所有版本

您可能想让API的客户端知道所有受支持的版本。为此，您应该利用ReportApiVersions属性，如下面给出的代码片段所示。

services.AddApiVersioning(config =>
{
  config.DefaultApiVersion = new ApiVersion(1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
});

在控制器中使用版本和操作方法

现在，我们使用属性添加一些受支持的版本到我们的控制器，如下面的代码片段所示。

[Route("api/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    [ApiVersion("2.0")]
    public class DefaultController : ControllerBase
    {
        string[] authors = new string[]
        { "Joydip Kanjilal", "Steve Smith", "Anand John" };
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return authors;
        }
    }

当您从HTTP客户端（例如Postman）发出Get请求时，将按照以下方式报告版本。

您也可以报告已弃用的版本。为此，您应该将一个额外的参数传递给ApiVersion方法，如下面给出的代码片段所示。

[ApiVersion("1.0", Deprecated = true)]

映射到特定版本的操作方法

还有一个重要的属性，名为MapToApiVersion。您可以使用它来映射到特定版本的操作方法。以下代码片段显示了如何实现此目的。

[HttpGet("{id}")]
[MapToApiVersion("2.0")]
public string Get(int id)
{
   return authors[id];
}

ASP.NET Core中的完整API版本控制示例

这是DefaultController的完整源代码供您参考。

[Route("api/[controller]")]
[ApiController]
[ApiVersion("1.0")]
[ApiVersion("1.1")]
[ApiVersion("2.0")]
public class DefaultController : ControllerBase
{
  string[] authors = new string[]
  { "Joydip Kanjilal", "Steve Smith", "Stephen Jones" };
  [HttpGet]
  public IEnumerable<string> Get()
  {
      return authors;
  }
  [HttpGet("{id}")]
  [MapToApiVersion("2.0")]
  public string Get(int id)
  {
     return authors[id];
  }
}

ASP.NET Core中的API版本控制策略

您可以通过多种方式在ASP.NET Core中对API进行版本控制。在本节中，我们将探讨它们中的每一个。

将版本信息作为QueryString参数传递

在这种情况下，通常将版本信息作为查询字符串的一部分传递，如下面给出的URL所示。

http://localhost:25718/api/default?api-version=1.0

在HTTP标头中传递版本信息

如果要在HTTP标头中传递版本信息，则应在ConfigureServices方法中进行设置，如下面的代码段所示。

services.AddApiVersioning(config =>
{
   config.DefaultApiVersion = new ApiVersion(1, 0);
   config.AssumeDefaultVersionWhenUnspecified = true;
   config.ReportApiVersions = true;
   config.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

设置完成后，您可以调用与特定版本的API相关的操作方法，如图3所示。

在URL中传递版本信息

传递版本信息的另一种方法是传递版本信息作为路由的一部分。这是对API进行版本控制的最简单方法，但有一些警告。首先，如果您使用此策略，则每当发布新版本的API时，您的客户就需要更新URL。因此，此方法违反了REST的基本原则，该原则指出特定资源的URL永不更改。

要实施此版本控制策略，应在控制器中指定路由信息，如下所示。

[Route("api/v{version:apiVersion}/[controller]")]

以下代码清单显示了如何在控制器类中进行设置。

[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
[ApiVersion("1.0")]
[ApiVersion("1.1")]
public class DefaultController : ControllerBase
    {
        string[] authors = new string[]
        { "Joydip Kanjilal", "Steve Smith", "Stephen Jones" };
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return authors;
        }
        [HttpGet("{id}")]
        [MapToApiVersion("2.0")]
        public string Get(int id)
        {
            return authors[id];
        }
    }

这是如何调用默认HTTP来获取DefaultController类的方法的方法。

http://localhost:25718/api/v1.0/default

要调用其他HTTP GET方法（即接受参数的方法），请在Web浏览器或HTTP客户端（如Postman）中指定以下内容。

http://localhost:25718/api/v2.0/default/1

弃用一个或多个API版本

假设您有多个版本的API，但是您想弃用其中一个或多个。您可以轻松地完成此操作-只需将ApiVersionAttribute类的Deprecated属性指定为true即可，如下面给出的代码片段所示。

[ApiController]
[ApiVersion("1.0")]
[ApiVersion("1.1", Deprecated = true)]
[ApiVersion("2.0")]
public class DefaultController : ControllerBase
{
     //Usual code
}

由于引入了Microsoft.AspNetCore.Mvc.Versioning包，ASP.NET Core中的API版本控制现在可以无缝进行了。有几种方法可以对API进行版本控制-您只需要根据自己的需求决定最佳策略。您还可以为API使用多种版本控制方案。由于客户端可以选择任何受支持的版本控制方案，因此增加了很多灵活性。