大家好,我是張飛洪,感謝您的閱讀,我會不定期和你分享學習心得,希望我的文章能成爲你成長路上的墊腳石,讓我們一起精進。
在本文中,我們將討論ASP.NET Core
中的新路由。我們將瞭解什麼是接口(endpoints
)路由,它是如何工作的,它在哪裏使用,以及如何創建自己的路由。
本文主題:
- 探索接口路由
- 創建自定義接口
- 創建更復雜的接口
名詞定義:端點,即我們訪問的接口或者叫API,有些地方叫EndPoint或者叫接口,其實源頭的稱呼應該叫端點會更貼切一些。或者你也可以直接叫EndPoint,但是先不管那麼多,大概瞭解這個意思就可以了。
探索接口路由
要了解接口路由(End Point),您需要了解什麼是端點以及什麼是路由。
端點是應用程序的一部分,當路由將傳入的請求映射到它時,端點就會被執行。
客戶端通常從服務器請求資源。大多數情況下,客戶端是一個瀏覽器。資源由指向特定目標的URL定義。除了網頁,它也可以是一個移動應用程序,從Web API請求特定JSON數據。
另一方面,執行的端點被映射到一個特定的路由,ASP.NET Core開發人員已經熟悉這樣一種路由模式:
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints => {
endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
});
如果路由或路由模式與傳入請求的URL匹配,則請求將映射到該端點。
ASP.NET Core
可以映射到以下端點:
- Controllers (例如, MVC or web APIs)
- Razor Pages
- SignalR (and Blazor Server)
- gRPC services
- Health checks
大多數端點都有非常簡單的路由模式。只有MVC和Web API端點使用更復雜的模式。Razor頁面的路由定義基於實際頁面的文件夾和文件結構。
在ASP.NET Core 2.2中引入端點之前,路由只是運用在MVC和Web API中。Razor Pages中的隱式路由是內置的,SignalR沒有路由一說。Blazor和gRPC在當時還不不知道在哪兒,健康檢查最初是作爲中間件組件實現的。
引入端點路由是爲了將路由與實際端點分離,說得白話一點,就是讓URL地址和實際執行的Action進行分離,這會讓框架更加靈活,同時這意味着新的端點不需要實現自己的路由。
創建自定義接口
創建端點的最簡單方法是使用lambda:
app.Map("/map", async context => {
await context.Response.WriteAsync("OK");
});
這裏將/map路由映射到一個簡單的端點,該端點將單詞“OK”寫入響應流。
關於早期
.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)映射到端點。以下代碼顯示瞭如何映射GET和POST方法:
app.MapGet("/mapget", async context => {
await context.Response.WriteAsync("Map GET");
});
app.MapPost("/mappost", async context => {
await context.Response.WriteAsync("Map POST");
});
我們還可以將兩個或多個HTTP方法映射到一個端點:
app.MapMethods("/mapmethods", new[] { "DELETE", "PUT" },
async context => {
await context.Response.WriteAsync("Map Methods");
});
這些端點映射很像我們在第8篇定製.NET 6.0的Middleware中間件中看到的基於lambda的中間件組件,這些管道中間件會返回結果,例如基於HTML的視圖、JSON結構化數據或類似的內容。但是,端點路由是一種更靈活的輸出方式,它應該會在ASP.NET Core 3.0以後的所有版本中進行使用。
在第8篇中,我們看到我們可以像這樣的分支管道:
app.Map("/map", mapped => { // …… });
以上這種方式也會創建一個路由,但只會偵聽以/map
開頭的URL。如果您希望有一個處理/map/{id:int?}
等模式的路由引擎,來匹配/map/456
而不是/map/abc
,那麼您應該使用前面所述的新的路由。
而那些基於lambda的端點映射,對於簡單的場景非常有用。然而,由於它們是在Program.cs
中定義的,如果您想使用這種方式來實現更復雜的場景,代碼維護性將變得很差。
因此,我們應該嘗試找到一種更結構化的方法來創建自定義端點。
創建更復雜的接口
接下來,我們將創建一個健康檢查接口例子,有點類似於您在Kubernetes集羣中運行應用程序時可能需要的接口,用來檢測系統的健康狀態:
我們從開發者的角度定義API接口,我們首先添加一個MapMyHealthChecks方法,作爲IEndpointRouteBuilder對象上的一個擴展方法,它沒有實現:
app.MapMyHealthChecks("/myhealth");
app.MapControllerRoute(name: "default",pattern:"{controller=Home}/{action=Index}/{id?}");
爲了避免混淆,我們這兒採取和之前類似的方式添加新接口,後面我們進一步來實現一下。
我們創建一個名爲MapMyHealthChecksExtensions
的靜態類,並在MapMyHealthCheck
中放置一個擴展方法,該對象擴展IEndpointRouteBuilder
接口並返回IEndpointConventionBuilder
對象:
namespace RoutingSample;
public static class MapMyHealthChecksExtensions {
public static IEndpointConventionBuilder MapMyHealthChecks (this IEndpointRouteBuilder endpoints, string pattern = "/myhealth")
{
// ...
}
}
以上只是骨架,實際的接口將被實現爲一個終止的中間件,也就是說,它不調用下一個的中間件組件,並創建響應流的輸出:
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");
}
}
實際工作是在Invoke
方法中完成的。目前,只演示200狀態碼和OK狀態響應,我們可以在這裏隨意擴展該方法,例如檢查數據庫或相關服務的可用性。
接下來我們使用這個終止中間件,我們回到MapMyHealthChecks
方法的框架。我們現在創建一個自己的管道,並將其映射到給定的pipeline:
var pipeline = endpoints.CreateApplicationBuilder().UseMiddleware().Build();
return endpoints.Map(pattern, pipeline).WithDisplayName("My custom health checks");
這種方法允許我們爲這個新的管道添加更多的中間件。WithDisplayName
擴展方法將配置的顯示名稱設置爲接口,接下來按F5鍵啓動程序,並在瀏覽器中調用https://localhost:7111/myhealth。我們將看到:
請注意,端口號可能會有所不同。我們還可以將已經存在的終止中間件組件轉換爲路由接口,以配置更加靈活的路由。
總結
ASP.NET Core
支持請求處理並向請求提供信息的多種方法。接口路由是一種基於URL和請求的方法提供資源。
在本文,我們學習瞭如何使用終止中間件組件作爲接口,並用將該接口映射到新的路由引擎,從而讓我們的路由變得更加強大和靈活。
每個Web應用程序都需要了解系統用戶,以允許或限制對特定數據的訪問。在下一章中,我們將展示如何配置身份驗證和識別用戶。