Asp-Net-Core开发笔记：API版本管理

最新推荐文章于 2024-02-26 10:59:36 发布
最新推荐文章于 2024-02-26 10:59:36 发布
阅读量322 收藏 2
点赞数 1
文章标签： 笔记 java 开发语言
原文链接：https://mp.weixin.qq.com/s?__biz=MzAwNTMxMzg1MA==&mid=2654096807&idx=1&sn=620f2b118d61d1d00dd551f722865961&chksm=80d869f2b7afe0e4944968f0c70c575ff0fe059b62f01cf13b21ae6f81d69aa97db1b97e5110&scene=126&sessionid=0
版权

1前言

对于Web API应用程序而言，随着时间的推移以及需求的增加或改变，API必然会遇到升级的需求。事实上，Web API应用程序应该从创建时就考虑到API版本的问题。业务的调整、功能的增加、接口的移除与改名、接口参数变动、实体属性的添加、删除和更改等都会改变API的功能，从而带来版本的变更。

现有的资料大部分是使用 Microsoft.AspNetCore.Mvc.Versioning 这个包，但我实际使用的时候发现这个包早就不更新了，微软官方文档好像也没有这部分介绍，不过在这个包的nuget主页上有说已经换成新的 Asp.Versioning.Mvc 包，原来是微软改名部发力了，失敬失敬~ 😂

好在这个新的包在Github上有很详细的文档，但这改名速度实在是猛，为了实现这个功能，我走了不少弯路。😂

OK，本文基于 .Net6.0，以 AspNetCore WebApi 为例，介绍引入API版本管理的过程。

2基础

指定版本的方法有两种，既可以使用[ApiVersion]特性，也可以使用版本约定方式。当定义了不同版本的API接口后，客户端可以通过如下多种方式来访问某一版本的API。

  • 使用URL路径，如 api/v1.0/values

  • 使用查询字符串，如 api/values?api-version=1.0

  • 使用HTTP自定义消息头

  • 使用媒体类型（Media Type）参数，如 Accept: application/json;v=2.0

ASP.NET Core MVC默认的方式是使用查询字符串，查询字符串使用的参数名为api-version。具体使用哪种方式由服务端指定（用下面介绍的 ApiVersionReader 属性来配置），既可以使用其中的一种，也可以同时使用多种不同的方式。

API版本的格式由主版本号与次版本号组成，此外还可以包含可选的两部分：版本组和状态。

  • [Version Group.]<Major>.<Minor>[-Status]

  • <Version Group>[<Major>[.Minor]][-Status]

版本组的格式为YYYY-MM-DD，它能够对API接口起到逻辑分组的作用，状态则能够标识当前版本的状况，如Alpha、Beta和RC等。以下是常见的版本格式：

  • /api/foo?api-version=1.0

  • /api/foo?api-version=2.0-Alpha

  • /api/foo?api-version=2015-05-01.3.0

  • /api/v1/foo

  • /api/v2.0-Alpha/foo

  • /api/v2015-05-01.3.0/foo

本文采用 /api/v1/foo 形式

3安装依赖

需要安装这俩nuget包

  • Asp.Versioning.Mvc

  • Asp.Versioning.Mvc.ApiExplorer

4注册服务

编辑 Program.cs 文件

builder.Services.AddApiVersioning(options => {
  options.DefaultApiVersion = new ApiVersion(1, 0);
  options.AssumeDefaultVersionWhenUnspecified = true;
  options.ReportApiVersions = true;
  options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("x-api-version"),
    new MediaTypeApiVersionReader("ver")
  );
})
  .AddMvc()
  .AddApiExplorer(options => {
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
  });

以上代码做了这些事：

  • DefaultApiVersion 设置默认版本为1.0

  • AssumeDefaultVersionWhenUnspecified 没有指定版本时，使用默认版本

  • ReportApiVersions 在响应头里加上可用的接口版本

  • ApiVersionReader 定义了可以从三个地方获取接口版本信息，URL里和俩请求头

  • GroupNameFormat 指定了版本名称格式，详见下表

  • SubstituteApiVersionInUrl 因为要使用URL指定版本，所以这里设置为true

API Version Format Strings

本文中我使用的是 'v'VVV 的格式

