在C# WebAPI中实现多版本控制的方法_Asp.net

引言

随着应用程序的不断演化和功能的不断扩展，api 版本控制成为了开发和维护 webapi 时不可或缺的一部分。api 版本控制允许开发者在不破坏现有功能的情况下对 api 进行更新和优化，是实现向后兼容性和持续交付的关键。

在本文中，我们将介绍如何在现代 c# webapi 项目中有效地实施 api 版本控制，并分享一些最佳实践，帮助开发者设计、实现和维护可扩展和易于管理的 api

在 webapi 中实现多个版本，可以让你灵活管理 api 的变化，同时保持向后兼容。

第一步：安装必要的 nuget 包(选择对应的.net版本,这里我用的是.net 6)

首先，确保你的项目中已经安装了 microsoft.aspnetcore.mvc.versioning 这个 nuget 包。你可以通过 nuget 管理器或者使用以下命令安装：

第二步：创建扩展方法（addswaggergenwithversioning）

通过扩展方法来封装 swagger 多版本配置。这样可以让 program.cs 中的配置更加简洁和可复用。

创建一个 swaggerserviceextensions.cs 文件：

using asp.versioning;
using microsoft.openapi.models;
using swashbuckle.aspnetcore.swaggergen;
 
namespace myapidemo.common.extensions
{
    /// <summary>
    /// swagger服务扩展
    /// </summary>
    public static class swaggerserviceextensions
    {
        /// <summary>
        /// 控制swagger多版本生成
        /// </summary>
        /// <param name="services"></param>
        /// <param name="apiversions"></param>
        public static void addswaggergenwithversioning(this iservicecollection services, string[] apiversions)
        {
            services.addswaggergen(m =>
            {
                // xml 注释文件
                string xmlpath = path.combine(appcontext.basedirectory, "myapidemo.xml");
                if (file.exists(xmlpath))
                    m.includexmlcomments(xmlpath, true);
                // 注册每个版本
                foreach (var version in apiversions)
                {
                    m.swaggerdoc(version, new openapiinfo
                    {
                        title = $"my api {version.toupper()}",
                        version = version
                    });
                }
 
                // 冲突处理
                m.resolveconflictingactions(apidescriptions => apidescriptions.first());
 
                // 根据控制器上的 apiversionattribute 筛选文档
                m.docinclusionpredicate((docname, apidesc) =>
                {
                    if (!apidesc.trygetmethodinfo(out var methodinfo)) return false;
 
                    var versions = methodinfo.declaringtype?
                        .getcustomattributes(true)
                        .oftype<apiversionattribute>()
                        .selectmany(attr => attr.versions)
                        .select(v => $"v{v.majorversion}")
                        .tolist();
 
                    return versions?.contains(docname) ?? false;
                });
 
            });
        }
 
    }
}

第三步：配置 program.cs

在 program.cs 中进行配置，首先添加上面的扩展方法，然后配置 apiversioning 和 swagger。

完整的 program.cs 配置：

using asp.versioning;
using myapidemo.common.extensions;
 
var builder = webapplication.createbuilder(args);
 
// 添加服务到容器
builder.services.addcontrollers();
builder.services.addendpointsapiexplorer();
 
// 配置 api 版本控制
builder.services.addapiversioning(options =>
{
    options.defaultapiversion = new apiversion(1, 0); // 默认版本为 1.0
    options.assumedefaultversionwhenunspecified = true; // 未指定版本时使用默认版本
    options.reportapiversions = true; // 返回支持的版本信息
    options.apiversionreader = apiversionreader.combine(
        new querystringapiversionreader("version"), // 从查询字符串读取版本号
        new urlsegmentapiversionreader(), // 从 url 路径读取版本号
        new headerapiversionreader("x-api-version"), // 从请求头读取版本号
        new mediatypeapiversionreader("version") // 从媒体类型读取版本号
    );
});
 
// 配置 swagger 多版本生成
var apiversions = new[] { "v1", "v2" };
builder.services.addswaggergenwithversioning(apiversions);
 
var app = builder.build();
 
// 启用 swagger 和 swagger ui
app.useswagger();
app.useswaggerui(options =>
{
    foreach (var version in apiversions)
    {
        options.swaggerendpoint($"/swagger/{version}/swagger.json", $"my api {version.toupper()}");
    }
});
 
app.usehttpsredirection();
app.useauthorization();
app.mapcontrollers();
app.run();

第四步：创建版本控制的控制器

根据版本需求创建不同版本的控制器，例如：

// api v1
[apicontroller]
[route("api/v{version:apiversion}/[controller]")]
[apiversion("1.0")]
public class productscontrollerv1 : controllerbase
{
    [httpget]
    public iactionresult getproducts()
    {
        return ok(new { message = "this is version 1.0" });
    }
}
 
// api v2
[apicontroller]
[route("api/v{version:apiversion}/[controller]")]
[apiversion("2.0")]
public class productscontrollerv2 : controllerbase
{
    [httpget]
    public iactionresult getproducts()
    {
        return ok(new { message = "this is version 2.0 with new features!" });
    }
}

第五步：测试 api

运行应用程序后，访问 http://localhost:5000/swagger。
你将看到 swagger ui，能够选择 v1 或 v2 版本的 api 来进行测试

总结

api 版本控制：通过配置 addapiversioning，你可以实现路径、查询参数、请求头等多种版本控制方式，确保不同版本的 api 不会相互干扰。
swagger 配置：通过扩展方法 addswaggergenwithversioning，你可以为多个 api 版本生成 swagger 文档，并在 swagger ui 中展示不同版本的 api。

这样，你就可以轻松管理和展示多个版本的 api，同时确保 api 兼容性和安全性。

到此这篇关于在c# webapi中实现多版本控制的方法的文章就介绍到这了,更多相关c# webapi多版本控制内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！