Test/Add comprehensive CQRS benchmarking suite with reflection and generated invoker paths

GFramework.Cqrs.Benchmarks/CustomColumn.cs

@@ -0,0 +1,71 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using BenchmarkDotNet.Columns;
+using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
+using System;
+
+namespace GFramework.Cqrs.Benchmarks;
+
+/// <summary>
+///     为 CQRS benchmark 结果补充可读的场景标签列。
+/// </summary>
+/// <param name="columnName">列名。</param>
+/// <param name="getValue">从 benchmark case 提取列值的委托。</param>
+public sealed class CustomColumn(string columnName, Func<Summary, BenchmarkCase, string> getValue) : IColumn
+{
+    /// <inheritdoc />
+    public string Id => $"{nameof(CustomColumn)}.{ColumnName}";
+
+    /// <inheritdoc />
+    public string ColumnName { get; } = columnName;
+
+    /// <inheritdoc />
+    public bool AlwaysShow => true;
+
+    /// <inheritdoc />
+    public ColumnCategory Category => ColumnCategory.Params;
+
+    /// <inheritdoc />
+    public int PriorityInCategory => 0;
+
+    /// <inheritdoc />
+    public bool IsNumeric => false;
+
+    /// <inheritdoc />
+    public UnitType UnitType => UnitType.Dimensionless;
+
+    /// <inheritdoc />
+    public string Legend => $"Custom '{ColumnName}' tag column";
+
+    /// <inheritdoc />
+    public bool IsDefault(Summary summary, BenchmarkCase benchmarkCase)
+    {
+        return false;
+    }
+
+    /// <inheritdoc />
+    public bool IsAvailable(Summary summary)
+    {
+        return true;
+    }
+
+    /// <inheritdoc />
+    public string GetValue(Summary summary, BenchmarkCase benchmarkCase)
+    {
+        return getValue(summary, benchmarkCase);
+    }
+
+    /// <inheritdoc />
+    public string GetValue(Summary summary, BenchmarkCase benchmarkCase, SummaryStyle style)
+    {
+        return GetValue(summary, benchmarkCase);
+    }
+
+    /// <inheritdoc />
+    public override string ToString()
+    {
+        return ColumnName;
+    }
+}

GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj

@@ -0,0 +1,30 @@
+<!--
+  Copyright (c) 2025-2026 GeWuYou
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>disable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+        <GenerateDocumentationFile>false</GenerateDocumentationFile>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
+        <PackageReference Include="MediatR" Version="13.1.0" />
+        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.7" />
+        <PackageReference Include="Microsoft.Extensions.Logging" Version="10.0.0" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\GFramework.Cqrs.Abstractions\GFramework.Cqrs.Abstractions.csproj" />
+        <ProjectReference Include="..\GFramework.Cqrs\GFramework.Cqrs.csproj" />
+        <ProjectReference Include="..\GFramework.Core.Abstractions\GFramework.Core.Abstractions.csproj" />
+        <ProjectReference Include="..\GFramework.Core\GFramework.Core.csproj" />
+    </ItemGroup>
+
+</Project>

GFramework.Cqrs.Benchmarks/Messaging/BenchmarkContext.cs

@@ -0,0 +1,17 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using GFramework.Cqrs.Abstractions.Cqrs;
+
+namespace GFramework.Cqrs.Benchmarks.Messaging;
+
+/// <summary>
+///     为纯 runtime benchmark 提供最小 CQRS 上下文标记，避免把完整架构上下文初始化成本混入 steady-state dispatch。
+/// </summary>
+internal sealed class BenchmarkContext : ICqrsContext
+{
+    /// <summary>
+    ///     共享的最小 CQRS 上下文实例。
+    /// </summary>
+    public static BenchmarkContext Instance { get; } = new();
+}

GFramework.Cqrs.Benchmarks/Messaging/BenchmarkDispatcherCacheHelper.cs