Format SpecifierDescriptionExamples
FFull API version as [group version][.major[.minor]][-status]2017-05-01.1-RC -> 2017-05-01.1-RC
FFFull API version with optional minor version as [group version][.major[.minor,0]][-status]2017-05-01.1-RC -> 2017-05-01.1.0-RC
GGroup version as yyyy-MM-dd2017-05-01.1-RC -> 2017-05-01
GGGroup version as yyyy-MM-dd with status2017-05-01.1-RC -> 2017-05-01-RC
yGroup version year from 0 to 992001-05-01.1-RC -> 1
yyGroup version year from 00 to 992001-05-01.1-RC -> 01
yyyGroup version year with a minimum of three digits2017-05-01.1-RC -> 017
yyyyGroup version year as a four-digit number2017-05-01.1-RC -> 2017
MGroup version month from 1 through 122001-05-01.1-RC -> 5
MMGroup version month from 01 through 122001-05-01.1-RC -> 05
MMMGroup version abbreviated name of the month2001-06-01.1-RC -> Jun
MMMMGroup version full name of the month2001-06-01.1-RC -> June
dGroup version day of the month, from 1 through 312001-05-01.1-RC -> 1
ddGroup version day of the month, from 01 through 312001-05-01.1-RC -> 01
dddGroup version abbreviated name of the day of the week2001-05-01.1-RC -> Mon
ddddGroup version full name of the day of the week2001-05-01.1-RC -> Monday
vMinor version2001-05-01.1-RC -> 1 1.1 -> 1
VMajor version1.0-RC -> 1 2.0 -> 2
VVMajor and minor version1-RC -> 1 1.1-RC -> 1.1 1.1 -> 1.1
VVVMajor, optional minor version, and status1-RC -> 1-RC 1.1 -> 1.1
VVVVMajor, minor version, and status1-RC -> 1.0-RC 1.1 -> 1.1 1 -> 1.0
SStatus1.0-Beta -> Beta
pPadded minor version with default of two digits1.1 -> 01 1 -> 00
p[n]Padded minor version with N digitsp2: 1.1 -> 01 p3: 1.1 -> 001
PPadded major version with default of two digits2.1 -> 02 2 -> 02
P[n]Padded major version with N digitsP2: 2.1 -> 02 P3: 2.1 -> 002
PPPadded major and minor version with a default of two digits2.1 -> 02.01 2 -> 02.00
PPPPadded major, optional minor version, and status with a default of two digits1-RC -> 01-RC 1.1-RC -> 01.01-RC
PPPPPadded major, minor version, and status with a default of two digits1-RC -> 01.00-RC 1.1-RC -> 01.01-RC

5设置API版本

例子接口有俩版本

  • /api/v1/demo/test

  • /api/v2/demo/test

在 Controller 下创建俩目录，v1 和 v2，然后分别创建Controller

上代码 Controllers/v1/DemoController.cs

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion(1.0)]
[ApiController]
public class DemoController : ControllerBase {
  [HttpGet("[action]")]
  public ApiResponse Test() {
    return ApiResponse.Ok("version=1.0");
  }
}

另一个版本的接口 Controllers/v2/DemoController.cs

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion(2.0)]
[ApiController]
public class DemoController : ControllerBase {
  [HttpGet("[action]")]
  public ApiResponse Test() {
    return ApiResponse.Ok("version=2.0");
  }
}

可以看到要区分不同版本的接口，只需要添加 [ApiVersion(2.0)] 特性即可。

因为我要使用URL来选择不同版本的接口，所以要把路由配置为 "api/v{version:apiVersion}/[controller]"

如果不把版本号写在URL里，也可以用请求参数传递，比如 /api/demo/test?api-version=1.0

这些可以在 ApiVersionReader 属性配置

6配置Swagger

swagger基本已经是接口文档的标准了，但我发现很多文章都没有介绍swagger这块。（还好官方文档没有忘记）

首先创建一个配置类

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions> {
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) =>
    this.provider = provider;

  public void Configure(SwaggerGenOptions options) {
    foreach (var description in provider.ApiVersionDescriptions) {
      options.SwaggerDoc(
        description.GroupName,
        new OpenApiInfo() {
          Title = $"Example API {description.ApiVersion}",
          Version = description.ApiVersion.ToString(),
        });
    }
  }
}

注册服务

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

配置中间件

app.UseSwagger();
app.UseSwaggerUI(options => {
    foreach (var description in app.DescribeApiVersions()) {
        var url = $"/swagger/{description.GroupName}/swagger.json";
        var name = description.GroupName.ToUpperInvariant();
        options.SwaggerEndpoint(url, name);
    }
});

7效果 & 测试

搞定，访问swagger文档，在右上角接口分组可以看到不同版本

ba1c8ee8b93a0f18353a18795ef67722.png

