Furion 动态 WebAPI及API版本、请求地址中间的可变参数等

5.1.1 什么是控制器​

简单来说，控制器是一个承上启下的作用，根据用户输入，执行响应行为（动作方法），同时在行为中调用模型的业务逻辑，返回给用户结果（视图）。

 

在 ASP.NET Core 中，控制器有两种表现形式：

• Mvc（带视图）
• WebAPI（RESTful API）

WebApi控制器

 

Mvc 控制器和 WebAPI 控制器最大的区别是 WebAPI 控制器不带 视图 和通过 请求谓词和路由地址响应行为。

5.1.2 Mvc 控制器 约定和缺点​

在学习动态 WebAPI 控制器之前，首先了解 ASP.NET Core 中 WebAPI 的一些约定和注意事项。

5.1.2.1 WebAPI 约定​

在 ASP.NET Core 应用中，一个 WebAPI 控制器需遵循以下约定：

• 控制器类必须继承 ControllerBase 或间接继承
• 动作方法必须贴有 [HttpMethod] 特性，如：[HttpGet]
• 控制器或动作方法至少有一个配置 [Route] 特性
• 生成 WebAPI 路由地址时会自动去掉控制器名称 Controller 后缀，同时也会去掉动作方法匹配的 HttpVerb 谓词，如 GET，POST，DELETE，PUT 等
• 不支持返回非 IEnumerable<T> 泛型对象
• 不支持类类型参数在 GET，HEAD 请求下生成 Query 参数

除了上述约定外，WebAPI 路由地址基本靠手工完成，不利于书写，不利于维护，再者，在移动应用对接中难以进行多版本控制。

5.1.2.2 .NET Core WebAPI 缺点​

通过上一章节可以看出，ASP.NET Core 应用实现 WebAPI 需要遵循种种约定，而且容易出错。

除了这些约定，.NET Core WebAPI 有以下缺点：

• 路由地址基本靠手工完成
• 在现在移动为王的时代，不利于进行多版本控制
• 对接 Swagger 文档分组比较复杂
• 实现 Policy 策略授权也比较复杂
• 不支持控制器热插拔插件化
• 难以实现复杂自定义的 RESTful API 风格

5.1.3 动态 WebAPI 控制器​

针对以上 ASP.NET Core 提供的 WebAPI 必须遵循的约定和不可避免的缺点，Furion 框架创造出一种更加灵活创建 WebAPI 控制器的方式。

这个方式在继承了 ASP.NET Core WebAPI 所有优点，同时进行了大量拓展和优化。优化后的 WebAPI 具有以下优点：

• 具备原有的 ControllerBase 所有功能
• 支持任意公开 非静态 非抽象 非泛型类转控制器
• 提供更加灵活方便的 IDynamicApiController 空接口或 [DynamicApiController] 特性替代 ControllerBase 抽象类
• 可直接在任意公开 非静态 非抽象 非泛型类贴 [Route] 特性自动转控制器
• 无需手动配置 [HttpMethod] 特性，同时支持一个动作方法多个 HttpVerb
• 无需手动配置 [Route] 特性，支持更加灵活的配置及自动路由生成
• 支持返回泛型接口，泛型类
• 和 Swagger 深度结合，提供极其方便的创建 Swagger 分组配置
• 支持 Basic Auth，Jwt，ApiKey 等多种权限灵活配置
• 支持控制器、动作方法版本控制功能
• 支持 GET、HEAD 请求自动转换 类类型参数
• 支持生成 OAS3 接口规范

5.1.4 注册动态 WebAPI 服务​

5.1.5 第一个例子​

创建一个 FurionAppService 类继承 IDynamicApiController 接口 或 贴 [DynamicApiController] 特性，并在这个类中编写一个 Get 方法。

• IDynamicApiController 方式
  
  using Furion.DynamicApiController; namespace Furion.Application { public class FurionAppService : IDynamicApiController { public string Get() { return $"Hello {nameof(Furion)}"; } } }

  1 2 3 4 5 6 7 8 9 10 11 12

  using Furion.DynamicApiController;   namespace Furion.Application {     public class FurionAppService : IDynamicApiController     {         public string Get()         {             return $"Hello {nameof(Furion)}";         }     } }

  
   

