ASP.NET Core 奇淫技巧之动态WebApi

来自:晓晨Master

一、前言


接触到动态WebApi(Dynamic Web API)这个词的已有几年,是从ABP框架里面接触到的,当时便对ABP的这个技术很好奇,后面分析了一波,也尝试过从ABP剥离一个出来作为独立组件来使用,可是后来因与ABP依赖太多而放弃。十几天前朋友 熊猫 将这部分代码成功的从 ABP 中剥离出来并做了一个简单Demo扔给我,经过这么久终于经过一些修改、添加功能、封装,现在已经能作为一个独立组件使用,

项目开源Github:https://github.com/dotnetauth/Panda.DynamicWebApi

希望觉得有用的朋友能给一个 Star 支持一下。


本文只讲使用,不讲原理,原理放到后面的文章中详细介绍。


二、介绍


不管是传统的三层架构、 DDD 经典四层架构(DDD Lite),亦或是其他具有应用逻辑层(业务逻辑层)的架构,在Web应用程序开发当中 ,我们的业务逻辑最终都需要经过 Web Api 来进行调用,这里我们可能会有一个重复的操作:编写业务逻辑->编写API调用业务逻辑,这种重复性的操作有没有解决办法呢,我们编写完业务逻辑以后便给我们自动生成WebApi,答案当然是有的。


这里介绍一下本文的主角:Panda.DynamicWebApi:https://github.com/dotnetauth/Panda.DynamicWebApi。


源自于ABP的一个可独立使用的,可自动为你的业务逻辑层生成 ASP.NET Core WebApi 层的开源组件。


它生成的API符合Restful风格,可以根据符合条件的类来生成WebApi,由MVC框架直接调用逻辑,无性能问题,完美兼容Swagger来构建API说明文档。


三、使用


这里以 DDD 经典四层架构中的应用逻辑层来讲解。


1、准备


(1)、建立两个项目一个是应用逻辑层类库项目;一个是作为生成WebApi Host,ASP.NET Core WebApi项目



(2)、编写应用逻辑


定义一个应用逻辑接口,所有应用逻辑都应实现它:


public interface IApplicationService
{
}


定义一个学生管理逻辑接口,继承应用逻辑接口


public interface IStudentAppService : IApplicationService
{
   /// <summary>
   /// 根据ID获取学生
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   StudentOutput Get(int id);

   /// <summary>
   /// 获取所有学生
   /// </summary>
   /// <returns></returns>
   List<StudentOutput> Get();

   /// <summary>
   /// 更新学生信息
   /// </summary>
   /// <param name="input"></param>
   void Update(UpdateStudentInput input);

   /// <summary>
   /// 更新学生年龄
   /// </summary>
   /// <param name="age"></param>
   void UpdateAge(int age);

   /// <summary>
   /// 根据ID删除学生
   /// </summary>
   /// <param name="id"></param>
   void Delete(int id);

   /// <summary>
   /// 添加学生
   /// </summary>
   /// <param name="input"></param>
   void Create(CreateStudentInput input);
}


实现学生逻辑管理接口:


public class StudentAppService: IStudentAppService
{
   /// <summary>
   /// 根据ID获取学生
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   [HttpGet("{id:int}")]
   public StudentOutput Get(int id)
   
{
       return new StudentOutput() {Id = 1, Age = 18, Name = "张三"};
   }

   /// <summary>
   /// 获取所有学生
   /// </summary>
   /// <returns></returns>
   public List<StudentOutput> Get()
   
{
       return new List<StudentOutput>()
       {
           new StudentOutput(){Id = 1,Age = 18,Name = "张三"},
           new StudentOutput(){Id = 2,Age = 19,Name = "李四"}
       };
   }

   /// <summary>
   /// 更新学生信息
   /// </summary>
   /// <param name="input"></param>
   public void Update(UpdateStudentInput input)
   
{
       throw new System.NotImplementedException();
   }

   /// <summary>
   /// 更新学生年龄
   /// </summary>
   /// <param name="age"></param>
   [HttpPatch("{id:int}/age")]
   public void UpdateAge(int age)
   
{
       throw new System.NotImplementedException();
   }

   /// <summary>
   /// 根据ID删除学生
   /// </summary>
   /// <param name="id"></param>
   [HttpDelete("{id:int}")]
   public void Delete(int id)
   
{
       throw new System.NotImplementedException();
   }

   /// <summary>
   /// 添加学生
   /// </summary>
   /// <param name="input"></param>
   public void Create(CreateStudentInput input)
   
{
       throw new System.NotImplementedException();
   }
}


