ASP.NET Core Minimal APIs 入门指南 - JetBrains 博客

为什么选择 ASP.NET Core Minimal API？

在多个版本的 .NET Core 和 .NET 中，性能始终是 .NET 团队关注的重点。尽管 ASP.NET Core MVC 是构建 Web API 的一种强大且成熟的方法，但其复杂的 MVC 管道可能会在处理 HTTP 请求时消耗大量时间和资源。

ASP.NET Core MVC 的标准请求处理步骤包括路由、控制器初始化、模型绑定、执行操作过滤器和结果过滤器等，通常需要经过 17 个步骤。如果使用视图引擎，步骤还会更多。而在构建基于 JSON 的 API 时，这些步骤可能显得冗余，从而限制了吞吐量的提升空间。

此外，ASP.NET Core MVC 的“约定优于配置”模式虽然强大，但有时会显得过于复杂。例如，路由的注册依赖于扫描路由属性或匹配用户定义的路由模式，这种方式可能会导致应用程序结构与代码分离，增加了开发和调试的难度。

Minimal API 则更符合现代微服务开发的编程模式，强调简化和明确性。通过 Minimal API，开发者可以将功能集中在单个文件中，代码更易于阅读和维护。与 ASP.NET Core MVC 的复杂结构相比，Minimal API 提供了更轻量级的开发体验。

值得一提的是，ASP.NET Core 的组件化设计允许开发者在同一应用中混合使用 MVC、Razor Pages 和 Minimal API。这种灵活性使得 Minimal API 成为优化现有代码库的一个有力工具，而不是完全替代现有框架。

创建第一个 Minimal API 应用程序

要开始使用 Minimal API，可以创建一个新的 ASP.NET Core 项目，选择“空”项目模板。创建完成后，项目中会包含一个 Program.cs 文件，代码如下：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

代码解析

1. WebApplication.CreateBuilder：该方法用于注册 Web 应用程序主机的常用组件，例如配置、日志记录、路由等。开发者可以在此阶段通过注册服务、读取配置等方式增强主机功能。
2. app.MapGet：用于定义一个 GET 请求的端点。Minimal API 支持所有常见的 HTTP 方法（如 GET、POST、PUT、PATCH、DELETE 等）。
3. app.Run：启动应用程序并开始监听传入的请求。

Minimal API 的核心是 RequestDelegate，它是一个简单的委托，接受一个 HttpContext 参数并返回一个任务：

public delegate Task RequestDelegate(HttpContext context);

通过依赖注入，开发者可以将额外的参数传递给端点定义，从而增强其功能。

模型绑定与返回类型

Minimal API 提供了简化的模型绑定机制。以下是一个示例，展示如何使用 POST 方法处理请求并返回结果：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/hugs", (Hug hug) =>
    Results.Ok(new Hugged(hug.Name, "Side Hug"))
);

app.Run();

public record Hug(string Name);
public record Hugged(string Name, string Kind);

模型绑定

Minimal API 的模型绑定机制会将请求体（假设为 JSON 格式）直接反序列化为指定的模型类型。例如，上述代码中的 Hug 模型会自动绑定到请求体中的 JSON 数据：

POST http://localhost:5272/hugs
Content-Type: application/json

{ "Name": "Khalid Abuhakmeh" }

返回类型

Minimal API 提供了 Results 类，用于简化常见的状态码和响应类型处理。开发者可以使用 Results.Ok、Results.Json 等方法快速生成响应。

依赖注入与服务

Minimal API 完全支持 ASP.NET Core 的依赖注入机制。以下示例展示了如何通过依赖注入实现服务的重构：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(new HuggingService());
var app = builder.Build();

app.MapPost("/hugs", (Hug hug, HuggingService hugger) =>
    Results.Ok(hugger.Hug(hug))
);

app.Run();

public record Hug(string Name);
public record Hugged(string Name, string Kind);

public class HuggingService
{
    private readonly string[] _hugKinds = { "Side Hug", "Bear Hug", "Polite Hug", "Back Hug", "Self Hug" };

    public Hugged Hug(Hug hug) =>
        new(hug.Name, _hugKinds[new Random().Next(_hugKinds.Length)]);
}

在上述代码中，HuggingService 被注册为单例服务，并通过依赖注入传递给端点处理函数。

请求与响应过滤器

ASP.NET Core 7 引入了 Minimal API 过滤器，用于减少重复代码。以下示例展示了如何添加一个时间戳过滤器：

async ValueTask