• [DynamicApiController] 方式
  
  using Furion.DynamicApiController; namespace Furion.Application { [DynamicApiController] public class FurionAppService { public string Get() { return $"Hello {nameof(Furion)}"; } } }

  1 2 3 4 5 6 7 8 9 10 11 12 13

  using Furion.DynamicApiController;   namespace Furion.Application {     [DynamicApiController]     public class FurionAppService     {         public string Get()         {             return $"Hello {nameof(Furion)}";         }     } }

  
   
• 如下图所示，一个 WebAPI 接口就这么生成了。

5.1.6 动态 WebAPI 原理解析​

5.1.6.1 控制器特性提供器​

Furion 框架会在应用启动时注册 DynamicApiControllerFeatureProvider 控制器特性提供器，该提供器继承自 ControllerFeatureProvider 类。

接着重写 bool IsController(TypeInfo typeInfo) 方法，用来标识控制器类型。在 Furion 框架中，继承自 ControllerBase 类或 IDynamicApiController 接口或 [DynamicApiController] 特性都会被标记为控制器类型。

5.1.6.2 应用模型转换器​

Furion 框架同时在应用启动时注册 DynamicApiControllerApplicationModelConvention 应用模型转换器，该转换器继承自 IApplicationModelConvention 接口。

接着实现 void Apply(ApplicationModel application) 接口方法。在该方法中配置控制器名称、路由、导出可见性及动作方法名称、路由、导出可见性等。

实际上该方法做的就是按照 WebAPI 约定 提前帮我们配置好路由、请求谓词等信息。避免了手动配置的同时还增加了许多新特性，如版本控制。

5.1.7 动态 WebAPI 配置约定​

5.1.7.1 控制器默认约定​

• 生成控制器名称默认去除以 AppServices，AppService，ApiController，Controller，Services，Service 作为前后缀的字符串。见第一个例子中的 FurionAppService -> Furion 支持自定义配置
• 控制器名称带 V[0-9_] 结尾的，会自动生成控制器版本号，如 FurionAppServiceV2 -> Furion@2，FurionAppServiceV1_1_0 -> Furion@1.1.0。支持版本分隔符配置
• 控制名称以 骆驼命名（CamelCase） 会自动切割成多个单词 - 连接。支持自定义配置

5.1.7.2 动作方法默认约定​

• 生成的动作方法名称默认去除以 Post/Add/Create/Insert/Submit，GetAll/GetList/Get/Find/Fetch/Query/Search，Put/Update，Delete/Remove/Clear，Patch 开头的字符串。支持自定义配置
• 生成的动作方法名称默认去除以 Async 作为前后缀的字符串。支持自定义配置
• 动作方法名称带 V[0-9_] 结尾的，会自动生成动作方法版本号，如 ChangePasswordV2 -> ChangePassword@2，ChangePasswordV1_1_0 -> ChangePassword@1.1.0。支持版本分隔符配置
• 动作方法名称以 骆驼(驼峰)/帕斯卡命名（CamelCase/Pascal） 会自动切割成多个单词 - 连接。支持自定义配置
• 动作方法参数将自动转为小写。支持自定义配置

5.1.7.3 请求谓词默认约定​

• 动作方法名
  • 以 Post/Add/Create/Insert/Submit/Change 开头，则添加 [HttpPost] 特性。
  • 以 GetAll/GetList/Get/Find/Fetch/Query 开头，则添加 [HttpGet] 特性。
  • 以 Put/Update 开头，则添加 [HttpPut] 特性。
  • 以 Delete/Remove/Clear 开头，则添加 [HttpDelete] 特性。
  • 以 Patch 开头，则添加 [HttpPatch] 特性
  • 支持自定义配置
• 如果不在上面约定中，则默认添加 [HttpPost] 特性。支持自定义配置

5.1.7.4 路由地址默认约定​

• 默认以 api 开头。支持自定义配置
• 默认转换为小写路由地址。支持自定义配置
• 生成控制器路由模板格式为：api/前置参数列表/模块名或默认区域名/[controller@版本号]/后置参数列表
• 生成动作方法路由模板格式为：前置参数列表/模块名/[action@版本号]/后置参数列表

