使用ASP.NET Core中的Minimal API快速构建轻量级Web服务插图

使用ASP.NET Core Minimal API：告别繁琐配置，极速构建轻量级Web服务

作为一名常年与各种Web框架打交道的开发者，我经历过从ASP.NET Web Forms到MVC的变迁。每次新项目启动，面对那些几乎成为模板的Controller、Startup.cs里成堆的中间件配置，我偶尔会想：如果我只是想快速暴露几个简单的HTTP端点（Endpoint），有没有更“轻”的方式？直到ASP.NET Core 6推出了Minimal API，我仿佛找到了答案。它不是什么颠覆性的新框架，而是一种更符合现代开发直觉的、极简的编程模型。今天，我就带你一起上手，用最少的代码，构建一个功能完整的待办事项（Todo）API服务，并分享我在实战中踩过的坑和收获。

一、开箱即用：创建你的第一个Minimal API项目

首先，确保你安装了.NET 6或更高版本的SDK。打开你熟悉的终端（我常用PowerShell或VS Code的集成终端），让我们用一行命令开始：

dotnet new web -n TodoMinimalApi -o .

这个命令在当前目录创建了一个最基础的ASP.NET Core Web项目。用你喜欢的IDE（VS Code、Rider或Visual Studio）打开项目，你会发现项目结构异常清爽。没有`Startup.cs`，没有`Controllers`文件夹，所有的魔法都始于`Program.cs`这一个文件。

打开`Program.cs`，你会看到类似下面的代码：

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

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

app.Run();

这就是Minimal API的核心！没有多余的仪式感，`WebApplication`就是我们的应用入口。`app.MapGet`定义了一个对根路径`“/”`的GET请求处理程序，它直接返回一个字符串。运行项目：

dotnet run

访问 `https://localhost:5001` 或 `http://localhost:5000`，你就能看到“Hello World!”。一个Web服务在几行代码内就跑起来了，这种即时反馈感非常棒。

二、定义模型与内存数据存储

为了构建Todo API，我们需要先定义数据模型。在项目根目录创建一个`Models`文件夹，并添加`TodoItem.cs`：

namespace TodoMinimalApi.Models;

