.NET 6.0 中自定義接口路由

在本文中，我們將討論ASP.NET Core中的新路由。我們將了解什么是接口(endpoints)路由，它是如何工作的，它在哪里使用，以及如何創(chuàng)建自己的路由。

本文主題：

探索接口路由

創(chuàng)建自定義接口

創(chuàng)建更復(fù)雜的接口

名詞定義：端點(diǎn)，即我們?cè)L問的接口或者叫API，有些地方叫EndPoint或者叫接口，其實(shí)源頭的稱呼應(yīng)該叫端點(diǎn)會(huì)更貼切一些。或者你也可以直接叫EndPoint，但是先不管那么多，大概了解這個(gè)意思就可以了。

探索接口路由

要了解接口路由（End Point），您需要了解什么是端點(diǎn)以及什么是路由。

端點(diǎn)是應(yīng)用程序的一部分，當(dāng)路由將傳入的請(qǐng)求映射到它時(shí)，端點(diǎn)就會(huì)被執(zhí)行。

客戶端通常從服務(wù)器請(qǐng)求資源。大多數(shù)情況下，客戶端是一個(gè)瀏覽器。資源由指向特定目標(biāo)的URL定義。除了網(wǎng)頁，它也可以是一個(gè)移動(dòng)應(yīng)用程序，從Web API請(qǐng)求特定JSON數(shù)據(jù)。

另一方面，執(zhí)行的端點(diǎn)被映射到一個(gè)特定的路由，ASP.NET Core開發(fā)人員已經(jīng)熟悉這樣一種路由模式：

app.UseRouting(); 
app.UseAuthorization(); 
app.UseEndpoints(endpoints => {    
   endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); 
});

如果路由或路由模式與傳入請(qǐng)求的URL匹配，則請(qǐng)求將映射到該端點(diǎn)。ASP.NET Core可以映射到以下端點(diǎn)：

• Controllers (例如, MVC or web APIs)

• Razor Pages

• SignalR (and Blazor Server)

• gRPC services

• Health checks

大多數(shù)端點(diǎn)都有非常簡(jiǎn)單的路由模式。只有MVC和Web API端點(diǎn)使用更復(fù)雜的模式。Razor頁面的路由定義基于實(shí)際頁面的文件夾和文件結(jié)構(gòu)。

在ASP.NET Core 2.2中引入端點(diǎn)之前，路由只是運(yùn)用在MVC和Web API中。Razor Pages中的隱式路由是內(nèi)置的，SignalR沒有路由一說。Blazor和gRPC在當(dāng)時(shí)還不不知道在哪兒，健康檢查最初是作為中間件組件實(shí)現(xiàn)的。

引入端點(diǎn)路由是為了將路由與實(shí)際端點(diǎn)分離，說得白話一點(diǎn)，就是讓URL地址和實(shí)際執(zhí)行的Action進(jìn)行分離，這會(huì)讓框架更加靈活，同時(shí)這意味著新的端點(diǎn)不需要實(shí)現(xiàn)自己的路由。

創(chuàng)建自定義接口

創(chuàng)建端點(diǎn)的最簡(jiǎn)單方法是使用lambda：

app.Map("/map", async context => {  
    await context.Response.WriteAsync("OK"); 
});

這里將/map路由映射到一個(gè)簡(jiǎn)單的端點(diǎn)，該端點(diǎn)將單詞“OK”寫入響應(yīng)流。

關(guān)于早期.NET 6.0版本的說明 在.NET 6.0之前，該映射只能在Startup.cs文件中的UseEndpoints方法中，而使用.NET 6.0和新的Minimal API方法，可以在Program.cs文件中完成映射。

另外，我們需要將Microsoft.AspNetCore.Http命名空間添加到using語句中。還可以將特定的HTTP方法（如GET、POST、PUT和DELETE）映射到端點(diǎn)。以下代碼顯示了如何映射GET和POST方法：

app.MapGet("/mapget", async context => {     
    await context.Response.WriteAsync("Map GET"); 
}); 
app.MapPost("/mappost", async context => {  
        await context.Response.WriteAsync("Map POST");
});

我們還可以將兩個(gè)或多個(gè)HTTP方法映射到一個(gè)端點(diǎn)：

app.MapMethods("/mapmethods",  new[] { "DELETE", "PUT" }, 
    async context => {
        await context.Response.WriteAsync("Map Methods");
});

這些端點(diǎn)映射很像我們?cè)诘?篇《定制.NET 6.0的Middleware中間件》中看到的基于lambda的中間件組件，這些管道中間件會(huì)返回結(jié)果，例如基于HTML的視圖、JSON結(jié)構(gòu)化數(shù)據(jù)或類似的內(nèi)容。但是，端點(diǎn)路由是一種更靈活的輸出方式，它應(yīng)該會(huì)在ASP.NET Core 3.0以后的所有版本中進(jìn)行使用。

