.NET 8 中的 Mini WebApi

介绍

.NET 8 中的极简 API 隆重登场，重新定义了我们构建 Web 服务的方式。如果您想知道极简 API 的工作原理以及它们如何简化您的开发流程，让我们通过一些引人入胜的示例来深入了解一下。

.NET 极简主义的诞生

想想我们曾经不得不为一个简单的 Web 服务编写几页代码。很乏味，对吧？最小 API 就像一股清新的空气。它们在 .NET 6 中引入，并在 .NET 8 中得到改进，消除了传统 ASP.NET Core MVC 模型的复杂性。不再需要控制器，不需要广泛的配置 — 这正是您所需要的。

为什么要使用最少的 API？

1、效率：少写，多做。这是现代开发人员的口头禅。

2、性能：它们精简、高效、快速，非常适合高性能场景。

3、易于使用：.NET 新手？没问题！最少的 API 易于访问和掌握。

4、灵活性：简单并不意味着受限。从微服务到大型应用程序，它们都能满足您的需求。

入门

要开始这一旅程，请确保您已安装.NET 8 SDK。打开您最喜欢的代码编辑器，让我们创建我们的第一个最小 API。

重要设置信息：在运行本文提供的示例之前，请确保您已安装必要的 NuGet 包。对于涉及 OpenAPI 文档的功能，您将需要该Microsoft.AspNetCore.OpenApi包。您可以使用以下命令通过 NuGet 包管理器控制台安装它：

Install-Package Microsoft.AspNetCore.OpenApi

此包对于使用以下示例中显示的扩展方法至关重要WithOpenApi。

示例 1：你好，世界！

经典入门。此 API 返回友好问候语。运行此 API，瞧！您的 API 将在http://localhost:<port>/向全世界问好。请注意，端口号可能会根据您的设置而变化。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

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

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

app.Run();
Response body:
Hello, World!
Response headers:
content-type: text/plain; charset=utf-8
date: Tue,21 Nov 2023 13:38:37 GMT
server: Kestrel

设置舞台：图书服务

在进入路由之前，让我们先了解一下设置。我们定义了一个IBookService接口及其实现BookService，它模拟了一个图书数据库。这是将数据访问逻辑封装在服务层中的经典示例，它促进了关注点分离并使代码更易于维护。

背景介绍

“想象一下，走进一个井然有序的数字图书馆，只需点击一下鼠标即可找到每本书。这就是我们BookService在 Minimal API 设置中创建的内容。这项服务是我们应用程序的支柱，用于管理和提供图书数据。”

namespace MinimalApis
{
public interface IBookService
{
List<Book> GetBooks();

Book GetBook(int id);
}

public class BookService : IBookService
{
private readonly List<Book> _books;

public BookService()
{
_books = new List<Book>
{
new()
{
Id = 1,
Title = "Dependency Injection in .NET",
Author = "Mark Seemann"
},
new()
{
Id = 2,
Title = "C# in Depth",
Author = "Jon Skeet"
},
new()
{
Id = 3,
Title = "Programming Entity Framework",
Author = "Julia Lerman"
},
new()
{
Id = 4,
Title = "Programming WCF Services",
Author = "Juval Lowy and Michael Montgomery"
}
};
}

public List<Book> GetBooks()
{
return this._books;
}

public Book GetBook(int id)
{
var book = this._books.FirstOrDefault(x => x.Id == id);

return book;
}
}

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

public string Title { get; set; }

public string Author { get; set; }
}
}

这IBookService是我们的蓝图，声明了我们的服务必须提供哪些功能——列出所有书籍并通过 ID 获取特定的书籍。BookService是具体的实现，我们定义这些功能如何工作。

在里面BookService，我们有一个私有列表_books，用作我们的模拟数据库。它预先填充了一些要模拟的书籍。这种设置让我们可以专注于 API 功能，而不必担心实际的数据库连接。

该GetBooks方法返回所有书籍，同时GetBook使用 LINQ 通过其 ID 搜索书籍。这是一种处理数据的简单而强大的方法。

builder.Services.AddSingleton<IBookService, BookService>();

最后，我们BookService通过依赖注入系统注册，将我们的 API 集成到 Minimal API 管道中。这样，它就可以BookService在我们的应用程序中的任何地方使用。

示例 2：获取所有书籍

本示例演示如何列出图书馆中的所有书籍。

app.MapGet("/books", (IBookService bookService) =>
TypedResults.Ok(bookService.GetBooks()))
.WithName("GetBooks")
.WithOpenApi(x => new OpenApiOperation(x)
{
Summary = "Get Library Books",
Description = "Returns information about all the available books from the Amy's library.",
Tags = new List<OpenApiTag> { new() { Name = "Amy's Library" } }
});

端点定义：app.MapGet("/books", ...)此行在 URL 处定义一个 GET 端点/books。

依赖注入：(IBookService bookService)这里IBookService自动注入，允许访问图书服务。

服务交互：bookService.GetBooks()调用GetBooks的方法BookService来获取所有书籍。

响应：TypedResults.Ok(...)将书籍列表包装在 HTTP 200 OK 响应中。

Swagger文档：

