ASP.NET Core 最小 API：极简开发，高效构建（上）

一、概述

构建最小 API，以创建具有最小依赖项的 HTTP API。它们非常适合于需要在 ASP.NET Core 中仅包括最少文件、功能和依赖项的微服务和应用。本文介绍使用 ASP.NET Core 生成最小 API 的基础知识，将创建以下 API：

API（应用程序接口）	描述	请求正文	响应正文
GET /todoitems	获取所有待办事项	无	待办事项的数组
GET /todoitems/complete	获取已完成的待办事项	无	待办事项的数组
GET /todoitems/{id}	按 ID 获取项	无	待办事项
POST /todoitems	添加新项	待办事项	待办事项
PUT /todoitems/{id}	更新现有项	待办事项	无
DELETE /todoitems/{id}	删除项	无	无

二、开发环境

Deepin 20.9、.Net Core 8、VS Code

开发环境搭建参考：.NET SDK 各操作系统开发环境搭建

三、创建 TodoApi 项目

创建一个空模板项目，

在这里插入图片描述

Program.cs 文件包含以下代码：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();app.MapGet("/", () => "Hello World!");app.Run();

前面的代码：

创建具有预配置默认值的 WebApplicationBuilder 和 WebApplication。
创建返回 / 的 HTTP GET 终结点 Hello World!

在这里插入图片描述

运行项目后，浏览器访问 http://localhost:5026 ，Hello World! 将显示在浏览器中。Program.cs 文件包含了一个最小但完整的应用。

在这里插入图片描述

四、添加 NuGet 包

需要添加 ORM 框架 EF CORE，搜索 Microsoft.EntityFrameworkCore.InMemory，然后安装，

在这里插入图片描述

安装完成，

在这里插入图片描述

除此之外，还需要安装 Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore 用于捕获异常，注意版本要适配 SDK，不然会报错rror CS1061: “IServiceCollection”未包含“AddDatabaseDeveloperPageExceptionFilter”的定义，并且找不到可接受第一个“IServiceCollection”类型参数的可访问扩展方法“AddDatabaseDeveloperPageExceptionFilter”(是否缺少 using 指令或程序集引用?)

在这里插入图片描述

五、模型和数据库上下文类

在项目文件夹中，创建名为 Todo.cs 的文件为此应用创建模型，包含以下代码：

namespace TodoApi;public class Todo
{public int Id { get; set; }public string? Name { get; set; }public bool IsComplete { get; set; }
}

该模型是一个表示应用管理的数据的类。

接着创建名为 TodoDb.cs 的文件定义数据库上下文，它是为数据模型协调实体框架功能的主类，此类从 Microsoft.EntityFrameworkCore.DbContext 类派生，包含以下代码：

namespace TodoApi;using Microsoft.EntityFrameworkCore;class TodoDb : DbContext
{public TodoDb(DbContextOptions<TodoDb> options): base(options) { }public DbSet<Todo> Todos => Set<Todo>();
}

六、添加 API 代码

将 Program.cs 文件的内容替换为以下代码：

using Microsoft.EntityFrameworkCore;using TodoApi;var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
var app = builder.Build();app.MapGet("/todoitems", async (TodoDb db) =>await db.Todos.ToListAsync());app.MapGet("/todoitems/complete", async (TodoDb db) =>await db.Todos.Where(t => t.IsComplete).ToListAsync());app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>await db.Todos.FindAsync(id)is Todo todo? Results.Ok(todo): Results.NotFound());app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{db.Todos.Add(todo);await db.SaveChangesAsync();return Results.Created($"/todoitems/{todo.Id}", todo);
});app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{var todo = await db.Todos.FindAsync(id);if (todo is null) return Results.NotFound();todo.Name = inputTodo.Name;todo.IsComplete = inputTodo.IsComplete;await db.SaveChangesAsync();return Results.NoContent();
});app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{if (await db.Todos.FindAsync(id) is Todo todo){db.Todos.Remove(todo);await db.SaveChangesAsync();return Results.NoContent();}return Results.NotFound();
});app.Run();

其中，以下这个代码段将数据库上下文添加到依赖关系注入 (DI) 容器，并且允许显示与数据库相关的异常：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();
var app = builder.Build();

DI 容器提供对数据库上下文和其他服务的访问权限。

七、使用 Swagger 创建 API 测试 UI

.NET 包 NSwag.AspNetCore 集成了 Swagger 工具，可用于生成遵循 OpenAPI 规范的测试 UI：

NSwag：将 Swagger 直接集成到 ASP.NET Core 应用程序中的 .NET 库，提供了中间件和配置。
Swagger：一组开放源代码工具（如 OpenAPIGenerator 和 SwaggerUI），用于生成遵循 OpenAPI 规范的 API 测试页。
OpenAPI 规范：基于控制器和模型中的 XML 和属性注释，描述 API 功能的文档。

在这里插入图片描述

安装 Swagger 工具之后，配置 Swagger 中间件：

using Microsoft.EntityFrameworkCore;
using NSwag.AspNetCore;
using TodoApi;var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<TodoDb>(opt => opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(config =>
{config.DocumentName = "TodoAPI";config.Title = "TodoAPI v1";config.Version = "v1";
});
var app = builder.Build();

在前面的代码中：

builder.Services.AddEndpointsApiExplorer();：启用 API 资源管理器，该服务提供有关 HTTP API 的元数据。该 API 资源管理器由 Swagger 用于生成 Swagger 文档。
builder.Services.AddOpenApiDocument(config => {...});：将 Swagger OpenAPI 文档生成器添加到应用程序服务，并配置它以提供有关 API 的详细信息，例如其标题和版本。

在 app 行中定义 var app = builder.Build(); 后，添加代码：

var app = builder.Build();
if (app.Environment.IsDevelopment())
{app.UseOpenApi();app.UseSwaggerUi(config =>{config.DocumentTitle = "TodoAPI";config.Path = "/swagger";config.DocumentPath = "/swagger/{documentName}/swagger.json";config.DocExpansion = "list";});
}

通过前面的代码，Swagger 中间件可以为生成的 JSON 文档和 Swagger UI 提供服务。 Swagger 仅在开发环境中启用。在生产环境中启用 Swagger 可能会公开有关 API 结构和实现的潜在敏感详细信息。

八、测试发布数据

Program.cs 中的以下代码创建 HTTP POST 终结点 /todoitems 以将数据添加到内存中数据库：

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{db.Todos.Add(todo);await db.SaveChangesAsync();return Results.Created($"/todoitems/{todo.Id}", todo);
});