Asp.Net Core EndPoint 終結點路由工做原理解讀

1、背景

在本打算寫一篇關於Identityserver4 的文章時候，確發現本身對EndPoint -終結點路由還不是很瞭解，故暫時先放棄了IdentityServer4 的研究和編寫；因此才產生了今天這篇關於EndPoint (終結點路由) 的文章。

仍是跟往常同樣，打開電腦使用強大的Google 和百度搜索引擎查閱相關資料，以及打開Asp.net core 3.1 的源代碼進行拜讀，同時終於在個人實踐及測試中對EndPoint 有了不同的認識，說到這裏更加敬佩微軟對Asp.net core 3.x 的框架中管道模型的設計。

我先來提出如下幾個問題：

1. 當訪問一個Web 應用地址時，Asp.Net Core 是怎麼執行到Controller 的Action的呢？
2. EndPoint 跟普通路由又存在着什麼樣的關係？
3. UseRouing() 、UseAuthorization()、UserEndpoints() 這三個中間件的關係是什麼呢？
4. 怎麼利用EndPoint 終結者路由來攔截Action 的執行而且記錄相關操做日誌？(時間有限，下一篇文章再來分享整理)

2、拜讀源碼解惑

Startup 代碼

咱們先來看一下Startup中簡化版的代碼，代碼以下：

public void ConfigureServices(IServiceCollection services)
{
        services.AddControllers();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
              endpoints.MapControllers();
        });
}

程序啓動階段：

• 第一步：執行services.AddControllers()
  將Controller的核心服務註冊到容器中去
• 第二步：執行app.UseRouting()
  將EndpointRoutingMiddleware中間件註冊到http管道中
• 第三步：執行app.UseAuthorization()
  將AuthorizationMiddleware中間件註冊到http管道中
• 第四步：執行app.UseEndpoints(encpoints=>endpoints.MapControllers())
  有兩個主要的做用：
  調用endpoints.MapControllers()將本程序集定義的全部Controller和Action轉換爲一個個的EndPoint放到路由中間件的配置對象RouteOptions中
  將EndpointMiddleware中間件註冊到http管道中

app.UseRouting() 源代碼以下：

public static IApplicationBuilder UseRouting(this IApplicationBuilder builder)
{
       if (builder == null)
       {
             throw new ArgumentNullException(nameof(builder));
       }

       VerifyRoutingServicesAreRegistered(builder);

       var endpointRouteBuilder = new DefaultEndpointRouteBuilder(builder);
       builder.Properties[EndpointRouteBuilder] = endpointRouteBuilder;
       
       return builder.UseMiddleware<EndpointRoutingMiddleware>(endpointRouteBuilder);
 }

EndpointRoutingMiddleware 中間件代碼以下：