@@ -0,0 +1,49 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using System;
+using System.Reflection;
+
+namespace GFramework.Cqrs.Benchmarks.Messaging;
+
+/// <summary>
+///     提供 benchmark 共享的 dispatcher 静态缓存清理入口。
+/// </summary>
+/// <remarks>
+///     `GFramework.Cqrs` runtime 会把反射绑定与 generated invoker 元数据缓存在静态字段中。
+///     benchmark 需要在同一进程内重复比较 cold-start、reflection 与 generated 路径时，
+///     显式清空这些缓存，避免前一组 benchmark 污染后续结果。
+/// </remarks>
+internal static class BenchmarkDispatcherCacheHelper
+{
+    /// <summary>
+    ///     清空 dispatcher 上与 benchmark 对照相关的全部静态缓存。
+    /// </summary>
+    public static void ClearDispatcherCaches()
+    {
+        ClearDispatcherCache("NotificationDispatchBindings");
+        ClearDispatcherCache("RequestDispatchBindings");
+        ClearDispatcherCache("StreamDispatchBindings");
+        ClearDispatcherCache("GeneratedRequestInvokers");
+        ClearDispatcherCache("GeneratedStreamInvokers");
+    }
+
+    /// <summary>
+    ///     通过反射定位并清空 dispatcher 的指定缓存字段。
+    /// </summary>
+    /// <param name="fieldName">要清理的静态缓存字段名。</param>
+    /// <exception cref="InvalidOperationException">指定缓存字段不存在、返回空值或未暴露清理方法。</exception>
+    internal static void ClearDispatcherCache(string fieldName)
+    {
+        var field = typeof(GFramework.Cqrs.CqrsRuntimeFactory).Assembly
+            .GetType("GFramework.Cqrs.Internal.CqrsDispatcher", throwOnError: true)!
+            .GetField(fieldName, BindingFlags.NonPublic | BindingFlags.Static)
+            ?? throw new InvalidOperationException($"Missing dispatcher cache field {fieldName}.");
+        var cache = field.GetValue(null)
+                    ?? throw new InvalidOperationException($"Dispatcher cache field {fieldName} returned null.");
+        var clearMethod = cache.GetType().GetMethod("Clear", BindingFlags.Public | BindingFlags.Instance)
+                          ?? throw new InvalidOperationException(
+                              $"Dispatcher cache field {fieldName} does not expose a Clear method.");
+        _ = clearMethod.Invoke(cache, null);
+    }
+}

GFramework.Cqrs.Benchmarks/Messaging/Fixture.cs