public class TodoItem
{
    public int Id { get; set; }
    public string? Title { get; set; }
    public bool IsCompleted { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

为了简单起见，我们不引入数据库，使用一个静态的`List`作为内存存储。在实际生产环境中，你肯定会换成真正的数据库（如SQL Server、PostgreSQL或SQLite），Minimal API与Entity Framework Core的集成同样丝滑，这点我们稍后提及。

回到`Program.cs`，在文件顶部，我们先声明这个内存列表：

using TodoMinimalApi.Models;

// 内存数据存储
var todoItems = new List
{
    new TodoItem { Id = 1, Title = "学习Minimal API", IsCompleted = true },
    new TodoItem { Id = 2, Title = "写一篇技术博客", IsCompleted = false }
};

三、实现CRUD端点：GET、POST、PUT、DELETE

现在，让我们用Minimal API的路由映射方法来实现完整的RESTful API。

1. 获取所有Todo项 (GET /api/todos)

app.MapGet("/api/todos", () => Results.Ok(todoItems));

`Results.Ok()`是一个帮助方法，它会返回200状态码和我们的数据。Minimal API内置了一系列这样的`Results`方法，非常方便。

2. 根据ID获取单个Todo项 (GET /api/todos/{id})

app.MapGet("/api/todos/{id}", (int id) =>
{
    var todo = todoItems.FirstOrDefault(t => t.Id == id);
    return todo is null ? Results.NotFound() : Results.Ok(todo);
});

注意路由中的`{id}`参数，它会自动绑定到处理程序的`id`参数上。如果没找到，我们返回404。

3. 创建新的Todo项 (POST /api/todos)

这里需要从请求体中接收数据。我们需要先启用JSON反序列化服务。

var builder = WebApplication.CreateBuilder(args);
// 添加JSON序列化服务，这是处理请求体所必需的
builder.Services.AddControllers(); // 或者更精确地：builder.Services.Configure(...)

var app = builder.Build();

然后定义POST端点：

app.MapPost("/api/todos", (TodoItem newTodo) =>
{
    // 简单的验证
    if (string.IsNullOrEmpty(newTodo.Title))
        return Results.BadRequest("Title is required.");

    newTodo.Id = todoItems.Max(t => t.Id) + 1; // 生成新ID
    newTodo.CreatedAt = DateTime.UtcNow;
    todoItems.Add(newTodo);

    // 返回201 Created状态码，并在Location头中提供新资源的URI
    return Results.Created($"/api/todos/{newTodo.Id}", newTodo);
});

踩坑提示：我第一次尝试时，直接写`(TodoItem newTodo)`，但请求一直报400错误，提示无法反序列化。原因是Minimal API默认没有配置模型绑定所需的某些服务。最简单的解决方案就是上面提到的，在`builder`中调用`builder.Services.AddControllers()`。这个方法会注册MVC所需的服务，其中就包含了JSON输入格式化器，完美解决了我们的问题。虽然我们不用Controller，但可以借用它的服务。

4. 更新Todo项 (PUT /api/todos/{id})

app.MapPut("/api/todos/{id}", (int id, TodoItem updatedTodo) =>
{
    var existingTodo = todoItems.FirstOrDefault(t => t.Id == id);
    if (existingTodo is null)
        return Results.NotFound();

    // 更新字段
    existingTodo.Title = updatedTodo.Title;
    existingTodo.IsCompleted = updatedTodo.IsCompleted;

    return Results.NoContent(); // 204 No Content，更新成功通常不返回内容
});

5. 删除Todo项 (DELETE /api/todos/{id})

app.MapDelete("/api/todos/{id}", (int id) =>
{
    var todoToRemove = todoItems.FirstOrDefault(t => t.Id == id);
    if (todoToRemove is null)
        return Results.NotFound();

    todoItems.Remove(todoToRemove);
    return Results.NoContent();
});

四、进阶技巧：依赖注入、验证与Swagger文档

一个健壮的API还需要依赖注入(DI)、数据验证和API文档。

依赖注入

假设我们抽象出一个`ITodoService`。Minimal API的DI容器使用方式和传统方式完全一致：

builder.Services.AddScoped();

// 然后在端点中注入
app.MapGet("/api/todos", (ITodoService service) => Results.Ok(service.GetAll()));

框架会自动将注册的服务注入到处理程序的参数中。

数据验证

我们可以使用`System.ComponentModel.DataAnnotations`命名空间下的特性进行验证：

using System.ComponentModel.DataAnnotations;

public class TodoItem
{
    public int Id { get; set; }

    [Required, MinLength(3)]
    public string? Title { get; set; }
    // ... 其他属性
}

并在端点中通过`IValidator`或手动验证，但更简洁的方式是使用社区库（如`FluentValidation`）或配合`.NET 7+`的端点过滤器（Endpoint Filter）。

集成Swagger/OpenAPI

这是让API变得专业和易用的关键。添加NuGet包`Swashbuckle.AspNetCore`，然后在`Program.cs`中配置：

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

运行项目，访问 `/swagger`，你就会得到一个漂亮的交互式API文档页面，所有我们定义的端点一目了然，并且可以直接测试！

五、总结与实战心得

通过这个简单的Todo API项目，我们已经领略了Minimal API的核心魅力：简洁、直观、高效。它特别适合微服务、原型开发、小型后台服务或只需要少数端点的场景。它减少了模板代码，让开发者更专注于业务逻辑本身。

我的实战建议：

  1. 保持`Program.cs`的整洁：当端点超过10个时，考虑按功能模块将端点定义拆分到扩展方法或单独的类中，否则`Program.cs`会变得臃肿。
  2. 善用`Results`类：它提供了丰富的静态方法（`Ok`, `Created`, `NotFound`, `BadRequest`等），能帮你快速构建符合HTTP语义的响应。
  3. 别忘了中间件：Minimal API同样支持完整的中间件管道。认证(`UseAuthentication`)、授权(`UseAuthorization`)、异常处理(`UseExceptionHandler`)、CORS等都可以像往常一样配置。
  4. 性能考量：由于其轻量级设计，Minimal API在请求处理开销上通常有微小的优势，但对于复杂应用，主要的性能瓶颈依然在数据库和业务逻辑。

总之，ASP.NET Core Minimal API是一个强大的工具，它并非要取代MVC，而是为我们提供了另一种更契合“API优先”思维的选择。下次当你需要快速搭建一个轻量级服务时，不妨从它开始，体验一下这种“少即是多”的编程乐趣。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。