介绍
.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 都能优雅高效地处理这些任务。