@@ -0,0 +1,35 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using BenchmarkDotNet.Loggers;
+using System;
+
+namespace GFramework.Cqrs.Benchmarks.Messaging;
+
+/// <summary>
+///     为 CQRS benchmark 运行打印并验证当前场景配置，避免矩阵配置与实际运行环境漂移。
+/// </summary>
+internal static class Fixture
+{
+    /// <summary>
+    ///     输出当前 benchmark 配置并验证关键环境变量。
+    /// </summary>
+    /// <param name="scenario">当前 benchmark 场景名称。</param>
+    /// <param name="handlerCount">当前场景的处理器数量。</param>
+    /// <param name="pipelineCount">当前场景的 pipeline 行为数量。</param>
+    public static void Setup(string scenario, int handlerCount, int pipelineCount)
+    {
+        ConsoleLogger.Default.WriteLineHeader("GFramework.Cqrs benchmark config");
+        ConsoleLogger.Default.WriteLineInfo($"Scenario      = {scenario}");
+        ConsoleLogger.Default.WriteLineInfo($"HandlerCount  = {handlerCount}");
+        ConsoleLogger.Default.WriteLineInfo($"PipelineCount = {pipelineCount}");
+
+        var environmentScenario = Environment.GetEnvironmentVariable("GFRAMEWORK_CQRS_BENCHMARK_SCENARIO");
+        if (!string.IsNullOrWhiteSpace(environmentScenario) &&
+            !string.Equals(environmentScenario, scenario, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException(
+                $"Scenario mismatch. Expected '{environmentScenario}', actual '{scenario}'.");
+        }
+    }
+}

GFramework.Cqrs.Benchmarks/Messaging/GeneratedRequestInvokerBenchmarkRegistry.cs

@@ -0,0 +1,98 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Threading;
+using System.Threading.Tasks;
+using GFramework.Core.Abstractions.Logging;
+using GFramework.Cqrs.Abstractions.Cqrs;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace GFramework.Cqrs.Benchmarks.Messaging;
+
+/// <summary>
+///     为 benchmark 手写一个“生成后等价物” registry，用于驱动真实的 generated invoker provider 运行时接线路径。
+/// </summary>
+public sealed class GeneratedRequestInvokerBenchmarkRegistry :
+    GFramework.Cqrs.ICqrsHandlerRegistry,
+    GFramework.Cqrs.ICqrsRequestInvokerProvider,
+    GFramework.Cqrs.IEnumeratesCqrsRequestInvokerDescriptors
+{
+    private static readonly GFramework.Cqrs.CqrsRequestInvokerDescriptor Descriptor =
+        new(
+            typeof(IRequestHandler<
+                RequestInvokerBenchmarks.GeneratedBenchmarkRequest,
+                RequestInvokerBenchmarks.GeneratedBenchmarkResponse>),
+            typeof(GeneratedRequestInvokerBenchmarkRegistry).GetMethod(
+                nameof(InvokeGeneratedRequestHandler),
+                BindingFlags.Public | BindingFlags.Static)
+            ?? throw new InvalidOperationException("Missing generated request invoker benchmark method."));
+
+    private static readonly IReadOnlyList<GFramework.Cqrs.CqrsRequestInvokerDescriptorEntry> Descriptors =
+    [
+        new GFramework.Cqrs.CqrsRequestInvokerDescriptorEntry(
+            typeof(RequestInvokerBenchmarks.GeneratedBenchmarkRequest),
+            typeof(RequestInvokerBenchmarks.GeneratedBenchmarkResponse),
+            Descriptor)
+    ];
+
+    /// <summary>
+    ///     将 generated benchmark request handler 注册到目标服务集合。
+    /// </summary>
+    public void Register(IServiceCollection services, ILogger logger)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(logger);
+
+        services.AddTransient(
+            typeof(IRequestHandler<
+                RequestInvokerBenchmarks.GeneratedBenchmarkRequest,
+                RequestInvokerBenchmarks.GeneratedBenchmarkResponse>),
+            typeof(RequestInvokerBenchmarks.GeneratedBenchmarkRequestHandler));
+        logger.Debug("Registered generated request invoker benchmark handler.");
+    }
+
+    /// <summary>
+    ///     返回当前 provider 暴露的全部 generated request invoker 描述符。
+    /// </summary>
+    public IReadOnlyList<GFramework.Cqrs.CqrsRequestInvokerDescriptorEntry> GetDescriptors()
+    {
+        return Descriptors;
+    }
+
+    /// <summary>
+    ///     为目标请求/响应类型对返回 generated request invoker 描述符。
+    /// </summary>
+    public bool TryGetDescriptor(
+        Type requestType,
+        Type responseType,
+        out GFramework.Cqrs.CqrsRequestInvokerDescriptor? descriptor)
+    {
+        if (requestType == typeof(RequestInvokerBenchmarks.GeneratedBenchmarkRequest) &&
+            responseType == typeof(RequestInvokerBenchmarks.GeneratedBenchmarkResponse))
+        {
+            descriptor = Descriptor;
+            return true;
+        }
+
+        descriptor = null;
+        return false;
+    }
+
+    /// <summary>
+    ///     模拟 generated invoker provider 产出的开放静态调用入口。
+    /// </summary>
+    public static ValueTask<RequestInvokerBenchmarks.GeneratedBenchmarkResponse> InvokeGeneratedRequestHandler(
+        object handler,
+        object request,
+        CancellationToken cancellationToken)
+    {
+        var typedHandler = (IRequestHandler<
+            RequestInvokerBenchmarks.GeneratedBenchmarkRequest,
+            RequestInvokerBenchmarks.GeneratedBenchmarkResponse>)handler;
+        var typedRequest = (RequestInvokerBenchmarks.GeneratedBenchmarkRequest)request;
+        return typedHandler.Handle(typedRequest, cancellationToken);
+    }
+}