.NET 8 IEndpointRouteBuilder詳解

2023-11-08 21:01:15

Map

​ 經過對 WebApplication 的初步剖析,我們已經大致對Web應用的骨架有了一定了解,現在我們來看一下Hello World案例中僅剩的一條程式碼:

app.MapGet("/", () => "Hello World!"); // 3 新增路由處理

​ 老規矩,看簽名:

public static RouteHandlerBuilder MapGet(this IEndpointRouteBuilder endpoints,
      [StringSyntax("Route")] string pattern,Delegate handler){
    return endpoints.MapMethods(pattern, (IEnumerable<string>) EndpointRouteBuilderExtensions.GetVerb, handler);
}

​ 我們已經解釋過 IEndpointRouteBuilder 的定義了,即為程式定義路由構建的約定。這次看到的是他的拓展方法 Map ,該方法是諸如 MapGetMapPostMapPutMapDeleteMapPatchMapMethods 的底層方法:

​ 他的實現就是為了給IEndpointRouteBuilderDataSources 新增一個 RouteEndpointDataSource

private static RouteHandlerBuilder Map(this IEndpointRouteBuilder endpoints, RoutePattern pattern, Delegate handler, IEnumerable<string> httpMethods, bool isFallback)
{
	return endpoints.GetOrAddRouteEndpointDataSource().AddRouteHandler(pattern, handler, httpMethods, isFallback, RequestDelegateFactory.InferMetadata, RequestDelegateFactory.Create);
}

RouteEndpointDataSource 繼承自 EndpointDataSource,提供一組RouteEndpoint

public override IReadOnlyList<RouteEndpoint> Endpoints
{
	get
	{
		RouteEndpoint[] array = new RouteEndpoint[_routeEntries.Count];
		for (int i = 0; i < _routeEntries.Count; i++)
		{
			array[i] = (RouteEndpoint)CreateRouteEndpointBuilder(_routeEntries[i]).Build();
		}
		return array;
	}
}

Endpoint

RouteEndpoint 繼承自 Endpoint。多了一個 RoutePattern 屬性,用於路由匹配,支援模式路由。還有一個 Order 屬性,用於處理多匹配源下的優先順序問題。

public sealed class RouteEndpoint : Endpoint
{
	public int Order { get; }
	public RoutePattern RoutePattern { get; }
}

Endpoint 是一個應用程式中路的一個邏輯終結點。

public string? DisplayName { get; } // 終結點名稱
public EndpointMetadataCollection Metadata { get; }  // 後設資料
public RequestDelegate? RequestDelegate { get; }  // 請求委託

​ 其中 Metadata 就是一個object集合,包含描述、標籤、許可權等資料,這一般是框架用到的,後面會再次見到它。重點是 RequestDelegateHttpContext 首次登場,相信有過Web開發經驗的同學熟悉的不能再熟悉。該委託其實就是一個Func<HttpContext, Task>,用於處理HTTP請求,由於TAP的普及,所以返回的Task

public delegate Task RequestDelegate(HttpContext context);

Endpoint 一般由 EndpointBuilder 構建,他能夠額外組裝Filter

public IList<Func<EndpointFilterFactoryContext, EndpointFilterDelegate, EndpointFilterDelegate>> FilterFactories

EndpointDataSource

​ 經過對 MapGet 的剖析我們最終發現,所有的終結點都被掛載在了 EndpointDataSource

public abstract IReadOnlyList<Endpoint> Endpoints { get; }
public virtual IReadOnlyList<Endpoint> GetGroupedEndpoints(RouteGroupContext context)

​ 除了被大家熟悉的 Endpoints 還提供了一個方法 GetGroupedEndpoints:在給定指定字首和約定的情況下,獲取此EndpointDataSource 的所有 Endpoint的。

public virtual IReadOnlyList<Endpoint> GetGroupedEndpoints(RouteGroupContext context)
{
	IReadOnlyList<Endpoint> endpoints = Endpoints;
	RouteEndpoint[] array = new RouteEndpoint[endpoints.Count];
	for (int i = 0; i < endpoints.Count; i++)
	{
		Endpoint endpoint = endpoints[i];
		if (!(endpoint is RouteEndpoint routeEndpoint))
		{
			throw new NotSupportedException(Resources.FormatMapGroup_CustomEndpointUnsupported(endpoint.GetType()));
		}
		RoutePattern routePattern = RoutePatternFactory.Combine(context.Prefix, routeEndpoint.RoutePattern);
		RouteEndpointBuilder routeEndpointBuilder = new RouteEndpointBuilder(routeEndpoint.RequestDelegate, routePattern, routeEndpoint.Order)
		{
			DisplayName = routeEndpoint.DisplayName,
			ApplicationServices = context.ApplicationServices
		};
		foreach (Action<EndpointBuilder> convention in context.Conventions)
		{
			convention(routeEndpointBuilder);
		}
		foreach (object metadatum in routeEndpoint.Metadata)
		{
			routeEndpointBuilder.Metadata.Add(metadatum);
		}
		foreach (Action<EndpointBuilder> finallyConvention in context.FinallyConventions)
		{
			finallyConvention(routeEndpointBuilder);
		}
		array[i] = (RouteEndpoint)routeEndpointBuilder.Build();
	}
	return array;
}

​ 通過剖析 RouteGroupContext,很容易發覺,Prefix 是一個路由字首,ConventionsFinallyConventions 是兩個約定hook。它專為 RouteEndpoint 獨有,通過 GetGroupedEndpoints 方法,組的字首和約定,會作用到每一個路由終結點。

public sealed class RouteGroupContext
{
    public required RoutePattern Prefix { get; init; }
    public IReadOnlyList<Action<EndpointBuilder>> Conventions { get; init; } = Array.Empty<Action<EndpointBuilder>>();
    public IReadOnlyList<Action<EndpointBuilder>> FinallyConventions { get; init; } = Array.Empty<Action<EndpointBuilder>>();
}