Bitzsoft.Integrations.Core 1.0.4

Bitzsoft.Integrations.Core

连接器平台公共核心，提供跨 net5.0、net8.0、net10.0 一致的 Provider 能力描述、目录、上下文路由和多租户凭据解析。

安装与兼容性

dotnet add package Bitzsoft.Integrations.Core

包同时支持 net5.0、net8.0 和 net10.0。Provider 包通常会传递引用 Core； 只有宿主直接使用目录、上下文或凭据抽象时才需要显式引用。

核心约定

• IntegrationProviderDescriptor 是能力、稳定度、API 版本与限制的代码事实源。
• 一个 Provider 只注册真实完成的细粒度能力。
• 多 Provider 消费通过 IIntegrationProviderResolver<TCapability> 显式按 providerId 解析。
• IContextualIntegrationProviderResolver<TCapability> 可按 region/environment 过滤；只有一个 候选时才允许自动选择，多个候选必须显式指定。
• IIntegrationContextAccessor 使用可嵌套的异步作用域传播 tenant/region/environment。
• IIntegrationCredentialResolver 是 Vault/KMS 扩展 seam；解析到的 IntegrationCredential 归调用方所有并必须释放。
• AddInMemoryIntegrationCredentials() 只在宿主明确选择时注册，不能误作默认生产 Vault。
• 直接注入单个能力接口仅作为单 Provider 兼容别名，不用于多租户或多厂商路由。
• net5.0 使用同一字典 resolver 语义；net8+ 同时注册大小写精确的原生 keyed service 兼容入口，但跨 TFM 业务仍应优先使用 resolver。

public sealed class CheckoutService(
    IIntegrationProviderResolver<IPaymentProvider> providers)
{
    public IPaymentProvider Resolve(string providerId)
        => providers.GetRequired(providerId);
}

services.AddBitzsoftIntegrationCore();
services.AddInMemoryIntegrationCredentials(); // 仅开发/测试或明确接受进程内驻留时

using (contextAccessor.Push(new IntegrationContext(
    tenantId: "tenant-a",
    region: "cn",
    environment: IntegrationEnvironments.Production)))
{
    var provider = contextualResolver.GetRequired(
        new IntegrationProviderSelection(providerId: "provider-a"));

    var key = IntegrationCredentialKey.FromContext(
        contextAccessor.Current!,
        "Payment:provider-a");
    using var credential = await credentialResolver.GetRequiredAsync(key);
    var apiKey = credential.GetRequiredSecret("ApiKey");
}

生产实现职责

• IIntegrationCredentialResolver：从 Vault/KMS 按完整 IntegrationCredentialKey 解析，并支持密钥轮换；
• IIntegrationContextAccessor：通过 Push 创建可嵌套作用域，作用域结束后必须释放；
• IIntegrationProviderResolver<TCapability>：多 Provider 场景始终显式指定 providerId；
• IContextualIntegrationProviderResolver<TCapability>：region/environment 是可信配置， 不能从未验签的请求正文推导；
• IIntegrationProviderCatalog：用于能力发现和支持矩阵，不替代运行时授权。

IntegrationCredential 使用可释放的内存载体；不要缓存、序列化、记录或放入普通 Options。 内存凭据 Store 不提供跨实例一致性、静态加密、审计或自动轮换，只适合测试和明确的 单进程开发。

错误与诊断

连接器应统一抛出 IntegrationException，使用 FailureKind、稳定 ErrorCode、 HTTP 状态、RetryAfter 和 OutcomeUnknown 表达机器可判定语义。异常消息与 ToString() 不得包含 secret、token、cursor 或供应商原始正文。调用方应优先按分类 决定重试、重新授权或人工处理，不能解析异常文本。