NexusContract.Core 1.0.0-preview.19

NexusContract.Core

引擎层 (Engine Layer) - 元数据驱动的高性能执行引擎

📦 这个包包含什么？

NexusContract 的核心执行引擎，实现运行期执行路径与元数据管理：

核心引擎

• NexusEngine - ISV 多租户调度引擎（实现 INexusEngine）

  • JIT 配置加载（通过 IConfigurationResolver）
  • Provider 路由（配置驱动）
  • 请求执行与异常处理

• NexusGateway - 三方网关唯一门面

  • 自动编排出入链路（投影 + 回填）
  • 纯异步设计（无同步版本）
  • 提供 ExecutionContext（物理化执行上下文）

元数据管理

• NexusContractMetadataRegistry - 契约元数据注册表

  • 启动期反射 + 验证 + 冷冻
  • 运行期 O(1) 查询（零反射）
  • 单例模式（全局唯一注册表）

• ContractMetadataCompiler - 元数据编译器

  • Expression Tree 预编译（Projector/Hydrator）
  • 生成零反射委托

• ContractValidator - 契约验证器

  • 启动期结构性检查（NXC1xx）
  • 运行期 Fail-Fast 验证

• ContractAuditor - 契约审计器

  • 属性审计（getter/setter 检查）
  • 生成 PropertyAuditResult

• CircularReferenceValidator - 循环引用检测器

  • 防止无限递归
  • 嵌套深度检查

• DiagnosticReport - 结构化诊断报告

  • 启动期错误汇总
  • 分级诊断（Error/Warning/Info）

投影与回填

• ProjectionEngine - 投影引擎

  • POCO → Dictionary（中间表示）
  • 支持嵌套、加密、命名策略
  • 使用预编译委托（零反射）

• ResponseHydrationEngine - 回填引擎

  • Dictionary → POCO（强类型响应）
  • 对称解密、类型转换
  • 精准错误定位（NXC3xx）

• ProjectionResult - 投影结果容器

  • 分离 Path/Query/Body 参数
  • 支持物理化执行

配置管理

• InMemoryConfigResolver - 内存配置解析器（实现 IConfigurationResolver）

  • 快速查询（Dictionary）
  • 支持运行时更新

• ProviderSettings - Provider 配置实现（实现 IProviderConfiguration）

  • AppId、私钥、网关地址等
  • 扩展配置支持

• ConfigurationContext - 配置上下文

  • 租户标识与 Provider 绑定

HTTP 构建器

• RequestUrlBuilder - URL 构建器

  • 占位符替换（Path 参数）
  • Query 参数拼接

• RequestPathRenderer - 路径渲染器

  • 点号路径 → URL 路径
  • 支持路径模板

• HeaderBuilder - HTTP 头构建器

  • 自动添加通用 Header

• EndpointRouteMetadata - 端点路由元数据

  • 提取路由参数
  • BFF 层路由支持

命名策略实现

• SnakeCaseNamingPolicy - 蛇形命名（snake_case）
• CamelCaseNamingPolicy - 驼峰命名（camelCase）
• PascalCaseNamingPolicy - 帕斯卡命名（PascalCase）

诊断与健康检查

• ContractStartupHealthCheck - 启动期健康检查
  • 扫描所有契约类型
  • 生成完整诊断报告
  • 支持 Fail-Fast 模式

工具类

• RobustConvert - 强力类型转换器

  • 处理 API 返回的类型混乱
  • 支持字符串 → 数值、布尔等

• TypeUtilities - 类型工具

  • 类型检查与推断
  • 泛型参数提取

• MethodInvokerCache - 方法调用缓存

  • 缓存 Validate/Normalize 方法
  • 零反射调用

🎯 适用场景

• ✅ 构建 Provider (如 AlipayProvider, UnionPayProvider)
• ✅ 实现 Gateway (投影/执行/回填管道)
• ✅ 启动期契约体检 (Preload + DiagnosticReport)

🚀 快速开始

安装

dotnet add package NexusContract.Core

启动期契约体检

using NexusContract.Core.Diagnostics;
using NexusContract.Core.Reflection;

// 方式 1：使用 ContractStartupHealthCheck（推荐）
var report = ContractStartupHealthCheck.Run(
    typeof(TradePayRequest).Assembly,  // 扫描契约所在程序集
    warmup: true                        // 预热：预编译 Projector/Hydrator
);

// 方式 2：手动调用 NexusContractMetadataRegistry
var registry = NexusContractMetadataRegistry.Instance;
var report = registry.Preload(
    new[] { typeof(TradePayRequest), typeof(TradeQueryRequest) },
    warmup: true
);

// 打印诊断报告
report.PrintToConsole(includeDetails: true);

if (report.HasErrors)
{
    Console.Error.WriteLine("❌ 检测到契约错误，中止启动。");
    Environment.Exit(1);
}

Console.WriteLine($"✅ 已预加载 {report.TotalTypes} 个契约类型");

示例2：直接使用 Provider（单租户模式）

如果你的场景不需要多租户动态配置，可以直接使用 Provider：

using NexusContract.Core;
using NexusContract.Core.Policies.Impl;
using NexusContract.Providers.Alipay;

