.NetCore 小笨蛋 发布于:2022年10月16日 更新于:2022年10月16日 135

Routing

  • Routing(路由):更准确的应该叫做Endpoint Routing,负责将HTTP请求按照匹配规则选择对应的终结点
  • Endpoint(终结点):负责当HTTP请求到达时,执行代码

路由是通过UseRouting和UseEndpoints两个中间件配合在一起来完成注册的:

  1. public class Startup
  2. {
  3. public void ConfigureServices(IServiceCollection services)
  4. {
  5. // 添加Routing相关服务
  6. // 注意,其已在 ConfigureWebDefaults 中添加,无需手动添加,此处仅为演示
  7. services.AddRouting();
  8. }
  9. public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  10. {
  11. app.UseRouting();
  12. app.UseEndpoints(endpoints =>
  13. {
  14. endpoints.MapGet("/", async context =>
  15. {
  16. await context.Response.WriteAsync("Hello World!");
  17. });
  18. });
  19. }
  20. }
  • UseRouting:用于向中间件管道添加路由匹配中间件(EndpointRoutingMiddleware)。该中间件会检查应用中定义的终结点列表,然后通过匹配 URL 和 HTTP 方法来选择最佳的终结点。简单说,该中间件的作用是根据一定规则来选择出终结点
  • UseEndpoints:用于向中间件管道添加终结点中间件(EndpointMiddleware)。可以向该中间件的终结点列表中添加终结点,并配置这些终结点要执行的委托,该中间件会负责运行由EndpointRoutingMiddleware中间件选择的终结点所关联的委托。简单说,该中间件用来执行所选择的终结点委托

UseRouting与UseEndpoints必须同时使用,而且必须先调用UseRouting,再调用UseEndpoints

Endpoints

先了解一下终结点的类结构:

  1. public class Endpoint
  2. {
  3. public Endpoint(RequestDelegate requestDelegate, EndpointMetadataCollection? metadata, string? displayName);
  4. public string? DisplayName { get; }
  5. public EndpointMetadataCollection Metadata { get; }
  6. public RequestDelegate RequestDelegate { get; }
  7. public override string? ToString();
  8. }

终结点有以下特点:

  • 可执行:含有RequestDelegate委托
  • 可扩展:含有Metadata元数据集合
  • 可选择:可选的包含路由信息
  • 可枚举:通过DI容器,查找EndpointDataSource来展示终结点集合。

在中间件管道中获取路由选择的终结点

在中间件管道中,我们可以通过HttpContext来检索终结点等信息。需要注意的是,终结点对象在创建完毕后,是不可变的,无法修改。

  • 在调用UseRouting之前,你可以注册一些用于修改路由操作的数据,比如UseRewriter、UseHttpMethodOverride、UsePathBase等。
  • 在调用UseRouting和UseEndpoints之间,可以注册一些用于提前处理路由结果的中间件,如UseAuthentication、UseAuthorization、UseCors等。

我们一起看下面的代码:

  1. public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  2. {
  3. app.Use(next => context =>
  4. {
  5. // 在 UseRouting 调用前,始终为 null
  6. Console.WriteLine($"1. Endpoint: {context.GetEndpoint()?.DisplayName ?? "null"}");
  7. return next(context);
  8. });
  9. // EndpointRoutingMiddleware 调用 SetEndpoint 来设置终结点
  10. app.UseRouting();
  11. app.Use(next => context =>
  12. {
  13. // 如果路由匹配到了终结点,那么此处就不为 null,否则,还是 null
  14. Console.WriteLine($"2. Endpoint: {context.GetEndpoint()?.DisplayName ?? "null"}");
  15. return next(context);
  16. });
  17. // EndpointMiddleware 通过 GetEndpoint 方法获取终结点,
  18. // 然后执行该终结点的 RequestDelegate 委托
  19. app.UseEndpoints(endpoints =>
  20. {
  21. endpoints.MapGet("/", context =>
  22. {
  23. // 匹配到了终结点,肯定不是 null
  24. Console.WriteLine($"3. Endpoint: {context.GetEndpoint()?.DisplayName ?? "null"}");
  25. return Task.CompletedTask;
  26. }).WithDisplayName("Custom Display Name"); // 自定义终结点名称
  27. });
  28. app.Use(next => context =>
  29. {
  30. // 只有当路由没有匹配到终结点时,才会执行这里
  31. Console.WriteLine($"4. Endpoint: {context.GetEndpoint()?.DisplayName ?? "null"}");
  32. return next(context);
  33. });
  34. }