请求 https://localhost:7053/api/v1/Demo/Test

接口返回

{
  "statusCode": 200,
  "successful": true,
  "message": "version=1.0",
  "data": null,
  "errorData": null
}

请求 https://localhost:7053/api/v2/Demo/Test

接口返回

{
  "statusCode": 200,
  "successful": true,
  "message": "version=2.0",
  "data": null,
  "errorData": null
}

不错~ 😃

8参考资料

  • https://github.com/dotnet/aspnet-api-versioning/wiki

dotNET跨平台
关注
  • 1
    点赞
  • 踩
  • 2
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
asp-net-interview-questions：:purple_circle:ASP.NET编码开发人员的访谈问答
02-04
asp-net-interview-questions：:purple_circle:ASP.NET编码开发人员的访谈问答
AdminLTE-ASP-NET-MVC：漂亮的AdminLTE模板的Asp.Net示例版本
02-05
ASP.NET MVC版本此仓库提供完整的AdminLTE ASP.NET MVC版本，包括AdminLTEHTML / JavaScript版本提供的所有演示页面，例如： 仪表板布局小部件图表UI元素形式桌子日历邮箱例子多层次开发工具与环境我正在将Visual ...
ASP.Net Core Web API结合Entity Framework Core框架（API的创建使用，接口前端权限设置，前端获取API的Get,post方法）（程序包引用以及导入数据库）
qq_48492162的博客
07-05 3016
Microsoft.EntityFrameworkCore.SqlServer （适用于EF Core SQL Server 提供程序）Microsoft.EntityFrameworkCore.Design（适用于EF Core .NET Core CLI 工具 ）Microsoft.EntityFrameworkCore.Tools（适用于 EF Core 的包管理器控制台工具）视图 ——其他窗口——程序包管理器控制台 输入以下指令，将数据库中的表导入程序中。
​​​​​​​​​​​​​​.NET Core Web API架构+应用场景+实例
最新发布
赵玉的专栏
02-26 2884
.NET Core Web API 非常适合设计 RESTful 风格的 API，这些 API 遵循 HTTP 协议，使用 URI 来标识资源，并通过不同的 HTTP 方法（GET、POST、PUT、DELETE 等）来操作资源。：.NET Core Web API 提供了强大的验证和授权机制，以确保 API 请求的数据有效性和安全性。：对于需要暴露数据给多个客户端（如 Web、移动、桌面应用等）的应用程序，.NET Core Web API 可以作为数据的统一入口，提供数据访问和操作的功能。
asp.net 带有版本控制的 API 接口实现 Microsoft.AspNetCore.Mvc.Versioning
大新软件老杨
03-21 607
使用 Versioning 之前，需要在我们的 API 项目中添加对于该 dll 的引用。这里需要注意下安装的版本问题，因为 Grapefruit.VuCore 这个框架距离现在搭建也有几个月的时间了，在这个月初的时候 .NET Core 2.2 也已经发布了，如果你和我一样还是采用的 .NET Core 2.1 版本的话，这里安装的 Versioning 版本最高只能到 2.3。 Install-Package Microsoft.AspNetCore.Mvc.Versioning 　　当我们安装完
Api接口版本管理实现
qq_38245668的博客
04-02 982
最终的实现类可能是针对以下情况之一：路径匹配，头部匹配，请求参数匹配，可产生MIME匹配，可消费MIME匹配，请求方法匹配，或者是以上各种情况的匹配条件的一个组合。日常Api接口开发中，接口的变动时有发生，同时老接口保留逻辑，这时需要对接口进行版本标记；或此接口对外暴露，而后接口地址映射发生改变，此时不想调用方做出调整，可将老接口地址映射到新接口的处理逻辑中。接口，版本匹配规则为：调用方未指明版本，使用最新版本；调用方指定版本，使用 小于等于此版本接口中最接近的版本接口。返回版本 1 的数据，符合预期。
实现 ASP.NET Core WebApi 的版本化
刘联其的个人分享
01-05 268
Web API 的版本化可以尽量保证在相同url情况下保留一个 api 的多个版本，通常一个 webapi 会有多个client，这些client包括：app，web，html5，crawl 等等同构或者异构的平台，当 api 升级之后，往往升级前的 api 也得保留，当维护两个api的时候就是一个不小的挑战，毕竟还是存在一些 client 用户需要访问老的api，这时候就需要将 webapi 版本化。 安装 Versioning 包 要想使用 webapi 的版本化功能，需要用 nuget...
aspnet-webapi-azure-deploy:ASP.NET Web API Azure部署
03-25
ASP.NET Web API Azure部署 通过GitHub动作将ASP.NET Web API部署到Azure Web应用程序。 脚步： 使用两个新的API和一个Web应用程序创建一个新的解决方案。 创建一些测试。 推送至GitHub。 在Azure中为两个API...
auth0-aspnetcore-webapi-samples：ASP.NET Core WebAPI服务的Auth0集成示例
01-30
ASP.NET Core Web API的快速入门示例此存储库包含的源代码请参阅快速入门本身，或查看各个文件夹中的自述文件以了解更多信息。
QRCoder-implemented-in-ASP.NET-Core:在ASP.NET Core中实现的QRCoder
05-24
在ASP.NET Core中实现的QRCoder 在ASP.NET Core中实现的QRCoder 该存储库是为希望在其应用程序中生成QRCode的任何人创建的。 我已经对其进行了测试，可以与ASP.NET Core MVC 2.0、2.2、3.1和5.0完美配合 我还在...
asp-net学习笔记.pdf
11-17
asp-net学习笔记.pdf
asp-net学习笔记(20220104215217).pdf
11-17
asp-net学习笔记(20220104215217).pdf
aspnet-core-jwt-authentication-api：ASP.NET Core 2.2 JWT身份验证API
01-30
aspnet-core-jwt-authentication-api ASP.NET Core 2.2-JWT身份验证API 有关文档和说明，请访问
asp-net-core-vue-starter：ASP.NET Core + Vue.js入门项目
02-06
该模板在ASP.NET Core 5.0上运行，由Vue CLI 4.0创建，具有基于插件的新体系结构，允许开发人员仅用一个命令就可以交互式地构建新项目。 提供如何创建入门模板的原始文章。 对于ASP.NET Core 3.1模板，请使用 ...
auth0-aspnet-owin-webapi-samples：用于ASP.NET OWIN Web API服务的Auth0集成示例
01-30
auth0-aspnet-owin-webapi-sample ASP.NET（OWIN）Web API的快速入门示例
WebAPI 的多版本管理
Fanbin168的专栏
06-13 2960
什么是API 的多版本问题？Android 等App 存在着多版本客户端共存的问题：App 最新版已经升级到了5.0了，但是有的用户手机上还运行着4.8、3.9甚至2.2版本的App，由于早期没有内置升级机制、用户不会升级、用户拒绝升级等原因，造成这些旧版本App也在运行。开发新版本App的时候，要给接口增加新的功能或者修改以前接口的规范，会造成旧版本App无法使用，因此在一定情况下会“保留旧接口...
ASP.NET Core Web API基础
qq_71012549的博客
12-26 990
MVC 模式代表 Model-View-Controller（模型-视图-控制器） 模式。这种模式用于应用程序的分层开发。Controller层Models层view层运行结果当修改代码显示在浏览器上第一种方法：点击调试--》生成代码不调试（点一次）--》点击生成--》生成解决方案（每改变一次代码点击一次）第二种方法：点击这个图标（热重载）但有个缺点不适合太复杂的代码的改变例如新增或删除一个方法。
ApiVersion接口版本管理
qq_41777392的博客
07-21 704
经测试，将两个方法定义的顺序交换，该api版本变为v15，也就是原api管理的代码没有实现识别最新版本接口的功能（应完善ApiVersionRequestMappingHandlerMapping类）。这样注册时/{version}/pub的version被设置为v16，latestVersion为yaml配置中config.api.version的值，version为实际请求的值。请求url中带的version，在conpareVersion中该变量名为version。请求url：/v18/pub。
Invalid non-ASCII or control character in header: 0x8BBE ASP.NET Core 文件下载报错
02-07
这个错误通常是由于你在下载文件时使用了无效的非 ASCII 或控制字符造成的。 ASP.NET Core 应用程序通常是通过 HTTP 协议与浏览器进行通信的，而 HTTP 协议中的报文头是使用 ASCII 编码的。如果你在报文头中使用了无效的字符，例如 0x8BBE 这个字符，就会导致这个错误。 要解决这个问题，你需要检查你的代码，确保不在报文头中使用无效的字符。另外，你还可以尝试使用 HttpUtility.UrlEncode 方法来编码你的报文头，这样可以避免使用无效的字符。 例如： string headerValue = HttpUtility.UrlEncode("Header value with invalid characters"); response.Headers.Add("MyHeader", headerValue); 这样就可以避免使用无效的字符，并且可以正常下载文件了。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值