在第8篇中，我們看到我們可以像這樣的分支管道：

app.Map("/map", mapped => {     // ……  });

以上這種方式也會(huì)創(chuàng)建一個(gè)路由，但只會(huì)偵聽以/map開頭的URL。如果您希望有一個(gè)處理/map/｛id:int？｝等模式的路由引擎，來匹配/map/456而不是/map/abc，那么您應(yīng)該使用前面所述的新的路由。

而那些基于lambda的端點(diǎn)映射，對(duì)于簡(jiǎn)單的場(chǎng)景非常有用。然而，由于它們是在Program.cs中定義的，如果你想使用這種方式來實(shí)現(xiàn)更復(fù)雜的場(chǎng)景，代碼維護(hù)性將變得很差。

因此，我們應(yīng)該嘗試找到一種更結(jié)構(gòu)化的方法來創(chuàng)建自定義端點(diǎn)。

創(chuàng)建更復(fù)雜的接口

接下來，我們將創(chuàng)建一個(gè)健康檢查接口例子，有點(diǎn)類似于您在Kubernetes集群中運(yùn)行應(yīng)用程序時(shí)可能需要的接口，用來檢測(cè)系統(tǒng)的健康狀態(tài)：我們從開發(fā)者的角度定義API接口，我們首先添加一個(gè)MapMyHealthChecks方法，作為IEndpointRouteBuilder對(duì)象上的一個(gè)擴(kuò)展方法，它沒有實(shí)現(xiàn)：

app.MapMyHealthChecks("/myhealth");   
app.MapControllerRoute(name: "default",pattern:"{controller=Home}/{action=Index}/{id?}");

為了避免混淆，我們這兒采取和之前類似的方式添加新接口，后面我們進(jìn)一步來實(shí)現(xiàn)一下。我們創(chuàng)建一個(gè)名為MapMyHealthChecksExtensions的靜態(tài)類，并在MapMyHealthCheck中放置一個(gè)擴(kuò)展方法，該對(duì)象擴(kuò)展IEndpointRouteBuilder接口并返回IEndpointConventionBuilder對(duì)象：

namespace RoutingSample; 
public static class MapMyHealthChecksExtensions {     
    public static IEndpointConventionBuilder  MapMyHealthChecks (this IEndpointRouteBuilder endpoints, string pattern = "/myhealth")     
    {         
        // ...     
    } 
}

以上只是骨架，實(shí)際的接口將被實(shí)現(xiàn)為一個(gè)終止的中間件，也就是說，它不調(diào)用下一個(gè)的中間件組件，并創(chuàng)建響應(yīng)流的輸出：

namespace RoutingSample; 
public class MyHealthChecksMiddleware {     
    private readonly ILogger _logger;     
    public MyHealthChecksMiddleware (RequestDelegate next, ILogger logger)    
     {  
        _logger = logger;     
    }     

    public async Task Invoke(HttpContext context)     {         
        // add some checks here...         
        context.Response.StatusCode = 200;         
        context.Response.ContentType = "text/plain";         
        await context.Response.WriteAsync("OK");     
    } 
}

實(shí)際工作是在Invoke方法中完成的。目前，只演示200狀態(tài)碼和OK狀態(tài)響應(yīng)，我們可以在這里隨意擴(kuò)展該方法，例如檢查數(shù)據(jù)庫(kù)或相關(guān)服務(wù)的可用性。

接下來我們使用這個(gè)終止中間件，我們回到MapMyHealthChecks方法的框架。我們現(xiàn)在創(chuàng)建一個(gè)自己的管道，并將其映射到給定的pipeline：

var pipeline = endpoints.CreateApplicationBuilder().UseMiddleware().Build(); 
return endpoints.Map(pattern, pipeline).WithDisplayName("My custom health checks");

這種方法允許我們?yōu)檫@個(gè)新的管道添加更多的中間件。WithDisplayName擴(kuò)展方法將配置的顯示名稱設(shè)置為接口，接下來按F5鍵啟動(dòng)程序，并在瀏覽器中調(diào)用https://localhost:7111/myhealth。

我們將看到：

請(qǐng)注意，端口號(hào)可能會(huì)有所不同。我們還可以將已經(jīng)存在的終止中間件組件轉(zhuǎn)換為路由接口，以配置更加靈活的路由。

總結(jié)

ASP.NET Core支持請(qǐng)求處理并向請(qǐng)求提供信息的多種方法。接口路由是一種基于URL和請(qǐng)求的方法提供資源。

在本文，我們學(xué)習(xí)了如何使用終止中間件組件作為接口，并用將該接口映射到新的路由引擎，從而讓我們的路由變得更加強(qiáng)大和靈活。每個(gè)Web應(yīng)用程序都需要了解系統(tǒng)用戶，以允許或限制對(duì)特定數(shù)據(jù)的訪問。在下一章中，我們將展示如何配置身份驗(yàn)證和識(shí)別用戶。