当访问/时,输出为:

  1. 1. Endpoint: null
  2. 2. Endpoint: Custom Display Name
  3. 3. Endpoint: Custom Display Name

当访问其他不匹配的URL时,输出为:

  1. 1. Endpoint: null
  2. 2. Endpoint: null
  3. 4. Endpoint: null

当路由匹配到了终结点时,EndpointMiddleware则是该路由的终端中间件;当未匹配到终结点时,会继续执行后面的中间件。

终端中间件:与普通中间件不同的是,该中间件执行后即返回,不会调用后面的中间件。

配置终结点委托

可以通过以下方法将委托关联到终结点

  • MapGet
  • MapPost
  • MapPut
  • MapDelete
  • MapHealthChecks
  • 其他类似“MapXXX”的方法
  1. public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  2. {
  3. app.UseRouting();
  4. // 在执行终结点前进行授权
  5. app.UseAuthorization();
  6. app.UseEndpoints(endpoints =>
  7. {
  8. endpoints.MapGet("/", async context => await context.Response.WriteAsync("get"));
  9. endpoints.MapPost("/", async context => await context.Response.WriteAsync("post"));
  10. endpoints.MapPut("/", async context => await context.Response.WriteAsync("put"));
  11. endpoints.MapDelete("/", async context => await context.Response.WriteAsync("delete"));
  12. endpoints.MapHealthChecks("/healthChecks");
  13. endpoints.MapControllers();
  14. });
  15. }

路由模板

规则:

  • 通过{}来绑定路由参数,如: {name}
  • 将?作为参数后缀,以指示该参数是可选的,如:{name?}
  • 通过=设置默认值,如:{name=jjj} 表示name的默认值是jjj
  • 通过:添加内联约束,如:{id:int},后面追加:可以添加多个内联约束,如:{id:int:min(1)}
  • 多个路由参数间必须通过文本或分隔符分隔,例如 {a}{b} 就不符合规则,可以修改为类似 {a}+-{b} 或 {a}/{b} 的形式
  • 先举个例子,/book/{name}中的{name}为路由参数,book为非路由参数文本。非路由参数的文本和分隔符/:
    • 是不分区大小写的(官方中文文档翻译错了)
    • 要使用没有被Url编码的格式,如空格会被编码为 %20,不应使用 %20,而应使用空格
    • 如果要匹配{或},则使用{{或}}进行转义

catch-all参数

路由模板中的星号和双星号**被称为catch-all参数,该参数可以作为路由参数的前缀,如/Book/{id}、/Book/{**id},可以匹配以/Book开头的任意Url,如/Book、/Book/、/Book/abc、/Book/abc/def等。

和**在一般使用上没有什么区别,它们仅仅在使用LinkGenerator时会有不同,如id = abc/def,当使用/Book/{id}模板时,会生成/Book/abc%2Fdef,当使用/Book/{**id}模板时,会生成/Book/abc/def。

复杂段

复杂段通过非贪婪的方式从右到左进行匹配,例如[Route(“/a{b}c{d}”)]就是一个复杂段。实际上,它的确很复杂,只有了解它的工作方式,才能正确的使用它。

  • 贪婪匹配(也称为“懒惰匹配”):匹配最大可能的字符串
  • 非贪婪匹配:匹配最小可能的字符串

接下来,就拿模板[Route(“/a{b}c{d}”)]来举两个例子:

成功匹配的案例——当Url为/abcd时,匹配过程为(|用于辅助展示算法的解析方式):

  • 从右到左读取模板,找到的第一个文本为c。接着,读取Url/abcd,可解析为/ab|c|d
  • 此时,Url中右侧的所有内容d均与路由参数{d}匹配
  • 然后,继续从右到左读取模板,找到的下一个文本为a。接着,从刚才停下的地方继续读取Url/ab|c|d,解析为/a|b|c|d
  • 此时,Url中右侧的值b与路由参数{b}匹配
  • 最后,没有剩余的路由模板段或参数,也没有剩余的Url文本,因此匹配成功。