.WithName("GetBooks")：为清楚起见，为端点分配一个名称。
.WithOpenApi(...)：添加 Swagger UI 的描述信息，增强 API 文档。

在 Postman 或浏览器中，发送 GET 请求以https://localhost:<port>/books接收所有书籍的 JSON 列表。

[
{
"id": 1,
"title": "Dependency Injection in .NET",
"author": "Mark Seemann"
},
{
"id": 2,
"title": "C# in Depth",
"author": "Jon Skeet"
},
{
"id": 3,
"title": "Programming Entity Framework",
"author": "Julia Lerman"
},
{
"id": 4,
"title": "Programming WCF Services",
"author": "Juval Lowy and Michael Montgomery"
}
]

示例 3：通过 ID 获取特定书籍
此示例显示如何通过 ID 检索特定书籍。

app.MapGet("/books/{id}", Results<Ok<Book>, NotFound> (IBookService bookService, int id) =>
bookService.GetBook(id) is { } book
? TypedResults.Ok(book)
: TypedResults.NotFound()
)
.WithName("GetBookById")
.WithOpenApi(x => new OpenApiOperation(x)
{
Summary = "Get Library Book By Id",
Description = "Returns information about selected book from the Amy's library.",
Tags = new List<OpenApiTag> { new() { Name = "Amy's Library" } }
});

端点定义：app.MapGet("/books/{id}", ...)在处定义一个 GET 端点/books/{id}，其中{id}是表示书籍 ID 的变量。

路线逻辑：bookService.GetBook(id) is { } book尝试通过 ID 查找书籍。如果找到，book则不为空。

条件响应：

如果找到：TypedResults.Ok(book)返回状态为 OK 的书籍。
如果未找到：TypedResults.NotFound()返回 404 未找到状态。
Swagger 文档：与示例 2 类似，为 Swagger UI 提供有意义的信息。

要查找 ID 为 3 的图书，请向发送 GET 请求https://localhost:<port>/books/3。您将获得 JSON 格式的图书详细信息，如果 ID 不存在，则收到 404 Not Found 响应。

{
"id": 3,
"title": "Programming Entity Framework",
"author": "Julia Lerman"
}

深入了解完整代码：完整的 Program.cs

在本节中，让我们探索一下该Program.cs文件。这是我们的 Minimal API 的所有部分汇集在一起的地方，从设置服务到定义端点。我将带您了解整个代码，将其分解为易于理解的部分，以便更清楚地理解。

完整代码清单

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.OpenApi.Models;
using MinimalApis;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddSingleton<IBookService, BookService>();

var app = builder.Build();

// configure exception middleware
app.UseStatusCodePages(async statusCodeContext
=> await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
.ExecuteAsync(statusCodeContext.HttpContext));

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

// example 2
app.MapGet("/books", (IBookService bookService) =>
TypedResults.Ok(bookService.GetBooks()))
.WithName("GetBooks")
.WithOpenApi(x => new OpenApiOperation(x)
{
Summary = "Get Library Books",
Description = "Returns information about all the available books from the Amy's library.",
Tags = new List<OpenApiTag> { new() { Name = "Amy's Library" } }
});

// example 3
app.MapGet("/books/{id}", Results<Ok<Book>, NotFound> (IBookService bookService, int id) =>
bookService.GetBook(id) is { } book
? TypedResults.Ok(book)
: TypedResults.NotFound()
)
.WithName("GetBookById")
.WithOpenApi(x => new OpenApiOperation(x)
{
Summary = "Get Library Book By Id",
Description = "Returns information about selected book from the Amy's library.",
Tags = new List<OpenApiTag> { new() { Name = "Amy's Library" } }
});

app.Run();

设置服务

在这里，我们启动应用程序并将其注入BookService到我们的服务集合中。这可BookService在整个应用程序中使用。此外，我们还为 API 文档设置了 Swagger。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IBookService, BookService>();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

配置中间件

本部分主要介绍中间件配置。UseStatusCodePages有助于处理 HTTP 状态代码，同时UseHttpsRedirection确保安全连接。在开发环境中启用 Swagger UI，以便于测试和探索。

var app = builder.Build();
app.UseStatusCodePages(...);
app.UseHttpsRedirection();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}

定义端点

这里，我们定义了三个端点：一个简单的问候语，一个列出所有书籍的端点，以及另一个通过 ID 获取特定书籍的端点。这些端点使用我们的BookService与书籍数据进行交互。

app.MapGet("/", () => "Hello, World!");
app.MapGet("/books", ...);
app.MapGet("/books/{id}", ...);

运行应用程序

最后，此行启动我们的应用程序，使其监听传入的请求。

app.Run();

该Program.cs文件就像管弦乐队的指挥，确保我们的 Minimal API 的每个部分都能和谐地演奏。它证明了 .NET 8 中 Minimal API 的强大功能 - 简单而强大，使我们能够轻松构建高效且有效的 Web 服务。

退出时

这些代码片段有效地演示了如何使用 .NET 中的 Minimal API 来创建干净、可维护且文档齐全的 Web 服务。通过利用依赖注入和清晰的路由，我们创建了一个易于理解和使用的 API。无论是列出所有书籍还是查找特定书籍，API 都能优雅高效地处理这些任务。