当前位置:Gxl网 > 电脑问题 > 动态 WebApi 引擎使用教程(3行代码完成动态 WebApi 构建)

动态 WebApi 引擎使用教程(3行代码完成动态 WebApi 构建)

时间:2021-07-01 10:21:17 帮助过:7人阅读

目录

 

什么是 WebApiEngine?

  WebApiEngine 是一个可用于动态 WebApi 生成的引擎,基于 .NET Core(包括 .NET 5、 .NET 6),用于解决前后端分离、微服务、异步 Web 请求场景下的 WebApi 的动态生成和管理,并全面兼容 Swagger。

 

开源地址

  WebApiEngine 完全开源,可商用。承载于 Senparc.CO2NET.WebApi 库,同属于 CO2NET 开源项目:

 

使用方法

  以下是 WebApiEngine 的使用方法,将以最原始的默认 .NET Core WebApi 模板项目作为基础进行构建,以便大家学习和亲手实践。

  首先,使用 Visual Stduio 或命令行创建原始项目。

技术图片

选择 ASP.NET Core Web API 项目

 

  或使用命令行,免去创建项目的其他步骤:

dotnet new webapi

技术图片

命令行创建项目模板

 

  项目创建完成后,已经默认包含了一个模拟气象数据查询的接口:

技术图片

原始项目

 

  小贴士:您可以使用 NET Core 3.1 或 .NET 5、.NET 6 进行开发,代码没有任何差别。

   运行后默认已经加载了 Swagger:

技术图片

原始运行页面,为 Swagger 首页

  

   使用 Swagger 我们已经可以测试 API:

技术图片

使用 Swagger 测试接口运行

 

   此处的 API 还是需要手写 API 才能完成,打开 WeatherForecastController.cs 可以看到初始化内容:

技术图片技术图片

 越来越复杂、混乱的 API 导致了大量低效、低价值的重复劳动

 

   为了解决这样的问题,WebApiEngine 登场了! 让我们来看看 WebApiEngine 能做什么?

 

使用 [ApiBind] 标签让任何方法变成 WebApi

  我们在 WeatherService 下再创建一个名为 GetWeatherForecast 的新方法,并附加一个 int 类型参数,用于演示新的接口:

 1         public WeatherForecast GetWeatherForecast(int index)
 2         {
 3             var rng = new Random();
 4             return new WeatherForecast
 5             {
 6                 Date = DateTime.Now.AddDays(index),
 7                 TemperatureC = rng.Next(-20, 55),
 8                 Summary = Summaries[rng.Next(Summaries.Length)]
 9             };
10         }

   然后,通过加单的 3 步,完成动态 API 的实现:

 

  第一步:安装 Senparc.CO2NET.WebApi 包:

技术图片

 安装 Senparc.CO2NET.WebApi 包

 

  也可以在项目目录下,使用命令行添加:

dotnet add package Senarc.CO2NET.WebApi

     第二步:在 ConfigureServices() 方法中添加两行代码:

1             var builder = services.AddMvcCore().AddApiExplorer();
2             services.AddAndInitDynamicApi(builder, null);

   第三步:添加 [ApiBind] 标签

  在任意方法上添加 [ApiBind] 标签,如之前创建的 GetWeatherForecast(int index) 方法:

 1         [ApiBind]
 2         public WeatherForecast GetWeatherForecast(int index)
 3         {
 4             var rng = new Random();
 5             return new WeatherForecast
 6             {
 7                 Date = DateTime.Now.AddDays(index),
 8                 TemperatureC = rng.Next(-20, 55),
 9                 Summary = Summaries[rng.Next(Summaries.Length)]
10             };
11         }

   完成!

 

  重新启动项目,即可看到新的 GetWeatherForecast 接口:

 

 

 

运行结果:

技术图片

 WebApiEngine 会自动处理重名的 API

 

复制特性

  动态 API 的另外一个难点是,正常的 WebAPI 通常都需要定义自己的特性,如访问鉴权、行为过滤,等等。WebApiEngine可以将原始方法上的特性标签直接复制到动态 API 上。

  我们在 GetWeatherForecast 方法上添加权限验证特性:

 1         [ApiBind("WeatherForecast", "MyApi")]
 2         [Authorize]
 3         public WeatherForecast GetWeatherForecast(int index)
 4         {
 5             var rng = new Random();
 6             return new WeatherForecast
 7             {
 8                 Date = DateTime.Now.AddDays(index),
 9                 TemperatureC = rng.Next(-20, 55),
10                 Summary = Summaries[rng.Next(Summaries.Length)]
11             };
12         }

  然后运行接口:

技术图片

 [Authorize] 标签生效 

 

  上面的测试可以看到 [Authorize] 标签已经生效(虽然提示了 Authorize 配置错误,是因为我们没有进行授权配置)。

  WebApiEngine 支持所有的特性标签。

 

为整个类配置 WebApi

  除了在某个具体的方法上添加 [ApiBind] 特性标签,您还可以在类(class)上使用此特性,使下属所有的方法(包括静态方法)都拥有相同的配置。

  class 上的特性标签同样会自动配置,其规则如下:

  1. 如果 class 设置了特性标签(如 [Authorize]),则下属所有的方法也将继承对应特性;
  2. 如果下属方法具有和 class 一样的特性标签,将完全覆盖 class 的特性设置;
  3. 集成特性标签的顺序,为先按顺序添加 class 的标签,后按顺序添加方法的标签(注此顺序为 CustomAttributeData.GetCustomAttributes() 获得到的顺序);

测试:

  将之前的 WeatherService2 类进行重写:

 1     [ApiBind("ClassCoverAttribute", "MyApi")]
 2     public class WeatherService2
 3     {
 4         public string GetWeatherForecast(string str)
 5         {
 6             return "the parameter value is :" + str;
 7         }
 8 
 9         [ApiBind(ApiRequestMethod = ApiRequestMethod.Get)]
10         public string GetWeatherForecastCopy(string str)
11         {
12             return "the parameter value is :" + str;
13         }
14 
15         public static string GetWeatherForecastCopyStatic(string str)
16         {
17             return "[static method]the parameter value is :" + str;
18         }
19     }

   第 1 行代码在 class 上进行添加,使其中 2 个方法都生效。

  第 9 行代码改写了 ApiBind 标签,使默认的 Post 方法,改为了 Get 方法。

  第 10 行代码是一个静态方法,同样能“享受”整个 class 的配置(当然也支持使用自定义 [ApiBind],然后覆盖 class 的配置)。

 

运行结果:

 技术图片

     运行结果中:

  • ① 是 GetWeatherForecast() 方法
  • ② 是 GetWeatherForecastCopyStatic() 静态方法(因为使用了 class继承,因此默认为相同的名称,后续版本将升级为当前方法名称)
  • ③ 是 WeatherService 类中的演示方法,和当前类无关
  • ④ 是 GetWeatherForecastCopy() 方法,该方法的 [ApiBind] 特性覆盖了 class 上的特性,因此没有指定 Category,使用了默认的分类名称,即当前程序集名称

 

忽略某些特定的方法

  有时,虽然我们偷懒将某个 class 一次性标记为 [ApiBind],但也会有个别的方法,我们并不希望开放为 API,这时候,可以使用 WebApiEngine 提供的忽略方法。

  有两种方式可以做到。

  方式一:使用 IgnoreApiBind 特性,如:

1         [IgnoreApiBind]
2         public static string GetWeatherForecastCopyStatic(string str)
3         {
4             return "[static method]the parameter value is :" + str;
5         }

  方式二:设置 ApiBind 特性中的 Ignore 属性,如:

1         [ApiBind(Ignore = true)]
2         public static string GetWeatherForecastCopyStatic(string str)
3         {
4             return "[static method]the parameter value is :" + str;
5         }

 

忽略某些特定的分类

  通过配置,我们也可以忽略部分特定的分类(Category),在运行引擎之前,在 startup.cs 中进行定义:

1             Senparc.CO2NET.WebApi.Register.AddOmitCategory("WeatherForecast");
2 
3             var builder = services.AddMvcCore().AddApiExplorer();
4             services.AddAndInitDynamicApi(builder, null);

  只需添加上述第 1 行代码,即可忽略整个 WeatherForecast 分类的接口(当然不能忽略通过原始方法编写的 Controller 内的 API):

 
忽略前 忽略后

 

进阶

  请关注后续内容:

  • 《1 行代码,将任何一个方法开放为 WebApi》
  • 《1 行代码,配置 WebApi 的注释文档》
  • 《0 代码,结合 NeuCharFramework 高效使用 WebApiEngine》
  • 《使用 WebApiEngine 实现微信接口可视化测试环境》
  • 《使用 NeuCharFramework + WebApiEngine 搭建微信全平台接口代理服务器》
  • 等等

 

本文示例源码下载

 

[本系列未完待续,持续更新中]