匹配失败的案例——当Url为/aabcd时,匹配过程为(|用于辅助展示算法的解析方式):

  • 从右到左读取模板,找到的第一个文本为c。接着,读取Url/aabcd,可解析为/aab|c|d
  • 此时,Url中右侧的所有内容d均与路由参数{d}匹配
  • 然后,继续从右到左读取模板,找到的下一个文本为a。接着,从刚才停下的地方继续读取Url/aab|c|d,解析为/a|a|b|c|d
  • 此时,Url中右侧的值b与路由参数{b}匹配
  • 最后,没有剩余的路由模板段或参数,但还有剩余的Url文本,因此匹配不成功。

使用复杂段,相比普通路由模板来说,会造成更加昂贵的性能影响

路由约束

通过路由约束,可以在路由匹配过程中,检查URL是否是可接受的。另外,路由约束一般是用来消除路由歧义,而不是用来进行输入验证的。

实现上,当Http请求到达时,路由参数和该参数的约束名会传递给IInlineConstraintResolver服务,IInlineConstraintResolver服务会负责创建IRouteConstraint实例,以针对Url进行处理。

预定义的路由约束
约束 示例 匹配项示例 说明
int {id:int} 123456789, -123456789 匹配任何整数
bool {active:bool} true, FALSE 匹配 true 或 false。 不区分大小写
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm 匹配固定区域中的有效 DateTime 值
decimal {price:decimal 49.99, -1,000.01 匹配固定区域中的有效 decimal 值。
double {weight:double} 1.234, -1,001.01e8 匹配固定区域中的有效 double 值。
float {weight:float} 1.234, -1,001.01e8 匹配固定区域中的有效 float 值。
guid {id:guid} CD2C1638-1638-72D5-1638-DEADBEEF1638 匹配有效的 Guid 值
long {ticks:long} 123456789, -123456789 匹配有效的 long 值
minlength(value) {username:minlength(4)} Rick 字符串必须至少为 4 个字符
maxlength(value) {filename:maxlength(8)} MyFile 字符串不得超过 8 个字符
length(length) {filename:length(12)} somefile.txt 字符串必须正好为 12 个字符
length(min,max) {filename:length(8,16)} somefile.txt 字符串必须至少为 8 个字符,且不得超过 16 个字符
min(value) {age:min(18)} 19 整数值必须至少为 18
max(value) {age:max(120)} 91 整数值不得超过 120
range(min,max) {age:range(18,120)} 91 整数值必须至少为 18,且不得超过 120
alpha {name:alpha} Rick 字符串必须由一个或多个字母字符组成,a-z,并区分大小写。
regex(expression) {ssn:regex(^\d{{3}}-\d{{2}}-\d{{4}}$)} 123-45-6789 字符串必须与正则表达式匹配
required {name:required} Rick 用于强制在 URL 生成过程中存在非参数值
正则表达式路由约束

通过regex(expression)来设置正则表达式约束,并且该正则表达式是:

  • RegexOptions.IgnoreCase:忽略大小写
  • RegexOptions.Compiled:将该正则表达式编译为程序集。这会使得执行速度更快,但会拖慢启动时间。
  • RegexOptions.CultureInvariant:忽略区域文化差异。

另外,还需要注意对某些字符进行转义:

  • \替换为\
  • {替换为{{, }替换为}}
  • [替换为[[,]替换为]]

例如:

标准正则表达式 转义的正则表达式
^\d{3}-\d{2}-\d{4}$ ^\d{{3}}-\d{{2}}-\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$
  • 指定 regex 约束的两种方式:
    ```csharp
    // 内联方式
    app.UseEndpoints(endpoints =>
    {
    endpoints.MapGet(“{message:regex(^\d{{3}}-\d{{2}}-\d{{4}}$)}”,
    1. context =>
    2. {
    3. return context.Response.WriteAsync("inline-constraint match");
    4. });
    });

// 变量声明方式
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: “people”,
pattern: “People/{ssn}”,
constraints: new { ssn = “^\d{3}-\d{2}-\d{4}$”, },
defaults: new { controller = “People”, action = “List”, });
});

  1. > 不要书写过于复杂的正则表达式,否则,相比普通路由模板来说,会造成更加昂贵的性能影响
  2. ###### 自定义路由约束
  3. 先说一句,自定义路由约束很少会用到,在你决定要自定义路由约束之前,先想想是否有其他更好的替代方案,如使用模型绑定。
  4. 通过实现IRouteConstraint接口来创建自定义路由约束,该接口仅有一个Match方法,用于验证路由参数是否满足约束,返回true表示满足约束,false则表示不满足约束。
  5. 以下示例要求路由参数中必须包含字符串“1”:
  6. ```csharp
  7. public class MyRouteConstraint : IRouteConstraint
  8. {
  9. public bool Match(HttpContext httpContext, IRouter route, string routeKey, RouteValueDictionary values, RouteDirection routeDirection)
  10. {
  11. if (values.TryGetValue(routeKey, out object value))
  12. {
  13. var valueStr = Convert.ToString(value, CultureInfo.InvariantCulture);
  14. return valueStr?.Contains("1") ?? false;
  15. }
  16. return false;
  17. }
  18. }

然后进行路由约束注册:

  1. public void ConfigureServices(IServiceCollection services)
  2. {
  3. services.AddRouting(options =>
  4. {
  5. // 添加自定义路由约束,约束 Key 为 my
  6. options.ConstraintMap["my"] = typeof(MyRouteConstraint);
  7. });
  8. }

最后你就可以类似如下进行使用了:

  1. [HttpGet("{id:my}")]
  2. public string Get(string id)
  3. {
  4. return id;
  5. }

路由模板优先级

考虑一下,有两个路由模板:/Book/List和/Book/{id},当url为/Book/List时,会选择哪个呢?从结果我们可以得知,是模板/Book/List。它是根据以下规则来确定的:

  • 越具体的模板优先级越高
  • 包含更多匹配段的模板更具体
  • 含有文本的段比参数段更具体
  • 具有约束的参数段比没有约束的参数段更具体
  • 复杂段和具有约束的段同样具体
  • catch-all参数段是最不具体的

核心源码解析

AddRouting

  1. public static class RoutingServiceCollectionExtensions
  2. {
  3. public static IServiceCollection AddRouting(this IServiceCollection services)
  4. {
  5. // 内联约束解析器,负责创建 IRouteConstraint 实例
  6. services.TryAddTransient<IInlineConstraintResolver, DefaultInlineConstraintResolver>();
  7. // 对象池
  8. services.TryAddTransient<ObjectPoolProvider, DefaultObjectPoolProvider>();
  9. services.TryAddSingleton<ObjectPool<UriBuildingContext>>(s =>
  10. {
  11. var provider = s.GetRequiredService<ObjectPoolProvider>();
  12. return provider.Create<UriBuildingContext>(new UriBuilderContextPooledObjectPolicy());
  13. });
  14. services.TryAdd(ServiceDescriptor.Transient<TreeRouteBuilder>(s =>
  15. {
  16. var loggerFactory = s.GetRequiredService<ILoggerFactory>();
  17. var objectPool = s.GetRequiredService<ObjectPool<UriBuildingContext>>();
  18. var constraintResolver = s.GetRequiredService<IInlineConstraintResolver>();
  19. return new TreeRouteBuilder(loggerFactory, objectPool, constraintResolver);
  20. }));
  21. // 标记已将所有路由服务注册完毕
  22. services.TryAddSingleton(typeof(RoutingMarkerService));
  23. var dataSources = new ObservableCollection<EndpointDataSource>();
  24. services.TryAddEnumerable(ServiceDescriptor.Transient<IConfigureOptions<RouteOptions>, ConfigureRouteOptions>(
  25. serviceProvider => new ConfigureRouteOptions(dataSources)));
  26. // EndpointDataSource,用于全局访问终结点列表
  27. services.TryAddSingleton<EndpointDataSource>(s =>
  28. {
  29. return new CompositeEndpointDataSource(dataSources);
  30. });
  31. services.TryAddSingleton<ParameterPolicyFactory, DefaultParameterPolicyFactory>();
  32. // MatcherFactory,用于根据 EndpointDataSource 创建 Matcher
  33. services.TryAddSingleton<MatcherFactory, DfaMatcherFactory>();
  34. // DfaMatcherBuilder,用于创建 DfaMatcher 实例
  35. services.TryAddTransient<DfaMatcherBuilder>();
  36. services.TryAddSingleton<DfaGraphWriter>();
  37. services.TryAddTransient<DataSourceDependentMatcher.Lifetime>();
  38. services.TryAddSingleton<EndpointMetadataComparer>(services =>
  39. {
  40. return new EndpointMetadataComparer(services);
  41. });
  42. // LinkGenerator相关服务
  43. services.TryAddSingleton<LinkGenerator, DefaultLinkGenerator>();
  44. services.TryAddSingleton<IEndpointAddressScheme<string>, EndpointNameAddressScheme>();
  45. services.TryAddSingleton<IEndpointAddressScheme<RouteValuesAddress>, RouteValuesAddressScheme>();
  46. services.TryAddSingleton<LinkParser, DefaultLinkParser>();
  47. // 终结点选择、匹配策略相关服务
  48. services.TryAddSingleton<EndpointSelector, DefaultEndpointSelector>();
  49. services.TryAddEnumerable(ServiceDescriptor.Singleton<MatcherPolicy, HttpMethodMatcherPolicy>());
  50. services.TryAddEnumerable(ServiceDescriptor.Singleton<MatcherPolicy, HostMatcherPolicy>());
  51. services.TryAddSingleton<TemplateBinderFactory, DefaultTemplateBinderFactory>();
  52. services.TryAddSingleton<RoutePatternTransformer, DefaultRoutePatternTransformer>();
  53. return services;
  54. }
  55. public static IServiceCollection AddRouting(
  56. this IServiceCollection services,
  57. Action<RouteOptions> configureOptions)
  58. {
  59. services.Configure(configureOptions);
  60. services.AddRouting();
  61. return services;
  62. }
  63. }

UseRouting

  1. public static class EndpointRoutingApplicationBuilderExtensions
  2. {
  3. private const string EndpointRouteBuilder = "__EndpointRouteBuilder";
  4. public static IApplicationBuilder UseRouting(this IApplicationBuilder builder)
  5. {
  6. VerifyRoutingServicesAreRegistered(builder);
  7. var endpointRouteBuilder = new DefaultEndpointRouteBuilder(builder);
  8. // 将 endpointRouteBuilder 放入共享字典中
  9. builder.Properties[EndpointRouteBuilder] = endpointRouteBuilder;
  10. // 将 endpointRouteBuilder 作为构造函数参数传入 EndpointRoutingMiddleware
  11. return builder.UseMiddleware<EndpointRoutingMiddleware>(endpointRouteBuilder);
  12. }
  13. private static void VerifyRoutingServicesAreRegistered(IApplicationBuilder app)
  14. {
  15. // 必须先执行了 AddRouting
  16. if (app.ApplicationServices.GetService(typeof(RoutingMarkerService)) == null)
  17. {
  18. throw new InvalidOperationException(Resources.FormatUnableToFindServices(
  19. nameof(IServiceCollection),
  20. nameof(RoutingServiceCollectionExtensions.AddRouting),
  21. "ConfigureServices(...)"));
  22. }
  23. }
  24. }

EndpointRoutingMiddleware

终于到了路由匹配的逻辑了,才是我们应该关注的,重点查看Invoke:

  1. internal sealed class EndpointRoutingMiddleware
  2. {
  3. private const string DiagnosticsEndpointMatchedKey = "Microsoft.AspNetCore.Routing.EndpointMatched";
  4. private readonly MatcherFactory _matcherFactory;
  5. private readonly ILogger _logger;
  6. private readonly EndpointDataSource _endpointDataSource;
  7. private readonly DiagnosticListener _diagnosticListener;
  8. private readonly RequestDelegate _next;
  9. private Task<Matcher>? _initializationTask;
  10. public EndpointRoutingMiddleware(
  11. MatcherFactory matcherFactory,
  12. ILogger<EndpointRoutingMiddleware> logger,
  13. IEndpointRouteBuilder endpointRouteBuilder,
  14. DiagnosticListener diagnosticListener,
  15. RequestDelegate next)
  16. {
  17. _matcherFactory = matcherFactory ?? throw new ArgumentNullException(nameof(matcherFactory));
  18. _logger = logger ?? throw new ArgumentNullException(nameof(logger));
  19. _diagnosticListener = diagnosticListener ?? throw new ArgumentNullException(nameof(diagnosticListener));
  20. _next = next ?? throw new ArgumentNullException(nameof(next));
  21. _endpointDataSource = new CompositeEndpointDataSource(endpointRouteBuilder.DataSources);
  22. }
  23. public Task Invoke(HttpContext httpContext)
  24. {
  25. // 已经选择了终结点,则跳过匹配
  26. var endpoint = httpContext.GetEndpoint();
  27. if (endpoint != null)
  28. {
  29. Log.MatchSkipped(_logger, endpoint);
  30. return _next(httpContext);
  31. }
  32. // 等待 _initializationTask 初始化完成,进行匹配,并流转到下一个中间件
  33. var matcherTask = InitializeAsync();
  34. if (!matcherTask.IsCompletedSuccessfully)
  35. {
  36. return AwaitMatcher(this, httpContext, matcherTask);
  37. }
  38. // _initializationTask在之前就已经初始化完成了,直接进行匹配任务,并流转到下一个中间件
  39. var matchTask = matcherTask.Result.MatchAsync(httpContext);
  40. if (!matchTask.IsCompletedSuccessfully)
  41. {
  42. return AwaitMatch(this, httpContext, matchTask);
  43. }
  44. // 流转到下一个中间件
  45. return SetRoutingAndContinue(httpContext);
  46. static async Task AwaitMatcher(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task<Matcher> matcherTask)
  47. {
  48. var matcher = await matcherTask;
  49. // 路由匹配,选择终结点
  50. await matcher.MatchAsync(httpContext);
  51. await middleware.SetRoutingAndContinue(httpContext);
  52. }
  53. static async Task AwaitMatch(EndpointRoutingMiddleware middleware, HttpContext httpContext, Task matchTask)
  54. {
  55. await matchTask;
  56. await middleware.SetRoutingAndContinue(httpContext);
  57. }
  58. }
  59. [MethodImpl(MethodImplOptions.AggressiveInlining)]
  60. private Task SetRoutingAndContinue(HttpContext httpContext)
  61. {
  62. // 终结点仍然为空,则匹配失败
  63. var endpoint = httpContext.GetEndpoint();
  64. if (endpoint == null)
  65. {
  66. Log.MatchFailure(_logger);
  67. }
  68. else
  69. {
  70. // 匹配成功则触发事件
  71. if (_diagnosticListener.IsEnabled() && _diagnosticListener.IsEnabled(DiagnosticsEndpointMatchedKey))
  72. {
  73. // httpContext对象包含了相关信息
  74. _diagnosticListener.Write(DiagnosticsEndpointMatchedKey, httpContext);
  75. }
  76. Log.MatchSuccess(_logger, endpoint);
  77. }
  78. // 流转到下一个中间件
  79. return _next(httpContext);
  80. }
  81. private Task<Matcher> InitializeAsync()
  82. {
  83. var initializationTask = _initializationTask;
  84. if (initializationTask != null)
  85. {
  86. return initializationTask;
  87. }
  88. // 此处我删减了部分线程竞争代码,因为这不是我们讨论的重点
  89. // 此处主要目的是在该Middleware中,确保只初始化_initializationTask一次
  90. var matcher = _matcherFactory.CreateMatcher(_endpointDataSource);
  91. using (ExecutionContext.SuppressFlow())
  92. {
  93. _initializationTask = Task.FromResult(matcher);
  94. }
  95. }
  96. }

上述代码的核心就是将_endpointDataSource传递给_matcherFactory,创建matcher,然后进行匹配matcher.MatchAsync(httpContext)。ASP.NET Core默认使用的 matcher 类型是DfaMatcher,DFA(Deterministic Finite Automaton)是一种被称为“确定有限状态自动机”的算法,可以从候选终结点列表中查找到匹配度最高的那个终结点。

UseEndpoints

  1. public static class EndpointRoutingApplicationBuilderExtensions
  2. {
  3. public static IApplicationBuilder UseEndpoints(this IApplicationBuilder builder, Action<IEndpointRouteBuilder> configure)
  4. {
  5. VerifyRoutingServicesAreRegistered(builder);
  6. VerifyEndpointRoutingMiddlewareIsRegistered(builder, out var endpointRouteBuilder);
  7. configure(endpointRouteBuilder);
  8. var routeOptions = builder.ApplicationServices.GetRequiredService<IOptions<RouteOptions>>();
  9. foreach (var dataSource in endpointRouteBuilder.DataSources)
  10. {
  11. routeOptions.Value.EndpointDataSources.Add(dataSource);
  12. }
  13. return builder.UseMiddleware<EndpointMiddleware>();
  14. }
  15. private static void VerifyEndpointRoutingMiddlewareIsRegistered(IApplicationBuilder app, out DefaultEndpointRouteBuilder endpointRouteBuilder)
  16. {
  17. // 将 endpointRouteBuilder 从共享字典中取出来,如果没有,则说明之前没有调用 UseRouting
  18. if (!app.Properties.TryGetValue(EndpointRouteBuilder, out var obj))
  19. {
  20. var message =
  21. $"{nameof(EndpointRoutingMiddleware)} matches endpoints setup by {nameof(EndpointMiddleware)} and so must be added to the request " +
  22. $"execution pipeline before {nameof(EndpointMiddleware)}. " +
  23. $"Please add {nameof(EndpointRoutingMiddleware)} by calling '{nameof(IApplicationBuilder)}.{nameof(UseRouting)}' inside the call " +
  24. $"to 'Configure(...)' in the application startup code.";
  25. throw new InvalidOperationException(message);
  26. }
  27. endpointRouteBuilder = (DefaultEndpointRouteBuilder)obj!;
  28. // UseRouting 和 UseEndpoints 必须添加到同一个 IApplicationBuilder 实例上
  29. if (!object.ReferenceEquals(app, endpointRouteBuilder.ApplicationBuilder))
  30. {
  31. var message =
  32. $"The {nameof(EndpointRoutingMiddleware)} and {nameof(EndpointMiddleware)} must be added to the same {nameof(IApplicationBuilder)} instance. " +
  33. $"To use Endpoint Routing with 'Map(...)', make sure to call '{nameof(IApplicationBuilder)}.{nameof(UseRouting)}' before " +
  34. $"'{nameof(IApplicationBuilder)}.{nameof(UseEndpoints)}' for each branch of the middleware pipeline.";
  35. throw new InvalidOperationException(message);
  36. }
  37. }
  38. }

EndpointMiddleware

EndpointMiddleware中间件中包含了很多异常处理和日志记录代码,为了方便查看核心逻辑,我都删除并进行了简化:

  1. internal sealed class EndpointMiddleware
  2. {
  3. internal const string AuthorizationMiddlewareInvokedKey = "__AuthorizationMiddlewareWithEndpointInvoked";
  4. internal const string CorsMiddlewareInvokedKey = "__CorsMiddlewareWithEndpointInvoked";
  5. private readonly ILogger _logger;
  6. private readonly RequestDelegate _next;
  7. private readonly RouteOptions _routeOptions;
  8. public EndpointMiddleware(
  9. ILogger<EndpointMiddleware> logger,
  10. RequestDelegate next,
  11. IOptions<RouteOptions> routeOptions)
  12. {
  13. _logger = logger ?? throw new ArgumentNullException(nameof(logger));
  14. _next = next ?? throw new ArgumentNullException(nameof(next));
  15. _routeOptions = routeOptions?.Value ?? throw new ArgumentNullException(nameof(routeOptions));
  16. }
  17. public Task Invoke(HttpContext httpContext)
  18. {
  19. var endpoint = httpContext.GetEndpoint();
  20. if (endpoint?.RequestDelegate != null)
  21. {
  22. // 执行该终结点的委托,并且视该中间件为终端中间件
  23. var requestTask = endpoint.RequestDelegate(httpContext);
  24. if (!requestTask.IsCompletedSuccessfully)
  25. {
  26. return requestTask;
  27. }
  28. return Task.CompletedTask;
  29. }
  30. // 若没有终结点,则继续执行下一个中间件
  31. return _next(httpContext);
  32. }
  33. }

总结

说了那么多,最后给大家总结了三张UML类图:

RoutePattern

EndPoint

Matcher

另外,本文仅仅提到了路由的基本使用方式和原理,如果你想要进行更加深入透彻的了解,推荐阅读蒋金楠老师的ASP.NET Core 3框架揭秘的路由部分。

这里⇓感觉得写点什么,要不显得有点空,但还没想好写什么... 返回顶部
About 京ICP备13038605号 © 代码片段 2025