动态WebApi
一.前言
接触到动态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
| 方法名开头 | 动词 |
|---|---|
| create | POST |
| add | POST |
| post | POST |
| get | GET |
| find | GET |
| fetch | GET |
| query | GET |
| update | PUT |
| put | PUT |
| delete | DELETE |
| remove | DELETE |
（8）强烈建议方法名称使用帕斯卡命名（PascalCase）规范，以更好的自动处理API名称，且使用以上对照表的动词。如:
添加苹果 -> Add/AddApple/Create/CreateApple
更新苹果 -> Update/UpdateApple
...
（9）[DynamicWebApi] 特性因为可被继承，所以为了父类被误识别，禁止放在除抽象类、接口以外的父类上。
2.配置
所有的配置均在对象 DynamicWebApiOptions 中，说明如下：
| 属性名 | 是否必须 | 说明 |
|---|---|---|
| DefaultHttpVerb | 否 | 默认值：POST。默认HTTP动词 |
| DefaultAreaName | 否 | 默认值：空。Area 路由名称 |
| DefaultApiPrefix | 否 | 默认值：api。API路由前缀 |
| RemoveControllerPostfixes | 否 | 默认值：AppService/ApplicationService。类名需要移除的后缀 |
| RemoveActionPostfixes | 否 | 默认值：Async。方法名需要移除的后缀 |
| FormBodyBindingIgnoredTypes | 否 | 默认值：IFormFile。不通过MVC绑定到参数列表的类型。 |
五.疑难解答
若遇到问题，可使用 Issues 进行提问。
六.结束
本项目开源地址：https://github.com/dotnetauth/Panda.DynamicWebApi 希望给个 Star 支持一下
本文Demo地址：XiaoChen.StudentManagement
目前学习.NET Core 最好的教程 .NET Core 官方教程
.NET Core 交流群：923036995 或 4656606 欢迎加群交流
如果您认为这篇文章还不错或者有所收获，您可以点击右下角的【推荐】支持，或请我喝杯咖啡【赞赏】，这将是我继续写作，分享的最大动力！
