欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

ASP.NET Core 3.0 实战:构建多版本 API 接口

程序员文章站 2022-08-23 21:52:00
第一次在博客写分享,请多多捧场,如有歧义请多多包含! 因为业务需求发展需要,所以API接口的变更升级是必不可少的事情,而原有的接口是不可能马上停止使用的。例如:Login接口为例,1.0版本之返回用户的基本信息,而2.0版本的迭代下,要把用户祖宗十八代信息都要返回到客户端,这时候1.0 vs 2.0 ......
第一次在博客写分享,请多多捧场,如有歧义请多多包含!
因为业务需求发展需要,所以api接口的变更升级是必不可少的事情,而原有的接口是不可能马上停止使用的。例如:login接口为例,1.0版本之返回用户的基本信息,而2.0版本的迭代下,要把用户祖宗十八代信息都要返回到客户端,这时候1.0 vs 2.0版本的返回信息有一点信息上的差异,如果在不进行版本控制的情况下,在原1.0的版本下优化,那么会出现一个比较严重的问题,如果还有在使用原1.0版本的终端岂不是gg了,所以如何能鱼与熊掌兼得,同时为1.0、2.0版本的终端考虑,所以一般常见的几种解决方案如下:
 
1、使用不同api名称(常见同时最为恶心)
这种是非常简单粗暴,非灵活处理方案,例如:1.0=login 2.0=newlogin 相对于来说是可以有效兼顾到各版本的终端用户,但是还是不够灵活,可配置度有点低。
1.0版本 https://****.com/login
2.0版本 https://****.com/newlogin
2、请求时带参数(这里就不详细说了)
1.0版本 https://****.com/login?version=1
2.0版本 https://****.com/login?version=2
3、header中标识版本信息
终端调用api接口时,在header中添加参数来表明请求的版本信息
4、在url中标识版本信息
1.0版本 https://****.com/v1/login
2.0版本 https://****.com/v2/login
 
这里主要介绍的是第四种方案的项目搭建(网上有很多类似的文章描述)
 
1、建立web api项目
ASP.NET Core 3.0 实战:构建多版本 API 接口
ASP.NET Core 3.0 实战:构建多版本 API 接口ASP.NET Core 3.0 实战:构建多版本 API 接口
 
2、nuget集成以下组件
swashbuckle.aspnetcore 4.0.1
microsoft.aspnetcore.mvc.versioning 3.1.1
microsoft.aspnetcore.mvc.versioning.apiexplorer 3.1.0
microsoft.extensions.platformabstractions1.1.0 (选择性集成,如果不需要api xml文档生成的可以去除)
以上组件的描述、作用请各位google、baidu下去了解,这里不详细说明了
 
3、项目、代码上的设置/改动
在startup->configureservices方法中添加以下代码
       services.addapiversioning((o) =>
            {
                o.reportapiversions = true;//可选配置,设置为true时,header返回版本信息
                o.defaultapiversion = new apiversion(1, 0);//默认版本,请求未指明版本的求默认认执行版本1.0的api
                o.assumedefaultversionwhenunspecified = true;//是否启用未指明版本api,指向默认版本
            }).addversionedapiexplorer(option =>
            {
                option.groupnameformat = "'v'vvvv";//api组名格式
                option.assumedefaultversionwhenunspecified = true;//是否提供api版本服务
            }).addswaggergen((s) =>
            {
                //填充ui内容
                var provider = services.buildserviceprovider().getrequiredservice<iapiversiondescriptionprovider>();
                foreach (var description in provider.apiversiondescriptions)
                {
                    s.swaggerdoc(description.groupname,
                         new info()
                         {
                             title = $"体检微服务接口 v{description.apiversion}",
                             version = description.apiversion.tostring(),
                             description = "微服务框架-切换版本请点右上角版本切换",
                             contact = new contact() { name = "荣少(黎更荣) wechat:186***** qq:157537648", email = "*******@hotmail.com" }
                         }
                    );
                }
                //生成api xml文档
                var basepath = platformservices.default.application.applicationbasepath;
                var xmlpath = path.combine(basepath, typeof(startup).gettypeinfo().assembly.getname().name + ".xml");
                s.includexmlcomments(xmlpath);
            });

以上代码其中option.groupnameformat = "'v'vvvv";//api组名格式,各位可以尝试玩玩~~~~

在startup->configure方法中添加以下代码

            app.useswagger().useswaggerui((o) =>
            {
                foreach (var description in provider.apiversiondescriptions)
                {
                    o.swaggerendpoint($"/swagger/{description.groupname}/swagger.json", description.groupname.toupperinvariant());
                }
            });

其中在startup->configure方法中缺少了iapiversiondescriptionprovider provider参数,自己手动补上即可

//项目自动生成的版本
public void configure(iapplicationbuilder app, ihostingenvironment env)

//参数补上后的版本 
public void configure(iapplicationbuilder app, ihostingenvironment env, iapiversiondescriptionprovider provider)

以上配置基本上算时完成了,那么web api要怎么写法呢?

 

在webapi项目中controllers下建立v1、v2俩个文件夹

namespace webapplication1.controllers.v1
{
    [apiversion("1.0")]
    [route("api/v{version:apiversion}/[controller]")]
    [apicontroller]
    public class valuescontroller : controllerbase
    {
        [httpget]
        public actionresult<ienumerable<string>> get()
        {
            return new string[] { "v1", "v1" };
        }
    }
}
namespace webapplication1.controllers.v2
{
    [apiversion("2.0")]
    [route("api/v{version:apiversion}/[controller]")]
    [apicontroller]
    public class valuescontroller : controllerbase
    {
        [httpget]
        public actionresult<ienumerable<string>> get()
        {
            return new string[] { "v2", "v2" };
        }
    }
}

这里的路由设置了配置的标签{version:apiversion},其中apiversion中有各类的属性字段,例如:弃用(不代表停用,就好像巨硬上已经过时的方法)该版本api-apiversion("1.0", deprecated = true)],该[apiversionneutral]标签就是表明停用,不需要该版本。

配置完成后,可以直接用url访问不同版本的接口地址:

https://localhost:44383/api/v1/values

https://localhost:44383/api/v2/values

最后的配置,因为项目默认启动的是api/values接口地址,需要修改项目properties->launchsettings.json

ASP.NET Core 3.0 实战:构建多版本 API 接口

 

最终运行效果如下:

ASP.NET Core 3.0 实战:构建多版本 API 接口

 

如果是对您有帮助,而您又比较慷概的请微信打赏下(后续会有更多的分享):

ASP.NET Core 3.0 实战:构建多版本 API 接口