使用 FastEndpoints 来垂直切换Web API的控制器方法

  • 使用 FastEndpoints 来垂直切换Web API的控制器方法已关闭评论
  • 84 次浏览
  • A+
所属分类:.NET技术
摘要

在我们开发项目的Web API的时候,随着项目功能要求越来越多,可能我们会为控制器基类增加越来越多的基础功能,有些功能有一定的适应性,但可能在一般的子类中用不到,而随着对控制器控制要求越来越精细,那么需要为基类或者子类增加更多的控制功能,这样随着迭代的进行,有些控制器的功能会显得越来越笨重。这个时候,一种更加灵活、轻便的Web API处理方式,对每个控制器方法的垂直切割的API框架应运而生,本篇随笔介绍的FastEndpoints 就是其中这样的一款框架,本篇随笔介绍一些FastEndpoints的基础处理方法,并通过一些基础的案例,把我们《 SqlSugar 开发框架》的一些模块进行迁移性测试,对比相关后端Web API的处理,一起分享给大家。

在我们开发项目的Web API的时候,随着项目功能要求越来越多,可能我们会为控制器基类增加越来越多的基础功能,有些功能有一定的适应性,但可能在一般的子类中用不到,而随着对控制器控制要求越来越精细,那么需要为基类或者子类增加更多的控制功能,这样随着迭代的进行,有些控制器的功能会显得越来越笨重。这个时候,一种更加灵活、轻便的Web API处理方式,对每个控制器方法的垂直切割的API框架应运而生,本篇随笔介绍的FastEndpoints 就是其中这样的一款框架,本篇随笔介绍一些FastEndpoints的基础处理方法,并通过一些基础的案例,把我们《 SqlSugar 开发框架》的一些模块进行迁移性测试,对比相关后端Web API的处理,一起分享给大家。

1、FastEndpoints介绍

FastEndpoints 是Minimal API和MVC的开发人员友好替代品,它是基于REPR设计模式(请求-端点-响应),以便创建方便且可维护的端点,几乎没有样板文件。

FastEndpoints 的性能与Minimal API 相当,甚至它更快,使用更少的内存并且每秒请求数比基准测试中的MVC控制器更高。对于比如:中间件、认证、授权、日志,依赖注入这些常用功能都支持,甚至有些还进行了加强。

设计主要是分为两种模式

分层模式:mvc、mvp、mvvm等
垂直模式:REPR设计模式
REPR设计模式就是垂直模式,系统的每个组件都是单独的一块,彼此并不影响,就像微服务那样。

MVC - 模型-视图-控制器旨在与用户界面配合使用。显然,视图是一个 UI 组件。如果您正在构建 API,则没有视图,因此您充其量使用的是 MC 模式,或者您可以将其称为模型-操作-控制器并获取 MAC 模式。关键是,你已经没有将MVC用于你的API,所以考虑一个更合适的模式应该不是一个很大的问题。

API 端点是非常独立的,每个端点都可以使用三个组件来描述:

请求(Request):终结点所需的数据形状
终结点(Endpoint):终结点在给定请求时执行的逻辑
响应(Response):终结点返回给调用方的响应
结合这三个元素,你会得到请求-端点-响应或 REPR 模式。

并非所有终结点都需要其请求或响应的实际数据,在某些情况下,不接收任何输入或仅返回 HTTP 状态代码。但是,在此模式中,空请求或响应仍然是有效的请求或响应,就像某些 MVC 操作不需要模型一样。

使用 API 端点库时,您可以将请求、终端节点和响应类型分组在一起,这样就无需在某些“视图模型”或“dtos”文件夹中四处寻找合适的类型。它减少了摩擦,使使用单个端点变得更加容易。

FastEndPoint GitHub库:https://github.com/FastEndpoints/FastEndpoints

FastEndpoints 在线文档:https://fast-endpoints.com 

2、简单例子入门

参考官方的文档介绍,我们可以很容易的创建出一个简单的类似Hello开篇的API应用。

我创建一个基于.net core的Web API项目,先把FastEndPoint的相关引用加入项目中,如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

 然后在项目中的启动类代码中,我们添加相关的代码使用FastEndpoints,如下所示。

using FastEndpoints; using FastEndpoints.Swagger;  var bld = WebApplication.CreateBuilder(); bld.Services    .AddFastEndpoints()    .SwaggerDocument();   var app = bld.Build(); app.UseFastEndpoints()    .UseSwaggerGen();  app.Run();

