组织ASP.NET Core Minimal APIs - Tess Ferrandez

我经常听到有人在社交媒体或评论中提到，认为“最小化 API”并不适合用于“真实生产”环境的应用程序。

这种观点的产生，可能是因为我们通常看到的示例代码过于简单，没有展示如何以一种对更大规模应用程序有意义的方式来组织代码。然而，坦率地说，许多所谓的“真实生产”应用程序本身也并不复杂，这又是另一个话题。

在过去两年里，我与许多大型组织合作，帮助他们将工作负载迁移到 Azure（API 框架（如 FastAPI 和 Flask）。

不过，在 ASP.NET 中，许多示例代码通常会将端点直接写在 Program.cs 文件中，代码以内联的方式呈现（如下所示）。这种方式并不适合更大规模的应用程序，因此，我想分享一些简单的步骤，帮助开发者更好地组织代码，使其更易于维护。

使用扩展方法组织端点

组织端点的一种简单方法是使用扩展方法。

我们可以在一个名为 Endpoints 的文件夹中，或者在一个特定的功能文件夹（如 TodoItems 文件夹）中创建一个名为 TodoItemEndpoints.cs 的文件，并在其中添加以下代码：

public static class TodoItemEndpoints
{
    public static void MapTodoItemEndpoints(this IEndpointRouteBuilder routes)
    {
        routes.MapGet("/todoitems", async (DbContext db) =>
        {
            return await db.TodoItems.ToListAsync();
        });
    }
}

通过这种方式，我们可以将端点的定义与主程序文件分离，从而使代码更加模块化和清晰。

使用 TypedResults 而不是 Results

为了让代码更清晰，我们可以使用 TypedResults 替代 Results。

当使用 Results 时，通常需要添加一个 Produces 属性，以便为 Swagger 等工具指定有效的响应类型。而使用 TypedResults 后，可以直接从返回类型中推断出响应类型，从而省略 Produces 属性。这不仅减少了代码的冗余，还能在编译时检查错误，使单元测试更加简单。

例如：

return TypedResults.Ok(todoItem);

这种方法可以显著提升代码的可读性和可靠性。

将功能与端点注册分开

尽管我们已经将端点定义移到了单独的文件中，但代码可能仍然显得混乱且难以测试。

为了解决这些问题，可以将 Lambda 表达式中的逻辑提取到独立的方法中。例如：

public static class TodoItemEndpoints
{
    public static void MapTodoItemEndpoints(this IEndpointRouteBuilder routes)
    {
        routes.MapGet("/todoitems", GetTodoItems);
    }

    private static async Task GetTodoItems(DbContext db)
    {
        var items = await db.TodoItems.ToListAsync();
        return TypedResults.Ok(items);
    }
}

通过这种方式，我们可以直接调用这些方法进行测试，而无需通过 API 调用来验证逻辑。

分组端点

为了进一步优化代码结构，可以对端点进行分组，避免重复定义。

例如，我们可以将所有与 TodoItems 相关的端点分组：

app.MapGroup("/todoitems")
    .RequireAuthorization()
    .WithTags("TodoItems")
    .MapGet("/", GetTodoItems)
    .MapPost("/", CreateTodoItem);

这种分组方式不仅减少了重复代码，还允许我们对整个组应用属性，例如授权、标签、CORS 或速率限制等。当然，如果需要，也可以对单个端点应用这些属性。

总结

通过以上方法，我们可以显著提升 ASP.NET Core Minimal APIs 的组织性和可维护性。使用扩展方法、TypedResults、功能分离以及端点分组，不仅让代码更清晰，还提高了测试和扩展的便利性。

Minimal APIs 是一个强大的工具，完全可以胜任“真实生产”环境中的应用开发。希望本文的内容能为您在实际项目中使用 Minimal APIs 提供一些有价值的参考。

原文链接: https://www.tessferrandez.com/blog/2023/10/31/organizing-minimal-apis.html