5.1.7.5 其他约定​

• 默认不处理 ControllerBase 控制器类型。支持自定义配置
• 默认不处理 GET，HEAD 请求的引用类型参数。支持自定义配置

5.1.8 更多例子​

5.1.8.1 多种请求谓词方法

 

如下图所示：

5.1.8.2 多个自定义动作方法

 

如下图所示：

5.1.8.3 带参数动作方法

 

如下图所示：

5.1.8.4 GET/HEAD 类类型参数​

默认情况下，ASP.NET Core 会将 GET/HEAD 请求中的 类类型参数 设置为 [FromBody] 绑定，如：

 

如下图所示：

但是，GET、HEAD 请求不支持 From Body 绑定。所以我们需要转换为 Query 查询参数。

Furion 框架支持以下两种方式配置：

• 配置 DynamicApiControllerSettings， Furion.Web.Entry/appsettings.json
  
  { "DynamicApiControllerSettings": { "ModelToQuery": true } }

  1 2 3 4 5

  {   "DynamicApiControllerSettings": {     "ModelToQuery": true   } }

如下图所示：

5.1.8.5 自定义参数位置​

Furion 框架提供了非常方便的自定义参数位置的特性 [ApiSeat]，通过 [ApiSeat] 可配置参数位置，支持以下四种位置：

• ApiSeats.ControllerStart：控制器之前
• ApiSeats.ControllerEnd：控制器之后
• ApiSeats.ActionStart：动作方法之前
• ApiSeats.ActionEnd：动作方法之后。默认值

 

如下图所示：

5.1.8.6 自定义请求谓词

 

如下图所示：

5.1.8.7 支持多个谓词

 

如下图所示：

5.1.8.8 支持自定义路由​

支持控制器和动作方法自定义路由：

5.1.8.9 多路由随意组合​

Furion 框架提供了非常灵活的各种路由组合方式，支持一对多，多对多路由组合：

 

如下图所示：

---

在 Furion 4.8.5.7+ 版本提供更加强大的路由组合方式：

 

5.1.8.10 支持版本控制​

5.1.8.11 不公开控制器或动作方法​

有些时候，我们无需导出某个动作方法或控制器（不显示到 Swagger），只需要添加 [ApiDescriptionSettings(false)] 或 [ApiDescriptionSettings(IgnoreApi = true)]即可。

另外动作方法还支持 [NonAction] 标记不是一个有效的控制器或 Action。

 

5.1.8.12 保持控制器和方法命名​

默认情况下，动态 API 会将控制器和方法名输出为 RESTFul 风格的路由，如需保留原有设计，只需配置：

 

5.1.8.13 方法参数 [FromQuery] 化/参数非必填/参数可选​

默认情况下，所有的基元类型参数都会贴上 [FromRoute] 特性，如果需要将参数调整为 [FromQuery] 修饰，只需要在方法上面贴 [QueryParameters] 特性即可，如：

生成的路由为：https://xxx.com?id=1&name=Furion

如果不喜欢每个都配置，也可以全局配置（只会影响基元类型的参数）：

特别注意

5.1.8.14 参数绑定配置​

Furion 框架提供了多种参数特性配置参数绑定规则：

• [FromRoute]：通过路由参数绑定值
• [FromQuery]：通过 Url 地址参数绑定值
• [FromBody]：通过 Request Body 参数绑定值
• [FromForm]：通过表单提交绑定值
• [FromHeader]：通过 Request Header 参数绑定值

5.1.8.15 自定义根据方法名生成 [HttpMethod] 规则​

在 Furion 框架中，在没有配置 [HttpMethod] 特性的情况下，会自动根据方法名第一个参数进行分析，并生成对应的 [HttpMethod] 特性，规则如下：

