@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/05-1-/345/213/225/346/205/213WebAPI.md

@@ -0,0 +1,825 @@
+# 5.1 动态 WebAPI
+
+> **小知识**：动态 WebAPI 实际上就是将普通的类变为 Controller，也就是动态 WebAPI 就是控制器，支持控制器一切功能。
+
+---
+
+## 5.1.1 什么是控制器
+
+简单来说，控制器是一个承上启下的作用，根据用户输入，执行响应行为（动作方法），同时在行为中调用模型的业务逻辑，返回给用户结果（视图）。
+
+在 ASP.NET Core 中，控制器有两种表现形式：Mvc（带视图）和 WebAPI（RESTful API）。Mvc 控制器和 WebAPI 控制器最大的区别是 WebAPI 控制器不带视图和通过请求谓词和路由地址响应行为。
+
+---
+
+## 5.1.2 Mvc 控制器约定和缺点
+
+### 5.1.2.1 WebAPI 约定
+
+在 ASP.NET Core 应用中，一个 WebAPI 控制器需遵循以下约定：
+
+- 控制器类必须继承 `ControllerBase` 或间接继承
+- 动作方法必须贴有 `[HttpMethod]` 特性，如 `[HttpGet]`
+- 控制器或动作方法至少有一个配置 `[Route]` 特性
+- 生成 WebAPI 路由地址时会自动去掉控制器名称 `Controller` 后缀，同时也会去掉动作方法匹配的 HttpVerb 谓词
+- 不支持返回非 `IEnumerable<T>` 泛型对象
+- 不支持类类型参数在 GET、HEAD 请求下生成 Query 参数
+
+### 5.1.2.2 .NET Core WebAPI 缺点
+
+- 路由地址基本靠手工完成
+- 不利于进行多版本控制
+- 对接 Swagger 文档分组比较复杂
+- 实现 Policy 策略授权也比较复杂
+- 不支持控制器热插拔插件化
+- 难以实现复杂自定义的 RESTful API 风格
+
+---
+
+## 5.1.3 动态 WebAPI 控制器
+
+Furion 框架推出一种更加灵活创建 WebAPI 控制器的方式，在继承了 ASP.NET Core WebAPI 所有优点的同时进行了大量扩展和优化：
+
+- 具备原有的 `ControllerBase` 所有功能
+- 支持任意公开、非静态、非抽象、非泛型类转控制器
+- 提供 `IDynamicApiController` 空接口或 `[DynamicApiController]` 特性替代 `ControllerBase`
+- 可直接在任意公开非静态非抽象非泛型类贴 `[Route]` 特性自动转控制器
+- 无需手动配置 `[HttpMethod]` 特性，支持一个动作方法多个 HttpVerb
+- 无需手动配置 `[Route]` 特性，支持自动路由生成
+- 支持返回泛型接口、泛型类
+- 和 Swagger 深度结合
+- 支持 Basic Auth、Jwt、ApiKey 等多种权限配置
+- 支持控制器、动作方法版本控制功能
+- 支持 GET、HEAD 请求自动转换类类型参数
+- 支持生成 OAS3 接口规范
+
+---
+
+## 5.1.4 注册动态 WebAPI 服务
+
+> **小提示**：`.AddDynamicApiControllers()` 默认已经集成在 `AddInject()` 中了，无需再次注册。
+
+```csharp
+// Furion.Web.Core\FurWebCoreStartup.cs
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Furion.Web.Core
+{
+    [AppStartup(800)]
+    public sealed class FurWebCoreStartup : AppStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddControllers()
+                    .AddDynamicApiControllers();
+        }
+    }
+}
+```
+
+> ⚠️ `.AddDynamicApiControllers()` 必须在 `services.AddControllers()` 之后注册。
+
+---
+
+## 5.1.5 第一个例子
+
+创建一个类继承 `IDynamicApiController` 接口或贴 `[DynamicApiController]` 特性：
+
+**IDynamicApiController 方式：**
+
+```csharp
+using Furion.DynamicApiController;
+
+namespace Furion.Application
+{
+    public class FurionAppService : IDynamicApiController
+    {
+        public string Get()
+        {
+            return $"Hello {nameof(Furion)}";
+        }
+    }
+}
+```
+
+**[DynamicApiController] 方式：**
+
+```csharp
+using Furion.DynamicApiController;
+
+namespace Furion.Application
+{
+    [DynamicApiController]
+    public class FurionAppService
+    {
+        public string Get()
+        {
+            return $"Hello {nameof(Furion)}";
+        }
+    }
+}
+```
+
+**[Route("路由模板")] 方式（Furion 4.9.2.19+）：**
+
+```csharp
+[Route("[controller]")]
+public class RouteController
+{
+    public void Get()
+    {
+    }
+}
+```
+
+---
+
+## 5.1.6 动态 WebAPI 原理解析
+
+### 5.1.6.1 控制器特性提供器
+
+Furion 框架在应用启动时注册 `DynamicApiControllerFeatureProvider` 控制器特性提供器，重写 `IsController` 方法来标识控制器类型。继承自 `ControllerBase` 类、`IDynamicApiController` 接口或贴 `[DynamicApiController]` 特性都会被标记为控制器类型。
+
+### 5.1.6.2 应用模型转换器
+
+同时注册 `DynamicApiControllerApplicationModelConvention` 应用模型转换器，在其中配置控制器名称、路由、导出可见性及动作方法名称、路由等，按照 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_]` 结尾的，会自动生成版本号。
+- 动作方法名称以骆驼/帕斯卡命名会自动切割成 `-` 连接。
+- 动作方法参数将自动转为小写。
+
+### 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 多种请求谓词方法
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public string Get() => "GET 请求";
+    public string Post() => "POST 请求";
+    public string Delete() => "DELETE 请求";
+    public string Put() => "PUT 请求";
+    public string Patch() => "PATCH 请求";
+}
+```
+
+### 5.1.8.2 多个自定义动作方法
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public string GetVersion() => "v1.0.0";
+    public string ChangeProfile() => "修改成功";
+    public string DeleteUser() => "删除成功";
+}
+```
+
+### 5.1.8.3 带参数动作方法
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public string GetUser(int id) => $"{id}";
+    public string GetUser(int id, string name) => $"{id} {name}";
+    public TestDto Add(TestDto testDto) => testDto;
+}
+```
+
+### 5.1.8.4 GET/HEAD 类类型参数
+
+默认情况下，ASP.NET Core 会将 GET/HEAD 请求中的类类型参数设置为 `[FromBody]` 绑定，但 GET、HEAD 请求不支持 From Body 绑定。
+
+两种解决方式：
+
+**方式一：`[FromQuery]` 特性**
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public TestDto GetTest([FromQuery] TestDto testDto) => testDto;
+}
+```
+
+**方式二：配置 `DynamicApiControllerSettings`**（见 5.1.10 节的 `ModelToQuery` 配置）
+
+### 5.1.8.5 自定义参数位置
+
+通过 `[ApiSeat]` 可配置参数在路由中的位置：
+
+| 值 | 说明 |
+|----|------|
+| `ApiSeats.ControllerStart` | 控制器之前 |
+| `ApiSeats.ControllerEnd` | 控制器之后 |
+| `ApiSeats.ActionStart` | 动作方法之前 |
+| `ApiSeats.ActionEnd` | 动作方法之后（默认值） |
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public string RouteSeat(
+        [ApiSeat(ApiSeats.ControllerStart)] int id,
+        [ApiSeat(ApiSeats.ControllerEnd)] string name,
+        [ApiSeat(ApiSeats.ActionStart)] decimal weight,
+        [ApiSeat(ApiSeats.ActionEnd)] DateTime birthday)
+    {
+        return "配置路由参数位置";
+    }
+}
+```
+
+> **特别注意**：`[ApiSeat]` 只能应用于贴了 `[FromRoute]` 特性的参数或基元类型、值类型、可空基元类型和可空值类型。
+
+### 5.1.8.6 自定义请求谓词
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    [HttpPost]
+    public string GetVersion() => "1.0.0";
+}
+```
+
+### 5.1.8.7 支持多个谓词
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    [HttpPost, HttpGet, AcceptVerbs("PUT", "DELETE")]
+    public string GetVersion() => "1.0.0";
+}
+```
+
+> ⚠️ 如果动作方法中含有类类型参数，且含有 POST/PUT/DELETE 任意请求谓词，那么该参数会自动添加 `[FromBody]`，即使在 GET/HEAD 请求中不支持。
+
+### 5.1.8.8 支持自定义路由
+
+```csharp
+// 自定义控制器路由
+[Route("customapi/mobile/[controller]")]
+public class FurionAppService : IDynamicApiController
+{
+    public string GetVersion() => "1.0.0";
+}
+```
+
+> **小提示**：动作方法自定义路由如果以 `/` 开头，则不会合并控制器路由。推荐使用 `[controller]` 或 `[action]` 占位符。
+
+### 5.1.8.9 多路由随意组合
+
+```csharp
+[Route("api/[controller]")]
+[Route("api/[controller]/second")]
+[Route("api/[controller]/three")]
+public class FurionAppService : IDynamicApiController
+{
+    [HttpGet]
+    [HttpGet("get/[action]")]
+    [HttpPost]
+    [HttpPost("post/cus-version")]
+    public string GetVersion() => "1.0.0";
+}
+```
+
+> ⚠️ 动作方法不能同时贴 `[Route]` 和 `[HttpMethod]` 特性，只能二取一。
+
+### 5.1.8.10 支持版本控制
+
+```csharp
+public class FurionAppServiceV1 : IDynamicApiController
+{
+    public string Get() => nameof(Furion);
+}
+
+public class FurionAppServiceV1_2 : IDynamicApiController
+{
+    public string Get() => nameof(Furion);
+}
+
+public class FurionAppServiceV1_2_1 : IDynamicApiController
+{
+    public string Get() => nameof(Furion);
+}
+```
+
+> **版本生成原理**：`V[0-9_]` 结尾的命名自动解析成版本号，如 `FurionAppServiceV2` → `v2/Furion`。
+
+版本复写：
+
+```csharp
+[ApiDescriptionSettings(Version = "4.0")]
+public string GetV1() => nameof(Furion);
+```
+
+### 5.1.8.11 不公开控制器或动作方法
+
+```csharp
+public class FurionAppService : IDynamicApiController
+{
+    public string Export() { /* .... */ }
+
+    [ApiDescriptionSettings(false)] // 不在 Swagger 上显示
+    public string NoExport() { /* ... */ }
+
+    [ApiDescriptionSettings(IgnoreApi = true)] // 不在 Swagger 上显示
+    public string NoExport2() { /* ... */ }
+
+    [NonAction] // 不是一个 API
+    public string IsNotAPI() { /* ... */ }
+}
+
+[ApiDescriptionSettings(false)] // 不导出整个控制器
+public class NoExportServices : IDynamicApiController { }
+
+[NonController] // 标记不是一个控制器
+public class TestController : ControllerBase { }
+```
+
+### 5.1.8.12 保持控制器和方法命名
+
+```json
+{
+  "DynamicApiControllerSettings": {
+    "KeepName": true,
+    "KeepVerb": true,
+    "LowercaseRoute": false
+  }
+}
+```
+
+### 5.1.8.13 方法参数 [FromQuery] 化
+
+```csharp
+[QueryParameters]
+public string Get(int id, string name)
+{
+    return $"{id} {name}";
+}
+// 生成的路由为：https://xxx.com?id=1&name=Furion
+```
+
+全局配置（只影响基元类型参数）：
+
+```json
+{
+  "DynamicApiControllerSettings": {
+    "UrlParameterization": true
+  }
+}
+```
+
+> ⚠️ 贴了 `[QueryParameters]` 之后会对所有参数影响，如不需要处理某个参数，只需贴 `[FromXXX]` 特性即可。
+
+### 5.1.8.14 参数绑定配置
+
+- `[FromRoute]`：通过路由参数绑定值
+- `[FromQuery]`：通过 Url 地址参数绑定值
+- `[FromBody]`：通过 Request Body 参数绑定值
+- `[FromForm]`：通过表单提交绑定值
+- `[FromHeader]`：通过 Request Header 参数绑定值
+
+### 5.1.8.15 自定义根据方法名生成 [HttpMethod] 规则
+
+在 `appsettings.json` 中配置：
+
+```json
+{
+  "DynamicApiControllerSettings": {
+    "VerbToHttpMethods": [
+      ["getall", "HEAD"],
+      ["other", "PUT"]
+    ]
+  }
+}
+```
+
+> ⚠️ 二维数组中每个元素的第一个必须**全小写**，第二个必须**全大写**，取值有：`HEAD`、`GET`、`PUT`、`POST`、`PATCH`、`DELETE`。
+
+### 5.1.8.16 路由参数非必填/选填
+
+```csharp
+// 方式一：可空 ?
+public object Method1(int id, DateTime? dateTime) { }
+
+// 方式二：默认值
+public object Method1(int id, int age = 10) { }
+
+// 方式三：默认值 + 可空 ?
+public object Method1(int id, int? age = 10) { }
+
+// 方式四：[FromQuery] 修饰
+public object Method1(int id, [FromQuery] string keyword) { }
+```
+
+### 5.1.8.17 [FromRoute] 路由约束
+
+通过 `[RouteConstraint]` 特性配置路由约束：
+
+```csharp
+public object Method1([RouteConstraint(":min(10)")] int id) { }
+```
+
+支持的路由约束符号：
+
+| 符号 | 描述 | 例子 |
+|------|------|------|
+| `*` | 匹配路由 0-n 长度（4.8.6.2+） | `:*` |
+| `alpha` | 匹配拉丁字母字符 | `: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 小驼峰路由路径
+
+```json
+{
+  "DynamicApiControllerSettings": {
+    "LowercaseRoute": false,
+    "KeepName": true,
+    "AsLowerCamelCase": true
+  }
+}
+```
+
+### 5.1.8.19 application/xml 报文参数支持
+
+在 `Startup.cs` 中启用 XML 请求报文格式支持：
+
+```csharp
+services.AddControllers()
+        .AddXmlSerializerFormatters()
+        .AddXmlDataContractSerializerFormatters();
+```
+
+> 如果出现 `XmlSerializer` 异常，移除 `.AddXmlSerializerFormatters()` 即可。
+
+在动态 WebAPI 中使用：
+
+```csharp
+public class XmlDemo : IDynamicApiController
+{
+    //[Consumes("application/xml")] // 设置了则只能传递 XML 格式，不设置则支持多种
+    public People Test(People people) => people;
+}
+```
+
+> **`[Consumes]` 和 `[Produces]` 说明**：`[Consumes]` 定义输入参数格式（对应请求报文的 accept），`[Produces]` 定义返回值格式（对应响应报文的 content-type）。
+
+### 5.1.8.20 监听请求取消 CancellationToken 参数
+
+> **版本说明**：Furion 4.9.2.19+ 版本使用。
+
+```csharp
+[HttpGet]
+public async Task SomeApi(CancellationToken cancellationToken)
+{
+    cancellationToken.Register(() =>
+    {
+        Console.WriteLine("用户中断了请求。");
+    });
+
+    await Task.Run(() => { /* 模拟异步操作 */ }, cancellationToken);
+}
+```
+
+### 5.1.8.21 忽略参数绑定（生成路由）
+
+> **版本说明**：Furion 4.9.2.25+ 版本使用。
+
+```csharp
+public void TestBindNever([BindNever] string never, int id) { }
+```
+
+忽略某个类型的属性：
+
+```csharp
+[Newtonsoft.Json.JsonIgnore]                        // 针对 Newtonsoft
+[System.Text.Json.Serialization.JsonIgnore]         // 针对 System.Text.Json
+public string PropertyName { get; set; }
+```
+
+### 5.1.8.22 绑定数组类型 URL 参数
+
+> **版本说明**：Furion 4.9.3.5+ 版本使用。
+
+```csharp
+public void GetArray([FromQuery] [FlexibleArray<string>] List<string> status) { }
+```
+
+支持 `status[]=a&status[]=b` 和 `status=a,b` 两种格式。`FlexibleArray` 的泛型类型 `T` 为数组元素的类型，支持在属性和参数上标注。
+
+---
+
+## 5.1.9 [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` | string[] | null | 接口分组，可结合 Swagger 使用 |
+| `Tags` | string[] | null | 接口标签，可结合 Swagger 使用 |
+| `Order` | int | 0 | 配置排序，数值越大越靠前 |
+| `LowercaseRoute` | bool | true | 是否采用小写路由 |
+| `AsLowerCamelCase` | bool | false | 启用小驼峰命名（首字母小写） |
+| `Area` | string | 空 | 配置区域名称，只作用于类 |
+| `Description` | string | null | 更多描述功能，只在方法中有效（v3.3.5+） |
+| `ForceWithRoutePrefix` | bool | false | 是否强制添加 DefaultRoutePrefix（v3.4.1+） |
+| `DisableInherite` | bool | false | 是否被派生类继承时生成路由（4.9.5.8+） |
+
+### 5.1.9.2 ~ 5.1.9.10 各配置示例
+
+**Name 配置：**
+
+```csharp
+[ApiDescriptionSettings(Name = "MyFur")]
+public class FurionAppService : IDynamicApiController
+{
+    [ApiDescriptionSettings(Name = "MyGet")]
+    public string Get() => nameof(Furion);
+}
+```
+
+**KeepName 配置：** 保留原有的控制器或动作方法名称。
+
+**SplitCamelCase 配置：** 默认将骆驼命名切割成多个单词并通过 `-` 连接。`KeepName` 优先级高于 `SplitCamelCase`。
+
+**KeepVerb 配置：** 标识是否保留动作谓词。
+
+**Enabled 配置：** `[ApiDescriptionSettings(false)]` 不导出接口。
+
+**Module 配置：** 配置路由分离，类似于 Mvc 区域的作用。
+
+```csharp
+[ApiDescriptionSettings(Module = "mobile")]
+public class FurionAppService : IDynamicApiController
+{
+    [ApiDescriptionSettings(Module = "user")]
+    public string GetVersion() => nameof(Furion);
+}
+```
+
+**Version 配置：** 配置接口版本，可复写特殊版本命名配置。默认版本分隔符为 `@`。
+
+**Groups 配置：** 配置 Swagger 分组信息，将控制器和动作方法进行归类和多个分组共享。
+
+**Tag 配置：** 配置 Swagger 标签分组信息及合并标签（组中组）。如果 `Tag` 名字一样则会自动合并。
+
+---
+
+## 5.1.10 DynamicApiControllerSettings 配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `DefaultRoutePrefix` | string | `api` | 默认路由前缀 |
+| `DefaultHttpMethod` | string | `POST` | 默认请求谓词 |
+| `DefaultModule` | string | null | 默认模块名称（区域） |
+| `LowercaseRoute` | bool | true | 小写路由格式 |
+| `AsLowerCamelCase` | bool | false | 启用小驼峰命名 |
+| `KeepVerb` | bool | false | 是否保留动作谓词 |
+| `KeepName` | bool | false | 是否保留默认名称 |
+| `CamelCaseSeparator` | string | `-` | 骆驼命名分隔符 |
+| `VersionSeparator` | string | `v`（4.9.1.14+ 之前为 `@`） | 版本分隔符 |
+| `VersionInFront` | bool | true | 版本号是否在前面（4.9.1.14+） |
+| `ModelToQuery` | bool | false | GET/HEAD 类类型参数转查询参数 |
+| `SupportedMvcController` | bool | false | 是否支持 Mvc Controller 动态配置 |
+| `UrlParameterization` | bool | false | 路由参数采用 [FromQuery] 化 |
+| `DefaultArea` | string | null | 配置默认区域 |
+| `ForceWithRoutePrefix` | bool | false | 强制添加 DefaultRoutePrefix（v3.4.1+） |
+| `AbandonControllerAffixes` | string[] | `AppServices, AppService, ApiController, Controller, Services, Service` | 去除控制器名称前后缀列表 |
+| `AbandonActionAffixes` | string[] | `Async` | 去除动作方法名称前后缀列表 |
+| `VerbToHttpMethods` | string[][] | 内置规则 | 复写方法名转 HttpMethod 规则 |
+| `DefaultBindingInfo` | string | `route` | 默认基元参数绑定方式（4.9.2.32+） |
+
+### 5.1.10.1 支持 Mvc 控制器动态配置
+
+```json
+{
+  "DynamicApiControllerSettings": {
+    "SupportedMvcController": true
+  }
+}
+```
+
+> **注意事项**：启用该配置后，如果 Mvc 控制器没有任何 `[Route]` 特性但贴了 `[ApiController]` 特性将会报错。建议使用 `[ApiDataValidation]` 代替。
+
+---
+
+## 5.1.11 关于 AOP 拦截
+
+动态 WebAPI 支持 Controller 的所有过滤器/筛选器拦截：
+
+```csharp
+public class SampleAsyncActionFilter : IAsyncActionFilter
+{
+    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
+    {
+        // 拦截之前
+        var resultContext = await next();
+        // 拦截之后
+
+        if (resultContext.Exception != null)
+        {
+            // 异常拦截
+        }
+    }
+}
+```
+
+---
+
+## 5.1.12 设置 api 超时请求时间
+
+**.NET5 版本：**
+
+```csharp
+webBuilder.UseKestrel(option =>
+{
+    option.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(20);
+    option.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(20);
+});
+```
+
+**.NET6 版本：**
+
+```csharp
+app.Configuration.Get<WebHostBuilder>().ConfigureKestrel(x =>
+{
+    x.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(20);
+    x.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(20);
+});
+```
+
+---
+
+## 5.1.13 获取路由/控制器/Action 列表
+
+**获取当前路由表信息：**
+
+```csharp
+var routeValuesFeature = _httpContextAccessor.HttpContext.Features.Get<IRouteValuesFeature>();
+var routeValues = routeValuesFeature.RouteValues;
+```
+
+**获取当前终点路由信息：**
+
+```csharp
+var endpointFeature = _httpContextAccessor.HttpContext.Features.Get<IEndpointFeature>();
+var routeEndpoint = endpointFeature.Endpoint as RouteEndpoint;
+var routePattern = routeEndpoint.RoutePattern;
+var metadata = routeEndpoint.Metadata;
+```
+
+**获取所有控制器列表：**
+
+```csharp
+var controllerFeature = new ControllerFeature();
+_applicationPartManager.PopulateFeature(controllerFeature);
+IList<TypeInfo> controllers = controllerFeature.Controllers;
+```
+
+**获取所有 Action 列表：**
+
+```csharp
+var actionDescriptors = _actionDescriptorCollectionProvider.ActionDescriptors.Items;
+
+foreach (ActionDescriptor actionDescriptor in actionDescriptors)
+{
+    var method = (actionDescriptor as ControllerActionDescriptor).MethodInfo;
+    var route = actionDescriptor.AttributeRouteInfo.Template;
+    var httpMethod = actionDescriptor.ActionConstraints?.OfType<HttpMethodActionConstraint>()
+        .FirstOrDefault()?.HttpMethods.First();
+}
+```
+
+**获取所有 Action 列表带分组信息：**
+
+```csharp
+var apiDescriptionGroups = _apiDescriptionGroupCollectionProvider.ApiDescriptionGroups.Items;
+
+foreach (ApiDescriptionGroup group in apiDescriptionGroups)
+{
+    foreach (ApiDescription action in group.Items)
+    {
+        var route = action.RelativePath;
+        var httpMethod = action.HttpMethod;
+        var groupName = action.GroupName;
+    }
+}
+```
+
+---
+
+## 5.1.14 插件化 IDynamicApiRuntimeChangeProvider
+
+> **版本说明**：Furion 4.8.8.8+ 版本使用。
+
+在运行时动态编译代码并添加为 WebAPI：
+
+```csharp
+public class PluginApiServices : IDynamicApiController
+{
+    private readonly IDynamicApiRuntimeChangeProvider _provider;
+
+    public PluginApiServices(IDynamicApiRuntimeChangeProvider provider)
+    {
+        _provider = provider;
+    }
+
+    public string Compile([FromBody] string csharpCode, [FromQuery] string assemblyName = default)
+    {
+        var dynamicAssembly = App.CompileCSharpClassCode(csharpCode, assemblyName);
+        _provider.AddAssembliesWithNotifyChanges(dynamicAssembly);
+        return dynamicAssembly.GetName().Name;
+    }
+
+    public void Remove(string assemblyName)
+    {
+        _provider.RemoveAssembliesWithNotifyChanges(assemblyName);
+    }
+}
+```
+
+请求 `api/plugin-api/compile` 接口并设置 `Content-Type` 为 `text/plain`，传入 C# 代码字符串即可。刷新浏览器即可看到最新的 API。
+
+---
+
+## 5.1.15 自定义生成 API 规则
+
+```csharp
+services.ConfigureDynamicApiController(builder =>
+{
+    // 自定义控制器生成逻辑
+    builder.ControllerFilter = (type) =>
+    {
+        return type != typeof(PersonService); // 排除特定类型
+    };
+
+    // 自定义 Action 生成配置
+    builder.ActionConfigure = (actionModel) =>
+    {
+        if (actionModel.ActionMethod.Name == "Insert")
+        {
+            actionModel.ApiExplorer.IsVisible = false;
+        }
+    };
+});
+```
+
+> **注意**：请确保在 `AddInject()` 或 `AddDynamicApiControllers` 之前注册。