(3)、给 WebApi Host 项目配置 Swagger。


Install-Package Swashbuckle.AspNetCore -Version 4.0.1


Startup 中配置


public void ConfigureServices(IServiceCollection services)
{    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
   services.AddSwaggerGen(options =>
   {
       options.SwaggerDoc("v1", new Info { Title = "晓晨学生管理系统 WebApi", Version = "v1" });
       options.DocInclusionPredicate((docName, description) => true);  options.IncludeXmlComments(@"bin\Debug\netcoreapp2.2\Xc.StuMgr.WebApiHost.xml");  options.IncludeXmlComments(@"bin\Debug\netcoreapp2.2\Xc.StuMgr.Application.xml");
   });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
   if (env.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
   }
   app.UseSwagger();
   app.UseSwaggerUI(c =>
   {
      c.SwaggerEndpoint("/swagger/v1/swagger.json", "晓晨学生管理系统 WebApi");
   });
   app.UseMvc();
}


运行则会直接看到默认的 ValuesController 的5个API。


2、动态WebApi


通过Nuget 为 Application 项目安装组件:


Install-Package Panda.DynamicWebApi


为接口 IApplicationService继承 IDynamicWebApi同时添加特性DynamicWebApi


[DynamicWebApi]
public interface IApplicationService:IDynamicWebApi
{
}


在 WebApi Host 项目中,Startup里配置动态WebApi:


Startup.cs:


// 添加动态WebApi 需放在 AddMvc 之后
services.AddDynamicWebApi();


然后打开浏览器访问将会看到:



可以看到成功为我们的 StudentAppService 生成了WebApi,并且和Swagger完美兼容。


四、详细介绍


经过上面的介绍,大家应该可以看出使用是非常简单的,只需两步:


第一步:为你的类(或者该类的接口、该类继承的抽象类,不得放在该类除前面两种情况的父类上)继承 IDynamicWebApi接口并加入特性[DynamicWebApi]


第二步:Startup中注册


// 添加动态WebApi 需放在 AddMvc 之后
services.AddDynamicWebApi();


因为需要MVC的一些类来进行处理,所以必须放在AddMvc之后,本组件有检查。


1、规则


本组件采用约定大于配置,所以在实际使用中有几个规则:


(1)要让类生成动态API需要满足两个条件,一个是该类直接或间接实现 IDynamicWebApi,同时该类本身或者父抽象类或者实现的接口具有特性 DynamicWebApi


(2)添加特性 [NonDynamicWebApi] 可使一个类或者一个方法不生成API,[NonDynamicWebApi] 具有最高的优先级。


(3)会对符合规则的动态API类名进行后缀的删除,如:我们前面的 StudentAppService,会被删除 AppService 后缀,这个规则是可以动态配置的。


(4)会自动添加API路由前缀,默认会为所有API添加 api前缀


(5)默认的HTTP动词为POST,可以通过 HttpGet/HttpPost/HttpDelete等等ASP.NET Core 内置特性来覆盖


(6)可以通过HttpGet/HttpPost/HttpDelete等内置特性来覆盖默认路由


(7)默认会根据你的方法名字来设置HTTP动词,如 CreateApple 或者 Create 生成的API动词为 POST,对照表如下,若命中(忽略大小写)对照表那么该API的名称中的这个动词将会被省略,如 CreateApple 将会变成 Apple,如未在以下对照表中,将会使用默认动词 POST



(8)强烈建议方法名称使用帕斯卡命名(PascalCase)规范,以更好的自动处理API名称,且使用以上对照表的动词。如:


添加苹果 -> Add/AddApple/Create/CreateApple


更新苹果 -> Update/UpdateApple


...


(9)[DynamicWebApi] 特性因为可被继承,所以为了父类被误识别,禁止放在除抽象类、接口以外的父类上。


2、配置


所有的配置均在对象 DynamicWebApiOptions 中,说明如下:



五、疑难解答


若遇到问题,可使用 Issues(https://github.com/dotnetauth/Panda.DynamicWebApi/issues)

进行提问。


六、结束


开源地址:https://github.com/dotnetauth/Panda.DynamicWebApi 希望给个 Star 支持一下


本文Demo地址:https://github.com/dotnetauth/Panda.DynamicWebApi/tree/master/practice/XiaoChen.StudentManagement


ABPhttps://github.com/aspnetboilerplate/aspnetboilerplate

推荐↓↓↓
DotNet程序员
上一篇:ASP.NET Core 集成 JWT 下一篇:.NET Core 微服务-Mycat