本章将介绍如何使用 ASP.NET Core Minimal APIs 构建 Web 服务（即 HTTP 或表现层状态转移（REST）服务）。然后，您将学习如何使用 HTTP 客户端消费 Web 服务，这可以是任何其他类型的 .NET 应用程序，包括网站或移动或桌面应用程序。我们将创建一个 Blazor WebAssembly 客户端。

本章需要您在第 10 章《使用 Entity Framework Core 处理数据》和第 12 至 14 章关于使用 ASP.NET Core 和 Blazor 构建网站中获得的知识和技能。

在本章中，我们将涵盖以下主题：

• 使用 ASP.NET Core 构建 Web 服务
• 为 Northwind 数据库创建一个 Web 服务
• 记录和尝试网络服务
• 使用 HTTP 客户端消费 Web 服务

使用 ASP.NET Core 构建 Web 服务

在我们构建现代网络服务之前，我们需要介绍一些背景，以为本章设定上下文。

理解网络服务缩略语

尽管 HTTP 最初是为了请求和响应 HTML 及其他供人类查看的资源而设计的，但它也适合构建服务。

罗伊·菲尔丁在他的博士论文中描述了 REST 架构风格，他指出 HTTP 标准适合构建服务，因为它定义了以下内容：

• URIs to uniquely identify resources, like https://localhost:5151/products/23.
• 在这些资源上执行常见任务的方法，如 GET 、 POST 、 PUT 和 DELETE 。
• 在请求和响应中协商交换内容的媒体类型的能力，例如 XML 和 JSON。当客户端指定请求头如 Accept: application/xml,*/*;q=0.8 时，会发生内容协商。ASP.NET Core Web 服务使用的默认响应格式是 JSON，这意味着响应头之一将是 Content-Type: application/json; charset=utf-8 。

网络服务使用 HTTP 通信标准，因此有时被称为 HTTP 服务或 RESTful 服务。

理解 HTTP 请求和响应

HTTP 定义了标准请求类型和标准代码以指示响应类型。它们中的大多数可以用于实现 Web 服务。

最常见的请求类型是 GET ，用于检索由唯一路径标识的资源，附加选项包括可接受的媒体类型，以设置为请求头，例如 Accept ，如下例所示：

GET /path/to/resource
Accept: application/json

常见的响应包括成功和多种类型的失败，如表 15.1 所示：

HTTP/1.1 103 Early Hints
Link: </style.css>; rel=preload; as=style
Link: </script.js>; rel=preload; as=script

表 15.1：GET 方法的常见 HTTP 状态码响应

其他常见的 HTTP 请求类型包括 POST 、 PUT 、 PATCH 或 DELETE ，用于创建、修改或删除资源。

要创建一个新资源，您可以发出一个 POST 请求，正文包含新资源，如以下代码所示：

POST /path/to/resource
Content-Length: 123
Content-Type: application/json

要创建一个新资源或更新现有资源，您可能会发出一个 PUT 请求，主体包含现有资源的全新版本，如果资源不存在，则会创建它；如果资源存在，则会替换它（有时称为插入或更新操作），如下代码所示：

PUT /path/to/resource
Content-Length: 123
Content-Type: application/json

为了更高效地更新现有资源，您可以发出一个 PATCH 请求，主体包含一个仅包含需要更改的属性的对象，如以下代码所示：

PATCH /path/to/resource
Content-Length: 123
Content-Type: application/json

要删除现有资源，您可以发出一个 DELETE 请求，如以下代码所示：

DELETE /path/to/resource

除了上表中显示的针对 GET 请求的响应外，所有创建、修改或删除资源的请求类型还有其他可能的通用响应，如表 15.2 所示：

表 15.2：对其他方法如 POST 和 PUT 的常见 HTTP 状态代码响应

ASP.NET Core 最小化 API 项目

我们将构建一个网络服务，提供一种使用 ASP.NET Core 与 Northwind 数据库中的数据进行交互的方法，以便任何能够发出 HTTP 请求并接收 HTTP 响应的客户端应用程序都可以使用这些数据。

传统上，您使用 ASP.NET Core Web API / dotnet new webapi 项目模板。这允许创建一个使用控制器或较新的最小 API 实现的 Web 服务。

警告！在 .NET 6 和 .NET 7 中， dotnet new webapi 命令创建一个使用控制器实现的服务。在 .NET 6 和 .NET 7 中，要使用最小 API 实现服务，您需要在命令中添加 --use-minimal-apis 开关。使用 .NET 8 或更高版本， dotnet new webapi 命令创建一个使用最小 API 实现的服务。要使用控制器实现服务，您需要添加 --use-controllers 开关。

最小化 API 网络服务和原生 AOT 编译

.NET 8 引入了 ASP.NET Core Web API（原生 AOT）/ dotnet new webapiaot 项目模板，该模板仅使用最小化 API 并支持原生 AOT 发布。随着时间的推移，.NET 的更多组件将支持 AOT，正如您在以下引用中所读到的：

“我们预计在 .NET 9 时间框架内对 MVC 和 Blazor 的原生 AOT 支持进行调查会有所进展，但考虑到涉及的大量工作，我们不期望为 .NET 9 提供生产就绪的原生 AOT 支持。” – Dan Roth

良好实践：最小化 API 特别适合垂直切片架构（VSA）。最小化 API 相对于基于控制器的 Web API 的一个主要好处是，每个最小化 API 端点只需要实例化它所需的依赖注入（DI）服务。使用控制器时，要执行该控制器中的任何操作方法，所有在任何操作方法中使用的 DI 服务必须在每次调用时实例化。这是浪费时间和资源！

创建一个 ASP.NET Core 最小化 API 项目

我们走吧：

1. 使用您首选的代码编辑器打开 ModernWeb 解决方案，然后添加一个新项目，如下列表所定义：项目模板：ASP.NET Core Web API / webapi解决方案文件和文件夹： ModernWeb项目文件和文件夹： Northwind.WebApi
2. 如果您正在使用 Visual Studio，请确认已选择以下默认设置：认证类型：无配置为 HTTPS：已选择启用容器支持：已清除启用 OpenAPI 支持：已选择请勿使用顶级语句：已清除 使用控制器：已清除

确保清除“使用控制器”复选框，否则您的代码将与本书中看到的非常不同！
如果您正在使用 VS Code 或 Rider，请在 ModernWeb 目录下的命令提示符或终端中输入以下内容：

dotnet new webapi -o Northwind.WebApi

1. 构建 Northwind.WebApi 项目。
2. 在项目文件中，删除实现 OpenAPI Web 服务文档的包的版本号，因为我们正在使用 CPM，如下所示的标记：

<PackageReference Include="Microsoft.AspNetCore.OpenApi" />

在 Program.cs 中，查看代码，如下所示：

var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
  app.MapOpenApi();
}
app.UseHttpsRedirection();
var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
{
  var forecast = Enumerable.Range(1, 5).Select(index =>
    new WeatherForecast
    (
      DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
      Random.Shared.Next(-20, 55),
      summaries[Random.Shared.Next(summaries.Length)]
    ))
    .ToArray();
  return forecast;
})
.WithName("GetWeatherForecast");
app.Run();
internal record WeatherForecast(DateOnly Date,
  int TemperatureC, string? Summary)
{
  public int TemperatureF => 32 +
    (int)(TemperatureC / 0.5556);
}

在审查前面的代码时，请注意以下几点：

• 该程序的配置与其他任何 ASP.NET Core 项目类似，首先调用 WebApplication.CreateBuilder 。
• 服务集合中添加了一个 OpenAPI 服务。这个服务用于记录 Web 服务。在 .NET 8 及之前版本中，使用了第三方的 Swashbuckle 包来实现这一点，但在 .NET 9 及之后版本中，微软编写了自己的实现。您可以在以下链接中阅读更多信息：https://github.com/dotnet/aspnetcore/issues/54599。默认情况下，OpenAPI 文档生成会创建一个符合 OpenAPI 规范 v3.0 的文档：https://spec.openapis.org/oas/v3.0.0。
• 在开发过程中，OpenAPI 文档被映射为端点，以便其他开发人员可以轻松地使用它来创建客户端。默认情况下，通过调用 MapOpenApi 注册的 OpenAPI 端点在 /openapi/{documentName}.json 端点处公开文档。默认情况下， documentName 是 v1 。在生产环境中，这些端点不再被映射，因为它们不再必要。
• MapGet 调用注册了相对路径 /weatherforecast 以响应 HTTP GET 请求，其实现使用共享 Random 对象返回一个包含随机温度和摘要的 WeatherForecast 对象数组，例如 Bracing 或 Balmy ，用于接下来五天的天气。

现在让我们允许 HTTP 请求指定预测应该提前多少天。同时，我们将通过将天气端点实现放在自己的代码文件中来实施良好的实践：

1. 添加一个名为 Program.Weather.cs 的新类文件。
2. 在 Program.Weather.cs 中，添加语句以扩展自动生成的 partial Program 类，通过移动（剪切并粘贴语句）来自 Program.cs 的天气相关语句，并进行小的调整，例如定义一个 GetWeather 方法，带有一个 days 参数，以控制生成多少个天气预报，如以下代码所示：

public partial class Program
{
  static string[] summaries = { "Freezing", "Bracing",
    "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot",
    "Sweltering", "Scorching" };
  internal static WeatherForecast[]? GetWeather(int days)
  {
    WeatherForecast[]? forecast = Enumerable.Range(1, days)
      .Select(index => new WeatherForecast
      (
        DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
        Random.Shared.Next(-20, 55),
        summaries[Random.Shared.Next(summaries.Length)]
      ))
      .ToArray();
    return forecast;
  }
  internal record WeatherForecast(DateOnly Date,
    int TemperatureC, string? Summary)
  {
    public int TemperatureF => 32 +
      (int)(TemperatureC / 0.5556);
  }
}

在 Program.cs 中，修改 MapGet 调用，如以下代码中突出显示的内容所示：

app.UseHttpsRedirection();
app.MapGet("/weatherforecast/{days:int?}",
  (int days = 5) => GetWeather(days))
  .WithName("GetWeatherForecast");
app.Run();

在 MapGet 调用中，请注意路由模板模式 {days:int?} 限制了 days 参数为 int 值。 ? 使 days 参数可选，如果缺失将默认为 5 。

审查网络服务的功能

现在，我们将测试网络服务的功能：

1. 在 Properties 文件夹中，在 launchSettings.json ，请注意，如果您使用的是 Visual Studio，默认情况下， https 配置文件将启动浏览器并导航到 /weatherforecast 相对 URL 路径，如以下标记中突出显示的内容所示：

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "launchUrl": "weatherforecast",

对于 https 配置文件，对于其 applicationUrl ，将 HTTPS 的随机端口号更改为 5151 ，将 HTTP 的随机端口号更改为 5150 ，如以下标记中突出显示所示：

"applicationUrl": "https://localhost:5151;http://localhost:5150",

1. 保存对所有已修改文件的更改。
2. 使用 https 启动配置启动 Northwind.WebApi 网络服务项目。
3. 在 Windows 上，如果您看到一个 Windows 安全警报对话框，提示 Windows Defender 防火墙已阻止此应用程序的一些功能，请点击允许访问按钮。
4. 启动 Chrome，导航到 https://localhost:5151/ ，请注意您将收到 404 状态代码响应，因为我们尚未启用静态文件，并且没有 index.xhtml 。请记住，该项目并不是为了让人类查看和交互，因此这是网络服务的预期行为。
5. 在 Chrome 中，显示开发者工具。
6. 导航到 https://localhost:5151/weatherforecast ，并注意网络服务应返回一个包含五个随机天气预报对象的 JSON 文档，格式为数组，如图 15.1 所示：

1. 关闭开发者工具。
2. 导航到 https://localhost:5151/weatherforecast/14 ，并注意请求两周天气预报时的响应包含 14 个预报。
3. 选择“美化打印”复选框，如图 15.1 所示，并注意最近版本的 Chrome 现在可以更好地格式化 JSON 响应，以便人类阅读。
4. 关闭 Chrome 并关闭网络服务器。

路线约束

要注册 /weatherforecast 路由端点，我们使用了路由约束来限制 days 参数的可接受值为整数，如以下代码中所示的高亮部分：

app.MapGet("/weatherforecast/{days:int?}", ...

路线约束允许我们根据数据类型和其他验证来控制匹配。它们在表 15.3 中总结：

表 15.3：带有示例和描述的路线约束

使用冒号分隔多个约束，如下例所示：

app.MapGet("/weatherforecast/{days:int:min(5)}", ...

对于正则表达式， RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant 会自动添加。正则表达式标记必须转义（将 \ 替换为 \\ ，将 { 替换为 {{ ，将 } 替换为 }} ）或使用逐字字符串字面量。

更多信息：您可以通过定义一个实现 IRouteConstraint 的类来创建自定义路由约束。这超出了本书的范围，但您可以在以下链接中阅读相关内容：https://learn.microsoft.com/en-us/aspnet/core/fundamentals/routing#custom-route-constraints。

短路路径

当路由将请求匹配到一个端点时，它会让其余的中间件管道运行，然后再调用端点逻辑。这需要时间，因此在 ASP.NET Core 8 及更高版本中，您可以立即调用端点并返回响应。

您可以通过在映射的端点路由上调用 ShortCircuit 方法来实现此操作，如以下代码所示：

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

或者，您可以调用 MapShortCircuit 方法来响应 404 Missing Resource 或其他状态代码，对于不需要进一步处理的资源，如以下代码所示：

app.MapShortCircuit(404, "robots.txt", "favicon.ico");