NexusContract.Abstractions 1.0.0-preview.19

NexusContract.Abstractions

宪法层 (Constitution Layer) - 纯净的契约抽象与边界定义

📦 这个包包含什么？

这是 NexusContract 框架的基础依赖层，包含：

契约核心 (Contract Core)

• IApiRequest<TResponse> - 强类型请求/响应绑定，编译期类型安全
• IApiRequest - 非泛型标记接口，用于运行时类型检查
• IContractValidator - 契约级别验证钩子（可选），用于特殊的业务验证逻辑
• IContractNormalizer - 自愈钩子（可选），在投影前修正契约状态
• EmptyResponse - 空响应类型，用于 OneWay 交互模式

标注属性 (Annotations)

• [ApiOperation] - 声明操作元数据

  • Operation: 操作ID（如 "alipay.trade.pay"）
  • Verb: HTTP 动词（GET/POST/PUT/DELETE）
  • Interaction: 交互模式（RequestResponse/OneWay）

• [ApiField] - 字段级映射，精确控制投影行为

  • Name: 协议字段名（显式锁定，优先于命名策略）
  • IsRequired: 必填字段标记（运行期触发 NXC201）
  • IsEncrypted: 加密字段标记（必须同时指定 Name）
  • Behavior: 投影行为（Default / IgnoreIfNull）
  • Source: 字段绑定源（RouteParam / Path / Query / Body / Header）
  • Flatten: 平铺容器标记（与 Name 互斥）
  • Order: 字段序号（用于签名排序）

枚举类型

• EmitBehavior - 投影行为控制

  • Default: null 值映射到字典（值为 null）
  • IgnoreIfNull: null 值导致键物理消失

• FieldSource - 字段绑定源

  • Auto: 自动推断（GET→Query，POST→Body）
  • RouteParam: BFF 层路由参数（如 {profileId}）
  • Path: 第三方 API 路径占位符（如 /shop/{shopId}）
  • Query: 强制放入 URL 查询参数
  • Body: 强制放入请求体
  • Header: 放入 HTTP 头

• InteractionKind - 交互模式

  • RequestResponse: 请求-响应模式（同步）
  • OneWay: 单向模式（异步通知）

• HttpVerb - HTTP 动词枚举（GET/POST/PUT/DELETE/PATCH）

Provider 抽象层

• IProvider - Provider 接口（无状态单例）

  • ProviderName: Provider 标识
  • ExecuteAsync<TResponse>(): 执行请求（投影→签名→发送→回填）

• IProviderConfiguration - Provider 配置抽象（只读视图）

  • AppId, MerchantId: 应用标识
  • PrivateKey, PublicKey: 密钥对
  • GatewayUrl: 网关地址
  • IsSandbox: 沙箱标识
  • GetExtendedSetting<T>(): 扩展配置访问

• IConfigurationResolver - 配置解析器（JIT 模式，支持 L1/L2 缓存）

  • ResolveAsync(): 解析配置（精确匹配，O(1)）
  • RefreshAsync(): 刷新缓存
  • WarmupAsync(): 预热缓存

安全抽象

• IEncryptor - 加密器接口（用于敏感字段加密）
• IDecryptor - 解密器接口（用于响应解密）
• ISecretProtector - 敏感数据保护器（保护/恢复机密信息）
  • Protect(): 保护敏感数据（加密）
  • Unprotect(): 恢复敏感数据（解密）
  • 用途: 保护私钥、AppSecret 等敏感配置（AES256-CBC + Base64）

传输抽象

• INexusTransport - 传输层接口（Egress HTTP/2 传输抽象）
  • SendAsync(): 发送 HTTP 请求
  • PostAsync(): POST 便捷方法
  • GetAsync(): GET 便捷方法
  • WarmupAsync(): 预热 HTTP/2 连接（生产环境推荐）
  • GetHostMetrics(): 获取主机性能指标
  • 职责: 高性能 HTTP/2 连接池、自动重试、熔断器、负载均衡
  • 实现: YarpTransport（NexusContract.Hosting.Yarp 包）

策略抽象

• INamingPolicy - 命名策略（字段名转换）
  • 用于隐式字段的命名推导（SnakeCase/CamelCase/PascalCase）

诊断体系

• ContractDiagnosticRegistry - 结构化错误码体系（NXC1xx-5xx）
• NxcErrorEnvelope - 标准错误信封（Code, Message, Data）
• ContractIncompleteException - 契约不完整异常（携带 NXC 码）
• NexusGuard - 参数校验守护（单一实现，统一入口）

边界配置

• ContractBoundaries - 物理红线配置
  • MaxNestingDepth: 最大嵌套深度（默认 3）
  • MaxCollectionSize: 最大集合大小
  • 循环引用检测

核心引擎抽象

• INexusEngine - Nexus 引擎接口（物理寻址网关的调度大脑）
  • ExecuteAsync<TResponse>(): 执行请求（自动调度到对应 Provider）
  • 职责: Provider 路由、JIT 配置加载、Validate → Normalize 执行流程
  • 物理寻址: 显式 providerName + profileId 参数（从 URL 路由提取）
  • 实现: NexusEngine（NexusContract.Core 包）

🎯 适用场景

• ✅ 定义业务契约 (Contract POCO)
• ✅ 多 Provider 共享 (Alipay, UnionPay, WeChat, Allinpay)
• ✅ 跨 .NET 版本兼容 (netstandard2.0)