• 动作方法名
  • 以 Post/Add/Create/Insert/Submit 开头，则添加 [HttpPost] 特性。
  • 以 GetAll/GetList/Get/Find/Fetch/Query 开头，则添加 [HttpGet] 特性。
  • 以 Put/Update 开头，则添加 [HttpPut] 特性。
  • 以 Delete/Remove/Clear 开头，则添加 [HttpDelete] 特性。
  • 以 Patch 开头，则添加 [HttpPatch] 特性
  • 以 Head 开头，则添加 [HttpHead] 特性
  • 支持自定义配置
• 如果不在上面约定中，则默认添加 [HttpPost] 特性。支持自定义配置

但是，有些时候这不是我们想要的规则，这时我们只需要在 appsettings.json 中配置即可：

特别注意

5.1.8.16 路由参数非必填/选填​

在 Furion v2.8.6 版本中实现了 [FromRoute] 参数非必填功能，支持以下几种方式：

5.1.8.17 [FormRoute] 路由约束​

在 Furion v2.8.6 版本中，添加了 [RouteConstraint] 特性，可配置路由约束，如：[RouteConstraint(":min(10)")]

[RouteConstraint] 支持路由约束符号如下：

符号	描述	例子
*	匹配路由 0-n 长度，Furion 4.8.6.2+ 支持	:*
alpha	匹配大写或小写拉丁字母字符（a-z、A-Z）	:alpha
bool	bool 类型	:bool
datetime	DateTime 类型	:datetime
decimal	decimal 类型	:decimal
double	double 类型	:double
float	float 类型	:float
guid	guid 类型	:guid
int	int 类型	:int
long	long 类型	:long
length	匹配长度（字符串）	:length(6) 或 :length(1,20)
max	最大值	:max(10)
maxlength	最大长度（字符串）	:maxlength(10)
min	最小值	:min(10)
minlength	最小长度（字符串）	:minlength(10)
range	取值范围	:range(10,50)
regex	正则表达式	:regex(^\d{3}-\d{3}-\d{4}$)

5.1.8.18 小驼峰 路由路径

5.1.8.19 application/xml 报文参数支持​

1. 在 Startup.cs 中启用 XML 请求报文格式支持

 

2. 定义实体类型

3. 在动态 WebAPI 中使用

4. XML 格式说明及注意事项

支持两种 XML 格式报文，如：

• 第一种（常用格式）

• 第二种（标准格式）

 

 

5.1.9 [ApiDescriptionSettings]​

除了上述 ASP.NET Core 提供的配置外，Furion 框架还提供了非常强大且灵活的 [ApiDescriptionSettings] 特性。

5.1.9.1 内置配置​

• Name：自定义控制器/动作方法名称，string，默认 null
• KeepName：是否保持原有名称不处理，bool，默认 false
• SplitCamelCase：切割骆驼(驼峰)/帕斯卡命名，bool，默认 true
• KeepVerb：是否保留动作方法请求谓词，bool，默认 false
• Enabled：是否导出接口，bool，默认 true
• Module：模块名，string，默认 null
• Version：版本号，string，默认 null
• Groups：接口分组，可结合 Swagger 一起使用，string[]，默认 null
• Tags：接口标签，可结合 Swagger 一起使用，string[]，默认 null
• Order：配置控制器/动作方法排序，数值越大越靠前
• LowercaseRoute：是否采用小写路由，bool 类型，默认 true
• AsLowerCamelCase：启用小驼峰命名（首字母小写），默认 false
• Area：配置区域名称，默认空，只作用于类中贴
• Description：配置单一接口更多描述功能，只在 方法 中有效，仅限 v3.3.5+版本有效
• ForceWithRoutePrefix：配置是否强制添加 DefaultRoutePrefix，当控制器自定义了 [Route] 有效，默认 false，仅限 v3.4.1+版本有效

5.1.9.2 Name 配置​

Name 参数可以覆盖动态 WebAPI 自动生成的控制器或动作方法名称。如：

 

如下图所示：

5.1.9.3 KeepName 配置​

KeepName 参数可以保留原有的控制器或动作方法名称。如：

如下图所示：

5.1.9.4 SplitCamelCase 配置​

SplitCamelCase 参数默认将骆驼(驼峰)命名切割成多个单词并通过指定 占位符 连接起来。默认 占位符 为 -。默认为 true。如：

 

如下图所示：

5.1.9.5 KeepVerb 配置​