// 1. 创建配置（包含网关地址）
var config = new AlipayProviderConfig
{
    AppId = "2021001234567890",
    MerchantId = "2088123456789012",
    PrivateKey = "MIIEvQIBA...",
    AlipayPublicKey = "MIIBIjANBg...",
    ApiGateway = new Uri("https://openapi.alipay.com"),  // ✅ 配置中包含网关地址
    UseSandbox = false
};

// 2. 创建 Gateway 和 Provider
var gateway = new NexusGateway(new SnakeCaseNamingPolicy());
var provider = new AlipayProvider(config, gateway, transport);

// 3. 执行请求（✅ 无需传入 URL，从配置和契约中推导）
var response = await provider.ExecuteAsync(
    new TradePayRequest { 
        MerchantOrderNo = "2024001",
        TotalAmount = 100.00m,
        Subject = "测试商品",
        Scene = "bar_code",
        AuthCode = "285015833990941919"
    },
    ct
);

// Provider 内部会：
// 1. 从配置获取 GatewayUrl: https://openapi.alipay.com
// 2. 从契约获取 OperationId: "alipay.trade.pay"
// 3. 转换为最终 URL: https://openapi.alipay.com/v3/alipay/trade/pay
// 4. 执行签名、HTTP 调用、验签、回填

示例3：使用 NexusEngine（多租户模式）

using NexusContract.Core.Engine;
using NexusContract.Core.Configuration;

// 1. 创建配置解析器
var configResolver = new InMemoryConfigResolver();

// 2. 添加租户配置（包含网关地址）
configResolver.AddConfiguration("Alipay", "tenant_001", new ProviderSettings(
    providerName: "Alipay",
    appId: "2021001234567890",
    merchantId: "2088123456789012",
    privateKey: "MIIEvQIBA...",
    publicKey: "MIIBIjANBg...",
    gatewayUrl: new Uri("https://openapi.alipay.com"),  // ✅ 配置中包含网关地址
    isSandbox: false
));

// 3. 创建引擎并注册 Provider
var engine = new NexusEngine(configResolver);
var alipayAdapter = new AlipayProviderAdapter(transport, gateway);
engine.RegisterProvider("Alipay", alipayAdapter);

// 4. 执行请求（✅ Engine 根据 providerName + profileId 查询配置）
var response = await engine.ExecuteAsync(
    new TradePayRequest { 
        MerchantOrderNo = "2024001",
        TotalAmount = 100.00m,
        Subject = "测试商品"
    },
    providerName: "Alipay",
    profileId: "tenant_001",  // 租户标识
    ct
);

// Engine 工作流：
// 1. 通过 configResolver 查询租户配置（tenant_001）
// 2. 获取配置中的 GatewayUrl: https://openapi.alipay.com
// 3. 委托给 AlipayProviderAdapter 执行
// 4. Adapter 根据配置动态创建 AlipayProvider 实例
// 5. 执行请求并返回响应

⚡ 性能特性

• 元数据冷冻: 启动期一次性反射，运行期 O(1) 查询（NexusContractMetadataRegistry）
• 预编译投影: Expression Tree 预编译 Projector/Hydrator，避免运行时反射
• 确定性 P99: GC 优化设计，平滑延迟曲线
• 零反射执行: 运行期使用预编译委托，无反射损耗
• 配置缓存: 支持 L1/L2 缓存，降低配置加载开销

🏛️ 执行路径（六阶段）

启动期（一次性）：
  0. Metadata Preload → 结构性验证（NXC1xx）+ 预编译（Projector/Hydrator）

运行期（每次请求）：
  Engine 入口：
    1. ResolveConfig  → IConfigurationResolver（JIT 加载配置）
    2. Validate       → IContractValidator（可选，业务验证）
    3. Normalize      → IContractNormalizer（可选，自愈修正）

  Gateway/Provider 执行：
    4. Project        → ProjectionEngine（POCO → Dictionary，零反射）
    5. Execute        → Provider/Transport（HTTP + 签名 + 发送）
    6. Hydrate        → ResponseHydrationEngine（Dictionary → POCO，零反射）

关键设计决策

1. Engine vs Gateway 职责分离

   • Engine：配置解析、Provider 路由、Validate/Normalize 执行
   • Gateway：投影/回填管道，由 Provider 调用

2. 双层验证机制

   • 启动期验证：元数据注册时的结构性检查（ContractValidator）
   • 运行期验证：业务逻辑验证（IContractValidator.Validate）

3. 零反射约束

   • 启动期预编译 Expression Tree（Projector/Hydrator）
   • 运行期调用预编译委托，无反射损耗
   • 未预加载的契约会触发 NXC504 异常

📚 文档

• 架构宪法 - 物理红线与设计禁忌
• 物理化执行架构 - Engine + Gateway 执行流程详解
• 启动期体检指南
• NXC 诊断码详解

🔗 相关包

• NexusContract.Abstractions - 基础抽象层（必需依赖，提供接口定义）
• NexusContract.Hosting - ASP.NET Core 托管层（Endpoint 路由）
• NexusContract.Hosting.Yarp - YARP 传输层（HTTP/2 + 连接池）
• NexusContract.Providers.Alipay - 支付宝 Provider 实现

📄 许可

MIT License - 查看 LICENSE