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

在本打算寫一篇關於Identityserver4 的文章時候，確發現自己對EndPoint -終結點路由還不是很瞭解，故暫時先放棄了IdentityServer4 的研究和編寫；所以才產生了今天這篇關於EndPoint (終結點路由) 的文章。還是跟往常一樣，打開電腦使用強大的Google 和百... ...

一、背景

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

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

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

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

二、拜讀源碼解惑

`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 博士】公眾號，後續給您帶來更精彩的分享

以上如果有錯誤得地方，請大家積極糾正，謝謝大家得支持！！

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

一、背景

二、拜讀源碼解惑

Startup 代碼

app.UseRouting() 源代碼如下：

app.UseEndpoints() 源代碼