KeepVerb 参数作用于动作方法，标识是否保留动作谓词。如：

 

如下图所示：

5.1.9.6 Enabled 配置​

Enabled 参数配置接口是否导出。通常用于动作方法，如果用于控制器实际作用不大。

 

如下图所示：

5.1.9.7 Module 配置​

Module 参数可以配置路由分离，类似于 Mvc 区域 的作用。

 

如下图所示：

5.1.9.8 Version 配置​

Version 参数可以配置接口版本，同时又可以复写特殊版本命名配置。默认版本分隔符为 @。如：

 

如下图所示：

5.1.9.9 Groups 配置​

Groups 配置主要用于配置 Swagger 分组信息。

通过配置 Groups 参数可以将控制器和动作方法 进行归类和多个分组直接共享。可通过 [ApiDescriptionSettings(params Groups)] 构造函数传入或指定 Groups 参数配置接口是否导出。通常用于动作方法，如果用于控制器实际作用不大。

 

如下图所示：

5.1.9.10 Tag 配置​

Tag 配置主要用于配置 Swagger 标签分组信息及合并标签。也就是 组中组:

5.1.10 DynamicApiControllerSettings 配置​

Furion 还提供动态 WebAPI 接口一些全局配置选项，如：

• DefaultRoutePrefix：默认路由前缀，string，默认 api
• DefaultHttpMethod：默认请求谓词，string，默认：POST
• DefaultModule：默认模块名称（区域），可用作接口版本，string，默认：v1
• LowercaseRoute：小写路由格式，bool，默认：true
• AsLowerCamelCase：启用小驼峰命名（首字母小写），默认 false
• KeepVerb：是否保留动作谓词，bool，默认：false
• KeepName：是否保留默认名称，bool，默认：fasle
• CamelCaseSeparator：骆驼(驼峰)/帕斯卡命名分隔符，string，默认：-
• VersionSeparator：版本分隔符，string，默认：@
• ModelToQuery：GET/HEAD 请求将 类类型参数转查询参数，bool，默认 false
• SupportedMvcController：是否支持 Mvc Controller 动态配置，bool，默认 false
• UrlParameterization：路由参数采用 [FromQuery] 化，默认 false（[FromRoute] 方式）
• DefaultArea：配置默认区域，默认 null
• ForceWithRoutePrefix：配置是否强制添加 DefaultRoutePrefix，当控制器自定义了 [Route] 有效，仅限 v3.4.1+版本有效
• AbandonControllerAffixes：默认去除控制器名称前后缀列表名，string[]，默认：
  • AppServices
  • AppService
  • ApiController
  • Controller
  • Services
  • Service
• AbandonActionAffixes：默认去除动作方法名称前后缀列表名，string[]，默认：
  • Async
• VerbToHttpMethods：复写默认方法名转 [HttpMethod] 规则，string[][] 二维数组类型，内置匹配规则为：

• 复写示例

 

 

5.1.10.1 支持 Mvc 控制器 动态配置​

默认情况下，Furion 动态 WebAPI 接口不对 ControllerBase 类型进行任何处理。当然，我们也可以手动启用 ControllerBase 支持。

设置 SupportedMvcController: true 后，Mvc ControllerBase 类型也能和动态 WebAPI 一样的灵活了。代码如下：

 

5.1.11 关于 AOP 拦截​

动态WebAPI 支持 Controller 的所有过滤器/筛选器拦截，也就是可以通过 ActionFilter，ResultFilter 进行拦截操作。如：

 

详细用法可参见 ASP.NET Core 5.0 – 筛选器

5.1.12 设置 api 超时请求时间​

在 Program.cs 中添加 .UseKestrel 配置即可，如：

• .NET5 版本

.NET6 版本

5.1.13 获取路由/控制器/Action 列表​

有时候我们需要获取当前路由信息，或所有控制器、Action 列表，而已通过以下代码获取：

• 获取当前路由表信息（简易）

输出：

• 获取当前终点路由信息（简易）

 

• 获取所有控制器列表

 

• 获取所有 Action 列表（强大）

 

• 获取所有 Action 列表带分组信息（强大）