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

.github/workflows/benchmark.yml

@@ -0,0 +1,71 @@
+# Copyright (c) 2025-2026 GeWuYou
+# SPDX-License-Identifier: Apache-2.0
+
+name: Benchmark
+
+on:
+  workflow_dispatch:
+    inputs:
+      benchmark_filter:
+        description: '可选的 BenchmarkDotNet 过滤器；留空时仅执行 benchmark 项目 Release build'
+        required: false
+        default: ''
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: Benchmark Build Or Run
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Cache NuGet packages
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.nuget/packages
+            ~/.local/share/NuGet
+          key: ${{ runner.os }}-nuget-benchmarks-${{ hashFiles('GFramework.Cqrs.Benchmarks/*.csproj', 'GFramework.Cqrs/*.csproj', 'GFramework.Cqrs.Abstractions/*.csproj', 'GFramework.Core/*.csproj', 'GFramework.Core.Abstractions/*.csproj', '**/nuget.config') }}
+
+      - name: Restore benchmark project
+        run: dotnet restore GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj
+
+      - name: Build benchmark project
+        run: dotnet build GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release --no-restore
+
+      - name: Report build-only mode
+        if: ${{ inputs.benchmark_filter == '' }}
+        run: |
+          echo "No benchmark filter provided."
+          echo "Workflow completed after validating the benchmark project build."
+
+      - name: Run filtered benchmarks
+        if: ${{ inputs.benchmark_filter != '' }}
+        env:
+          BENCHMARK_FILTER: ${{ inputs.benchmark_filter }}
+        run: |
+          set -euo pipefail
+          dotnet run --project GFramework.Cqrs.Benchmarks/GFramework.Cqrs.Benchmarks.csproj -c Release --no-build -- \
+            --filter "$BENCHMARK_FILTER"
+
+      - name: Upload BenchmarkDotNet artifacts
+        if: ${{ always() && inputs.benchmark_filter != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-artifacts
+          path: |
+            BenchmarkDotNet.Artifacts/**
+            GFramework.Cqrs.Benchmarks/bin/Release/net10.0/BenchmarkDotNet.Artifacts/**
+          if-no-files-found: ignore

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/BenchmarkHostFactory.cs

@@ -0,0 +1,93 @@
+// Copyright (c) 2025-2026 GeWuYou
+// SPDX-License-Identifier: Apache-2.0
+
+using System;
+using System.Linq;
+using GFramework.Core.Ioc;
+using GFramework.Cqrs.Abstractions.Cqrs;
+using MediatR;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace GFramework.Cqrs.Benchmarks.Messaging;
+
+/// <summary>
+///     为 benchmark 场景构建最小且可重复的 GFramework / MediatR 对照宿主。
+/// </summary>
+/// <remarks>
+///     基准工程里的对照目标是“相同消息合同下的调度差异”，而不是程序集扫描量或容器生命周期差异。
+///     因此这里统一封装两类宿主的最小注册形状，确保：
+///     1. GFramework 容器在首次发送前已经冻结，可真实解析按类型注册的 handler；
+///     2. MediatR 只扫描当前 benchmark 明确拥有的 handler / behavior 类型，避免整个程序集的额外注册污染结果。
+/// </remarks>
+internal static class BenchmarkHostFactory
+{
+    /// <summary>
+    ///     创建一个已经冻结的 GFramework benchmark 容器。
+    /// </summary>
+    /// <param name="configure">向容器写入 benchmark 所需 handler / pipeline 的注册动作。</param>
+    /// <returns>已冻结、可立即用于 runtime 分发的容器。</returns>
+    internal static MicrosoftDiContainer CreateFrozenGFrameworkContainer(Action<MicrosoftDiContainer> configure)
+    {
+        ArgumentNullException.ThrowIfNull(configure);
+
+        var container = new MicrosoftDiContainer();
+        configure(container);
+        container.Freeze();
+        return container;
+    }
+
+    /// <summary>
+    ///     创建只承载当前 benchmark handler 集合的最小 MediatR 宿主。
+    /// </summary>
+    /// <param name="configure">补充当前场景的显式服务注册，例如手工单例 handler 或 pipeline 行为。</param>
+    /// <param name="handlerAssemblyMarkerType">用于限定扫描程序集的标记类型。</param>
+    /// <param name="handlerTypeFilter">
+    ///     仅允许当前 benchmark 场景需要的 handler / behavior 类型通过扫描；
+    ///     这样可保留 `AddMediatR` 的正常装配路径，同时避免整个基准程序集里的其他 handler 被一并注册。
+    /// </param>
+    /// <param name="lifetime">当前 benchmark 希望 MediatR 使用的默认注册生命周期。</param>
+    /// <returns>只承载当前 benchmark 场景所需服务的 DI 宿主。</returns>
+    internal static ServiceProvider CreateMediatRServiceProvider(
+        Action<IServiceCollection>? configure,
+        Type handlerAssemblyMarkerType,
+        Func<Type, bool> handlerTypeFilter,
+        ServiceLifetime lifetime = ServiceLifetime.Transient)
+    {
+        ArgumentNullException.ThrowIfNull(handlerAssemblyMarkerType);
+        ArgumentNullException.ThrowIfNull(handlerTypeFilter);
+
+        var services = new ServiceCollection();
+        services.AddLogging(static builder =>
+            Microsoft.Extensions.Logging.FilterLoggingBuilderExtensions.AddFilter(
+                builder,
+                "LuckyPennySoftware.MediatR.License",
+                Microsoft.Extensions.Logging.LogLevel.None));
+
+        configure?.Invoke(services);
+
+        services.AddMediatR(options =>
+        {
+            options.Lifetime = lifetime;
+            options.TypeEvaluator = handlerTypeFilter;
+            options.RegisterServicesFromAssembly(handlerAssemblyMarkerType.Assembly);
+        });
+
+        return services.BuildServiceProvider();
+    }
+
+    /// <summary>
+    ///     判断某个类型是否正好实现了指定的闭合或开放 MediatR 合同。
+    /// </summary>
+    /// <param name="candidateType">待判断类型。</param>
+    /// <param name="openGenericContract">目标开放泛型合同，例如 <see cref="MediatR.IRequestHandler{TRequest,TResponse}" />。</param>
+    /// <returns>命中任一实现接口时返回 <see langword="true" />；否则返回 <see langword="false" />。</returns>
+    internal static bool ImplementsOpenGenericContract(Type candidateType, Type openGenericContract)
+    {
+        ArgumentNullException.ThrowIfNull(candidateType);
+        ArgumentNullException.ThrowIfNull(openGenericContract);
+
+        return candidateType.GetInterfaces().Any(interfaceType =>
+            interfaceType.IsGenericType &&
+            interfaceType.GetGenericTypeDefinition() == openGenericContract);
+    }
+}

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}'.");
+        }
+    }
+}