Galosys.Foundation.Castle.Core 26.9.16.1

Galosys.Foundation.Castle.Core

成熟度: 🟢 稳定 — 生产可用，测试充分，活跃维护

基于 Castle.DynamicProxy 的 AOP 拦截模块。核心设计理念：

• 原生 Castle 集成 — 直接使用 Castle 的 IInterceptor / IInvocation / ProxyGenerator
• 继承式拦截 — 拦截器特性继承 InterceptorAttribute 覆写 InterceptAsync，无需独立 Handler 类
• 单一适配器 — InterceptorAdapter 一个 IInterceptor 实现，自动发现方法上的所有 InterceptorAttribute 子类并执行链式分派

架构概览

用户代码 → [MyAttribute] 标记 → DI 自动代理注册 → Castle 生成代理 → 方法调用 → InterceptorAdapter.Intercept() → GetCustomAttributes<InterceptorAttribute>() → MyAttribute.InterceptAsync() → invocation.Proceed() → 业务方法

┌─ Service 层 ─────────────────────────────────────────────┐
│  [Transactional]                                          │
│  public class OrderService {                              │
│      public virtual async Task CreateAsync() { ... }      │
│  }                                                         │
└──────────────────────────┬───────────────────────────────┘
                           │ DI 注入（Castle 自动代理）
                           ▼
┌─ Castle 代理 ────────────────────────────────────────────┐
│  ProxyGenerator.CreateClassProxy / CreateInterfaceProxy   │
│  → InterceptorAdapter.Intercept()                         │
│    → GetCustomAttributes<InterceptorAttribute>()          │
│    → TransactionalAttribute.InterceptAsync(invocation, sp)│
│      → invocation.ProceedAsync()                           │
└──────────────────────────────────────────────────────────┘

安装

dotnet add package Galosys.Foundation.Castle.Core

定义拦截器

继承 InterceptorAttribute 并覆写 InterceptAsync 方法：

using Castle.DynamicProxy;

public class AuditLogAttribute : InterceptorAttribute
{
    public override async ValueTask InterceptAsync(IAsyncInvocation invocation, IServiceProvider sp)
    {
        Console.WriteLine($"[Audit] 调用: {invocation.Invocation.Method.Name}");
        await invocation.ProceedAsync();
        Console.WriteLine($"[Audit] 返回: {invocation.Result}");
    }
}

public class PaymentService
{
    [AuditLog]
    public virtual async Task PayAsync(decimal amount)
    {
        await Task.CompletedTask;
    }
}

InterceptorAttribute 自动处理同步 void / Task / ValueTask / Task<T> / ValueTask<T> 所有返回类型。

内置拦截器

[Transactional] — 事务管理（Castle.DynamicProxy）

[Transactional]
public virtual async Task CreateOrderAsync(Order order) { }

[Transactional(IsolationLevel = IsolationLevel.Serializable, Timeout = 30000)]
public virtual void ProcessPayment(Payment payment) { }

[Retryable] — 重试策略（扩展拦截器，物理归属 Galosys.Foundation.Polly.Core）

物理归属：自 v2026.09 起，RetryableAttribute 从 Galosys.Foundation.Castle.Core 迁至 Galosys.Foundation.Polly.Core（依赖反转）。namespace Castle.DynamicProxy 保留，源码 using Castle.DynamicProxy; 仍可编译。运行时使用 [Retryable] 必须额外引用 Galosys.Foundation.Polly.Core，否则解析到 Core NoOp，重试无效果。

[Retryable]
public virtual async Task<string> CallApiAsync() { }

[Retryable(MaxAttempts = 5, MaxDelay = 10000, Multiplier = 2)]
public virtual async Task<Data> FetchDataAsync() { }

[Retryable(RetryFor = typeof(HttpRequestException))]
public virtual async Task<Response> ResilientCallAsync() { }

API 演进：上述 MaxAttempts / MaxDelay / Multiplier / RetryFor 参数已标记 [Obsolete]，重试参数应统一在 services.AddResilienceCore(RetryableAttribute.PipelineName, b => b.WithRetry(...)) 中配置，然后 services.AddPollyResilience() 覆盖 NoOp。[Retryable] 拦截器仅作为命名管道的入口，不再直接持有 Polly 配置。

// 注册命名弹性管道
builder.Services.AddResilienceCore(RetryableAttribute.PipelineName, b => b.WithRetry(new RetryOptions
{
    MaxRetries = 5,
    Delay = TimeSpan.FromSeconds(1),
    BackoffType = BackoffType.Exponential,
}));
builder.Services.AddPollyResilience(); // 覆盖 NoOp，启用 Polly 真实实现

模块化宿主无需手动注册：引 Galosys.Foundation.Polly.Core 后 PollyCoreModule 自动注入默认 retry 命名管道 + AddPollyResilience()。详细管道配置见 Galosys.Foundation.Polly.Core 的弹性管道实现。

注册方式

方式一：自动注册（推荐）

// Program.cs
builder.Host.UseCastleCoreServiceProvider();

内部自动执行 services.ConfigureCastleDynamicProxy()，将所有标注了 InterceptorAttribute 子类的服务实现替换为 Castle 代理。

方式二：手动注册

// 需在所有服务注册完成后调用
builder.Services.ConfigureCastleDynamicProxy();

接口代理 vs 类代理

类代理限制：非 virtual 的 public 方法静默跳过代理（不拦截、无提示）。启动时 ConfigureCastleDynamicProxy 会对非虚方法输出 Trace 警告。

异步支持

InterceptorAdapter 统一处理 5 种返回类型：

拦截器链

多个 Attribute 叠加时，按方法上的声明顺序执行（从外到内）。

// 执行顺序：1) Transactional → 2) Retryable
[Transactional]
[Retryable]
public virtual async Task ComplexOperationAsync()
{
    // 业务方法在最内层执行
}

核心类参考

测试覆盖

集成测试位于 framework/test/Galosys.Foundation.Castle.Core.Tests/，涵盖：

• ConfigureCastleDynamicProxy — ProxyGenerator 单例注册、三种注册方式的代理替换（ImplementationType / Instance / Factory）
• 生命周期保留 — Singleton / Scoped / Transient 在代理替换后行为不变
• 代理类型 — 接口代理（ITestService）、类代理（TestClassService）
• 拦截器链 — 多 Attribute 叠加执行
• 异步支持 — void / Task / Task<T> / ValueTask / ValueTask<T>
• CastleCoreServiceProviderFactory — IHostBuilder 集成链路

运行测试：

dotnet test framework/test/Galosys.Foundation.Castle.Core.Tests/

性能基线

BenchmarkDotNet v0.13.12 / .NET 10.0.1 / RyuJIT AVX2（framework/test/Galosys.Foundation.Castle.Core.Benchmarks/）

注意事项

• 虚方法：类代理必须 virtual，否则拦截静默跳过
• 注册顺序：ConfigureCastleDynamicProxy 必须在所有服务注册之后调用（替换式注册）
• ValidateScopes：UseCastleCoreServiceProvider() 默认启用；若代理的 Singleton 服务依赖 Scoped 构造参数，会抛出 InvalidOperationException，包含具体提示
• 拦截器嵌套：拦截器内不要创建新代理
• AOT：Castle.Core 基于 Emit，Native AOT 不可用

依赖

• Castle.Core 5.1.1
• Galosys.Foundation.Core