internal sealed class EndpointRoutingMiddleware
    {
        private const string DiagnosticsEndpointMatchedKey = "Microsoft.AspNetCore.Routing.EndpointMatched";

        private readonly MatcherFactory _matcherFactory;
        private readonly ILogger _logger;
        private readonly EndpointDataSource _endpointDataSource;
        private readonly DiagnosticListener _diagnosticListener;
        private readonly RequestDelegate _next;

        private Task<Matcher> _initializationTask;

        public EndpointRoutingMiddleware(
            MatcherFactory matcherFactory,
            ILogger<EndpointRoutingMiddleware> logger,
            IEndpointRouteBuilder endpointRouteBuilder,
            DiagnosticListener diagnosticListener,
            RequestDelegate next)
        {
            if (endpointRouteBuilder == null)
            {
                throw new ArgumentNullException(nameof(endpointRouteBuilder));
            }

            _matcherFactory = matcherFactory ?? throw new ArgumentNullException(nameof(matcherFactory));
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
            _diagnosticListener = diagnosticListener ?? throw new ArgumentNullException(nameof(diagnosticListener));
            _next = next ?? throw new ArgumentNullException(nameof(next));

            _endpointDataSource = new CompositeEndpointDataSource(endpointRouteBuilder.DataSources);
        }

        public Task Invoke(HttpContext httpContext)
        {
            // There's already an endpoint, skip maching completely
            var endpoint = httpContext.GetEndpoint();
            if (endpoint != null)
            {
                Log.MatchSkipped(_logger, endpoint);
                return _next(httpContext);
            }

            // There's an inherent race condition between waiting for init and accessing the matcher
            // this is OK because once `_matcher` is initialized, it will not be set to null again.
            var matcherTask = InitializeAsync();
            if (!matcherTask.IsCompletedSuccessfully)
            {
                return AwaitMatcher(this, httpContext, matcherTask);
            }

            var matchTask = matcherTask.Result.MatchAsync(httpContext);
            if (!matchTask.IsCompletedSuccessfully)
            {
                return AwaitMatch(this, httpContext, matchTask);
            }

            return SetRoutingAndContinue(httpContext);

            // Awaited fallbacks for when the Tasks do not synchronously complete
            static async Task AwaitMatcher(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task<Matcher> matcherTask)
            {
                var matcher = await matcherTask;
                await matcher.MatchAsync(httpContext);
                await middleware.SetRoutingAndContinue(httpContext);
            }

            static async Task AwaitMatch(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task matchTask)
            {
                await matchTask;
                await middleware.SetRoutingAndContinue(httpContext);
            }

        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private Task SetRoutingAndContinue(HttpContext httpContext)
        {
            // If there was no mutation of the endpoint then log failure
            var endpoint = httpContext.GetEndpoint();
            if (endpoint == null)
            {
                Log.MatchFailure(_logger);
            }
            else
            {
                // Raise an event if the route matched
                if (_diagnosticListener.IsEnabled() && _diagnosticListener.IsEnabled(DiagnosticsEndpointMatchedKey))
                {
                    // We're just going to send the HttpContext since it has all of the relevant information
                    _diagnosticListener.Write(DiagnosticsEndpointMatchedKey, httpContext);
                }

                Log.MatchSuccess(_logger, endpoint);
            }

            return _next(httpContext);
        }

        // Initialization is async to avoid blocking threads while reflection and things
        // of that nature take place.
        //
        // We've seen cases where startup is very slow if we  allow multiple threads to race
        // while initializing the set of endpoints/routes. Doing CPU intensive work is a
        // blocking operation if you have a low core count and enough work to do.
        private Task<Matcher> InitializeAsync()
        {
            var initializationTask = _initializationTask;
            if (initializationTask != null)
            {
                return initializationTask;
            }

            return InitializeCoreAsync();
        }

        private Task<Matcher> InitializeCoreAsync()
        {
            var initialization = new TaskCompletionSource<Matcher>(TaskCreationOptions.RunContinuationsAsynchronously);
            var initializationTask = Interlocked.CompareExchange(ref _initializationTask, initialization.Task, null);
            if (initializationTask != null)
            {
                // This thread lost the race, join the existing task.
                return initializationTask;
            }

            // This thread won the race, do the initialization.
            try
            {
                var matcher = _matcherFactory.CreateMatcher(_endpointDataSource);

                // Now replace the initialization task with one created with the default execution context.
                // This is important because capturing the execution context will leak memory in ASP.NET Core.
                using (ExecutionContext.SuppressFlow())
                {
                    _initializationTask = Task.FromResult(matcher);
                }

                // Complete the task, this will unblock any requests that came in while initializing.
                initialization.SetResult(matcher);
                return initialization.Task;
            }
            catch (Exception ex)
            {
                // Allow initialization to occur again. Since DataSources can change, it's possible
                // for the developer to correct the data causing the failure.
                _initializationTask = null;

                // Complete the task, this will throw for any requests that came in while initializing.
                initialization.SetException(ex);
                return initialization.Task;
            }
        }

        private static class Log
        {
            private static readonly Action<ILogger, string, Exception> _matchSuccess = LoggerMessage.Define<string>(
                LogLevel.Debug,
                new EventId(1, "MatchSuccess"),
                "Request matched endpoint '{EndpointName}'");

            private static readonly Action<ILogger, Exception> _matchFailure = LoggerMessage.Define(
                LogLevel.Debug,
                new EventId(2, "MatchFailure"),
                "Request did not match any endpoints");

            private static readonly Action<ILogger, string, Exception> _matchingSkipped = LoggerMessage.Define<string>(
                LogLevel.Debug,
                new EventId(3, "MatchingSkipped"),
                "Endpoint '{EndpointName}' already set, skipping route matching.");

            public static void MatchSuccess(ILogger logger, Endpoint endpoint)
            {
                _matchSuccess(logger, endpoint.DisplayName, null);
            }

            public static void MatchFailure(ILogger logger)
            {
                _matchFailure(logger, null);
            }

            public static void MatchSkipped(ILogger logger, Endpoint endpoint)
            {
                _matchingSkipped(logger, endpoint.DisplayName, null);
            }
        }
    }

咱們從它的源碼中能夠看到，EndpointRoutingMiddleware中間件先是建立matcher，而後調用matcher.MatchAsync(httpContext)去尋找Endpoint，最後經過httpContext.GetEndpoint()驗證了是否已經匹配到了正確的Endpoint並交個下箇中間件繼續執行！

app.UseEndpoints() 源代碼

public static IApplicationBuilder UseEndpoints(this IApplicationBuilder builder, Action<IEndpointRouteBuilder> configure)
{
       if (builder == null)
       {
              throw new ArgumentNullException(nameof(builder));
       }

       if (configure == null)
       {
              throw new ArgumentNullException(nameof(configure));
       }

       VerifyRoutingServicesAreRegistered(builder);

       VerifyEndpointRoutingMiddlewareIsRegistered(builder, out var endpointRouteBuilder);

       configure(endpointRouteBuilder);

       // Yes, this mutates an IOptions. We're registering data sources in a global collection which
       // can be used for discovery of endpoints or URL generation.
       //
       // Each middleware gets its own collection of data sources, and all of those data sources also
       // get added to a global collection.
       var routeOptions = builder.ApplicationServices.GetRequiredService<IOptions<RouteOptions>>();
        foreach (var dataSource in endpointRouteBuilder.DataSources)
        {
              routeOptions.Value.EndpointDataSources.Add(dataSource);
        }

        return builder.UseMiddleware<EndpointMiddleware>();
}

internal class DefaultEndpointRouteBuilder : IEndpointRouteBuilder
{
        public DefaultEndpointRouteBuilder(IApplicationBuilder applicationBuilder)
        {
            ApplicationBuilder = applicationBuilder ?? throw new ArgumentNullException(nameof(applicationBuilder));
            DataSources = new List<EndpointDataSource>();
        }

        public IApplicationBuilder ApplicationBuilder { get; }

        public IApplicationBuilder CreateApplicationBuilder() => ApplicationBuilder.New();

        public ICollection<EndpointDataSource> DataSources { get; }

        public IServiceProvider ServiceProvider => ApplicationBuilder.ApplicationServices;
    }

代碼中構建了DefaultEndpointRouteBuilder 終結點路由構建者對象，該對象中存儲了Endpoint的集合數據；同時把終結者路由集合數據存儲在了routeOptions 中，並註冊了EndpointMiddleware 中間件到http管道中；
Endpoint對象代碼以下：

/// <summary>
/// Represents a logical endpoint in an application.
/// </summary>
public class Endpoint
{
        /// <summary>
        /// Creates a new instance of <see cref="Endpoint"/>.
        /// </summary>
        /// <param name="requestDelegate">The delegate used to process requests for the endpoint.</param>
        /// <param name="metadata">
        /// The endpoint <see cref="EndpointMetadataCollection"/>. May be null.
        /// </param>
        /// <param name="displayName">
        /// The informational display name of the endpoint. May be null.
        /// </param>
        public Endpoint(
            RequestDelegate requestDelegate,
            EndpointMetadataCollection metadata,
            string displayName)
        {
            // All are allowed to be null
            RequestDelegate = requestDelegate;
            Metadata = metadata ?? EndpointMetadataCollection.Empty;
            DisplayName = displayName;
        }

        /// <summary>
        /// Gets the informational display name of this endpoint.
        /// </summary>
        public string DisplayName { get; }

        /// <summary>
        /// Gets the collection of metadata associated with this endpoint.
        /// </summary>
        public EndpointMetadataCollection Metadata { get; }

        /// <summary>
        /// Gets the delegate used to process requests for the endpoint.
        /// </summary>
        public RequestDelegate RequestDelegate { get; }

        public override string ToString() => DisplayName ?? base.ToString();
    }

Endpoint 對象代碼中有兩個關鍵類型屬性分別是EndpointMetadataCollection 類型和RequestDelegate：

• EndpointMetadataCollection：存儲了Controller 和Action相關的元素集合，包含Action 上的Attribute 特性數據等
• RequestDelegate ：存儲了Action 也即委託，這裏是每個Controller 的Action 方法

再回過頭來看看EndpointMiddleware 中間件和核心代碼，EndpointMiddleware 的一大核心代碼主要是執行Endpoint 的RequestDelegate 委託，也即Controller 中的Action 的執行。

public Task Invoke(HttpContext httpContext)
{
        var endpoint = httpContext.GetEndpoint();
        if (endpoint?.RequestDelegate != null)
        {
             if (!_routeOptions.SuppressCheckForUnhandledSecurityMetadata)
             {
                 if (endpoint.Metadata.GetMetadata<IAuthorizeData>() != null &&
                        !httpContext.Items.ContainsKey(AuthorizationMiddlewareInvokedKey))
                  {
                      ThrowMissingAuthMiddlewareException(endpoint);
                  }

                  if (endpoint.Metadata.GetMetadata<ICorsMetadata>() != null &&
                       !httpContext.Items.ContainsKey(CorsMiddlewareInvokedKey))
                   {
                       ThrowMissingCorsMiddlewareException(endpoint);
                   }
             }

            Log.ExecutingEndpoint(_logger, endpoint);

            try
            {
                 var requestTask = endpoint.RequestDelegate(httpContext);
                 if (!requestTask.IsCompletedSuccessfully)
                 {
                     return AwaitRequestTask(endpoint, requestTask, _logger);
                 }
            }
            catch (Exception exception)
            {
                 Log.ExecutedEndpoint(_logger, endpoint);
                 return Task.FromException(exception);
            }

            Log.ExecutedEndpoint(_logger, endpoint);
            return Task.CompletedTask;
        }

        return _next(httpContext);

        static async Task AwaitRequestTask(Endpoint endpoint, Task requestTask, ILogger logger)
         {
             try
             {
                 await requestTask;
             }
             finally
             {
                 Log.ExecutedEndpoint(logger, endpoint);
             }
         }
}

疑惑解答：

1. 當訪問一個Web 應用地址時，Asp.Net Core 是怎麼執行到Controller 的Action的呢？

答：程序啓動的時候會把全部的Controller 中的Action 映射存儲到routeOptions 的集合中，Action 映射成Endpoint終結者 的RequestDelegate 委託屬性，最後經過UseEndPoints 添加EndpointMiddleware 中間件進行執行，同時這個中間件中的Endpoint 終結者路由已是經過Rouing匹配後的路由。

2. EndPoint 跟普通路由又存在着什麼樣的關係？

答：Ednpoint 終結者路由是普通路由map 轉換後的委託路由，裏面包含了路由方法的全部元素信息EndpointMetadataCollection 和RequestDelegate 委託。

3. UseRouing() 、UseAuthorization()、UseEndpoints() 這三個中間件的關係是什麼呢？

答：UseRouing 中間件主要是路由匹配，找到匹配的終結者路由Endpoint ；UseEndpoints 中間件主要針對UseRouing 中間件匹配到的路由進行 委託方法的執行等操做。
UseAuthorization 中間件主要針對 UseRouing 中間件中匹配到的路由進行攔截 作受權驗證操做等，經過則執行下一個中間件UseEndpoints(),具體的關係能夠看下面的流程圖：

上面流程圖中省略了一些部分，主要是把UseRouing 、UseAuthorization 、UseEndpoint 這三個中間件的關係突顯出來。

若是您覺的不錯，請微信掃碼關注 【dotNET 博士】公衆號，後續給您帶來更精彩的分享

以上若是有錯誤得地方，請你們積極糾正，謝謝你們得支持！！