如果需要对Swagger进行一些定制修改,可以改动如下,这里先忽略。

    .SwaggerDocument(o =>     {         o.DocumentSettings = s =>         {             s.Title = "SqlSugar框架接口API文档";             s.Version = "v1";         };         o.TagDescriptions = t =>         {             t["Test"] = "测试接口";             t["User"] = "用户相关接口";         };     })

为了简便,我们以命名控件不同,以及目录,来区分不同的Web API分组,如下所示,我们创建一个基于Test的相关API接口。

使用 FastEndpoints 来垂直切换Web API的控制器方法

对于以前的控制器接口来说,一般可能一个控制(如TestController)会包含多个方法,如上面的Create、List方法,这里使用的是FastEndpoints,它们是把一个大型的控制器切换为一个方法一个类来处理,碎片化意味着类的增加,不过我们不需要做太多的工作,可以通过它们的一些基类来简化这个过程。

我们把WebAPI中请求的Request和Response的对象,放在一个Model类文件里面,如下代码所示。

namespace FastWebApi.Controllers.Test {     /// <summary>     /// 测试请求信息     /// </summary>     public class TestRequest     {         public string FirstName { get; set; }         public string LastName { get; set; }         public int Age { get; set; }     }      /// <summary>     /// 测试返回信息     /// </summary>     public class TestResponse     {         public string FullName { get; set; }         public bool IsOver18 { get; set; }     } }

我们来看看基于FastEndPoints方式 生成一个Create的请求Web API方法,如下代码所示

namespace FastWebApi.Controllers.Test {     //客户使用标识,不用覆盖 Configure 函数     //[HttpPost("/api/user/create")]     //[AllowAnonymous]      /// <summary>     /// 创建记录     /// </summary>     public class Create : Endpoint<TestRequest, AjaxResponse>     {         public override void Configure()         {             Post("/test/create");             AllowAnonymous();         }          public override async Task HandleAsync(TestRequest req, CancellationToken ct)         {             var result = new TestResponse()             {                 FullName = req.FirstName + " " + req.LastName,                 IsOver18 = req.Age > 18             };             await SendAsync(result.ToAjaxResponse());         }     } }

我们配置Web API方法的路由,可以通过在Configure函数中指定: Post("/test/create")

也可以通过Attribute属性标识的方式,来声明,上面的注释代码所示。

[HttpPost("/api/user/create")]

这两者是等同的,任何一种方式都可以,默认的接口是需要授权才能访问的,如果我们标识了

[AllowAnonymous]

就可以匿名访问Web API 的方法了,Web API的方法处理逻辑,都是统一通过重写 HandleAsync 方法进行实现的,如上面代码所示。

其中AjaxResponse 是我定义的一个统一返回结果,这样我们的接口模型就一致了。

如下是Web API统一封装后返回的结果对象。

使用 FastEndpoints 来垂直切换Web API的控制器方法

如果需要了解我的《SqlSugar开发框架》的统一结果返回处理,可以参考《基于SqlSugar的数据库访问处理的封装,在.net6框架的Web API上开发应用 》中的 【统一结果封装和异常处理】 部分内容即可。

如果不需要统一返回模型,则可以自定义为任何的返回类型,如下是官方的案例所示。

public class MyEndpoint : Endpoint<MyRequest, MyResponse> {     public override void Configure()     {         Post("/api/user/create");         AllowAnonymous();     }      public override async Task HandleAsync(MyRequest req, CancellationToken ct)     {         await SendAsync(new()         {             FullName = req.FirstName + " " + req.LastName,             IsOver18 = req.Age > 18         });     } }

接下来,我们检查下.netcore项目的launchSettings.json 配置信息

使用 FastEndpoints 来垂直切换Web API的控制器方法

确保打开的时候就启动Swagger页面即可。

使用 FastEndpoints 来垂直切换Web API的控制器方法

启动Swagger页面,我们来看看具体的效果,可以看到有两个Test的接口,如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

我们来调试Swagger,并测试下结果返回。

使用 FastEndpoints 来垂直切换Web API的控制器方法

测试返回的结果如下所示,由于采用了统一返回结果的处理,这里返回的TestResponse的对象序列化信息,放在了result的里面了,如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

而List的控制器方法,这里没有请求输入的对象信息,因此参数为空。具体的API方法定义如下所示。

namespace FastWebApi.Controllers.Test {     /// <summary>     /// 获取所有记录     /// </summary>     [HttpGet("/test/list")]     [AllowAnonymous]     public class List : EndpointWithoutRequest<AjaxResponse>     {         /// <summary>         /// 处理返回         /// </summary>         public override async Task HandleAsync(CancellationToken ct)         {             var result = new List<TestResponse>()             {                 new TestResponse                 {                      FullName= "test",                       IsOver18 = true,                 },                 new TestResponse                 {                     FullName= "test 2",                       IsOver18 = false,                 }             };            await SendAsync(result.ToAjaxResponse());         }     } }

Swagger接口展示界面效果。

使用 FastEndpoints 来垂直切换Web API的控制器方法

正常执行返回结果如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