🚀 快速开始

安装

dotnet add package NexusContract.Abstractions

示例 1：基础契约定义

using NexusContract.Abstractions.Attributes;
using NexusContract.Abstractions.Contracts;

[ApiOperation("alipay.trade.pay", HttpVerb.POST)]
public class TradePayRequest : IApiRequest<TradePayResponse>
{
    [ApiField("out_trade_no", IsRequired = true)]
    public string MerchantOrderNo { get; set; }
    
    [ApiField("total_amount", IsRequired = true)]
    public decimal TotalAmount { get; set; }
    
    // 加密字段（必须显式指定 Name）
    [ApiField("card_no", IsEncrypted = true)]
    public string CardNo { get; set; }
}

public class TradePayResponse
{
    [ApiField("trade_no")]
    public string TradeNo { get; set; }
    
    [ApiField("trade_status")]
    public string TradeStatus { get; set; }
}

示例 2：自愈钩子（IContractNormalizer）

[ApiOperation("alipay.trade.pay", HttpVerb.POST)]
public class TradePayRequest : IApiRequest<TradePayResponse>, IContractNormalizer
{
    [ApiField("merchant_id", IsRequired = true)]
    public string MerchantId { get; set; }

    [ApiField("enterprise_pay_amount", Behavior = EmitBehavior.IgnoreIfNull)]
    public decimal? EnterprisePayAmount { get; set; }

    public void Normalize()
    {
        // 某些商户不支持企业支付，清除该字段
        if (string.IsNullOrEmpty(MerchantId) || !MerchantId.StartsWith("2088"))
            EnterprisePayAmount = null;
    }
}

示例 3：契约验证钩子（IContractValidator）

[ApiOperation("alipay.trade.pay", HttpVerb.POST)]
public class TradePayRequest : IApiRequest<TradePayResponse>, IContractValidator
{
    [ApiField("total_amount")]
    public decimal TotalAmount { get; set; }
    
    [ApiField("discount_amount", Behavior = EmitBehavior.IgnoreIfNull)]
    public decimal? DiscountAmount { get; set; }

    public void Validate()
    {
        // 业务规则：折扣金额不能超过总金额
        if (DiscountAmount.HasValue && DiscountAmount.Value > TotalAmount)
        {
            throw new ContractIncompleteException("NXC201", "折扣金额不能超过总金额");
        }
    }
}

🔒 关键约束与最佳实践

1. 加密字段必须显式命名（红线 NXC106）

// ✗ 错误：加密字段未指定 Name（启动期抛出 NXC106）
[ApiField(IsEncrypted = true)]
public string CardNo { get; set; }

// ✓ 正确：显式指定 Name
[ApiField("card_no", IsEncrypted = true)]
public string CardNo { get; set; }

2. 平铺容器禁止指定 Name（红线 NXC311）

// ✗ 错误：平铺容器不能指定 Name
[ApiField("buyer", Flatten = true)]
public BuyerInfo Buyer { get; set; }

// ✓ 正确：只标记 Flatten
[ApiField(Flatten = true)]
public BuyerInfo Buyer { get; set; }

3. 必填字段运行期拦截（NXC201）

// 当 MerchantId 被标注为 IsRequired 且为 null 时（运行期投影抛出 NXC201）
[ApiField("merchant_id", IsRequired = true)]
public string MerchantId { get; set; }

建议：在构造请求对象时填充所有必填字段，或在实现 Normalize() 时补齐缺失值。

4. 嵌套对象必须显式命名（红线 NXC107）

// 嵌套深度 ≥ 2 时，必须显式标注 [ApiField]
[ApiField("buyer_info")]
public BuyerInfo Buyer { get; set; }

5. EmitBehavior 使用场景

• Default：绝大多数 API（null 值映射到字典，值为 null）
• IgnoreIfNull：特殊 API（如支付宝某些接口要求字段"物理消失"）

// 支付宝特殊接口：字段存在（即使为 null）会被拒绝
[ApiField("enterprise_pay_amount", Behavior = EmitBehavior.IgnoreIfNull)]
public decimal? EnterprisePayAmount { get; set; }

🏛️ 设计哲学

"显式边界优于隐式魔法"

• 零运行时依赖: 不依赖任何第三方包
• 纯净抽象: 只有接口和 Attribute，无行为实现
• 架构约束: 通过诊断码 (NXC1xx) 强制执行设计边界
• 编译期类型安全: 强类型绑定，避免运行期类型错误
• Provider 隔离: 每个 Provider 独立配置，互不干扰

📚 文档

• 架构宪法 - 物理红线与设计禁忌（执行流程、验证机制请参考此文档）
• 逻辑深度对齐 - 点号路径规则与唯一性检查
• 物理对齐参考 - 架构诊断与平铺容器规则
• NXC 诊断码详解

💡 关于双层验证、执行流程、零反射约束等运行期行为：
这些属于 NexusContract.Core 层的职责，请参考 架构宪法 或 Core 模块的文档。
本包（Abstractions）只提供接口定义（如 IContractValidator、IContractNormalizer），不涉及具体的执行逻辑。

🔗 相关包

• NexusContract.Core - 核心引擎实现（执行流程、验证、投影、回填）
• NexusContract.Providers.Alipay - 支付宝 Provider 实现

📄 许可

MIT License - 查看 LICENSE