 如果处理过程中有异常,由于我们采用了统一返回结果处理,因此异常信息也需要统一在对象里面,返回结果如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

 以上就是简单类型的一些处理例子,结合了统一返回结果的处理,我们可以很好的定义一个通用的结果返回。

 

3、对我们SqlSugar框架常规CRUD等基类接口进行垂直切割的处理

 上面我们为了更好理解FastEndpoints的碎片化接口的处理,我们做了两个简单的方法来测试。

下面我们通过对我们SqlSugar开发框架中的基类接口进行功能上的拆分,并结合实际业务的需要接口,进行扩展的处理,从而也实现了常规CRUD的操作接口,并实现特殊业务类的API接口处理。

关于Web API的常规接口处理 ,我们为了简化代码,往往抽象一些常规的CRUD方法在控制器基类中,这样可以极大的减少了继承子类的接口代码,通过继承基类,子类自动具备了CRUD的处理接口,只需要根据业务的需要,增加一些特殊的业务接口即可。

以前的处理方法,我们是根据项目的需要,我们定义了一些控制器的基类,用于实现不同的功能,如下界面所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

其中ControllerBase是.net core Web API中的标准控制器基类,我们由此派生一个LoginController用于登录授权,而BaseApiController则处理常规接口用户身份信息,而BusinessController则是对标准的增删改查等基础接口进行的封装,我们实际开发的时候,只需要开发编写类似CustomerController基类即可。

而现在采用FastEndpoints ,需要垂直切割整个控制器,我们需要把基类的接口实现放到具体的业务API类里面,我们为了方便,可以给他们不同的名称一个接口,或者组合在一个文件里面,如下所示。

使用 FastEndpoints 来垂直切换Web API的控制器方法

我们来看看其中给一个简单的Count方法接口实现。

namespace FastWebApi.Controllers.User {     /// <summary>     /// 根据条件计算记录数量     /// </summary>     [HttpGet("/user/count")]     public class Count : Endpoint<UserPagedDto, AjaxResponse>     {         /// <summary>         /// 处理请求         /// </summary>         public override async Task HandleAsync(UserPagedDto req, CancellationToken ct)         {             var result = await BLLFactory<IUserService>.Instance.CountAsync(req);             await SendAsync(result.ToAjaxResponse());         }     } }

这里可以采用接口注入的方式,也可以采用我们辅助类BLLFactory<IUserService>.Instance方法调用接口,一样的实现。

这样结合了业务的具体Service来处理,只需要简单的处理下即可,也算比较方便,由于这些基础的CRUD的方法,主要路由、分页对象,业务对象,主键类型的不同,这些可以通过我们的代码生成工具的处理快速生成即可,因此可以实现批量化的业务类的API接口方法生成。

至于具体的业务接口API,我们就需要手工处理了,如对于用户的登陆获取token的方法,我们这里需要模仿来生成一个EndPiont类,如下所示。

    /// <summary>     /// 根据用户名、密码验证用户身份有效性     /// </summary>     [HttpPost("/user/verify-user")]     [AllowAnonymous]     public class VerifyUser : Endpoint<VerifyUserDto, AjaxResponse>     {         /// <summary>         /// 处理请求         /// </summary>         public override async Task HandleAsync(VerifyUserDto input, CancellationToken ct)         {             var result = await BLLFactory<IUserService>.Instance.VerifyUser(input.UserName, input.UserPassword, input.SystemType, input.IP, input.MacAddr);             await SendAsync(result.ToAjaxResponse());         }     }

其他业务方法也是类似的处理,这里的FastEndPoints的处理类,只是增加了一个简单的包装层就可以了,最后看看这些方法在SwaggerUI中的展示,和我们普通模式的Web API中的Swagger UI界面类似的效果。

使用 FastEndpoints 来垂直切换Web API的控制器方法

 这样,我们可以在保持接口一致性的情况下,无缝的对接新的Web API接口后端了。