Bitzsoft.Integrations.Rest 1.0.0-alpha.10

Bitzsoft.Integrations.Rest

通用 REST 传输默认不截断请求或响应正文。OAuth Token 等整段均为凭据的交换， 可在构造 RestRequest 时显式设置 第二个参数 suppressRequestAndResponseBodiesFromLogging: true；该设置只影响审计日志， 不会修改或限制实际 HTTP 正文。

面向国内与国际 ToB 系统集成的通用 REST/Webhook transport，目标框架为 net5.0;net8.0;net10.0。它负责可复用的传输、安全和分页语义，不用弱类型字典 伪装 ERP、CRM 或其他厂商业务模型。

安装

dotnet add package Bitzsoft.Integrations.Rest

它是连接器内部安全传输底座，不是允许业务层拼接任意 URL、Header 和重试策略的 通用 HTTP 替代品。

已实现

• 固定 HTTPS origin 与 base path，默认禁止自动重定向和 Cookie；
• API Key Header、Basic、Bearer、OAuth2 Client Credentials 与 RFC 7523 JWT Bearer assertion；
• OAuth token 按租户/profile/环境/凭据隔离、并发 single-flight、提前刷新和密钥轮换识别；
• 每租户 PFX 客户端证书及短生命周期 mTLS handler；
• HMAC-SHA256 出站签名、幂等键、关联 ID 和默认 Header；
• ResponseHeadersRead 流式响应，以及完整 byte/string 读取；
• RFC Link: <...>; rel="next" 分页与不透明 continuation cursor；
• 复用 Webhook Gateway 的 HMAC 验签、防重放、Inbox、重试和 DLQ。

响应正文不设置隐式大小上限，也不会截断。调用方可流式消费，或显式读取完整正文。 宿主的 RequestLogging 默认同样应保留完整正文；大小限制只能由宿主明确选择启用。 OAuth token 请求与响应整段都属于凭据，transport 会逐请求显式抑制其日志正文； 这不改变普通业务 API 大正文的完整记录策略。

注册

services.AddVaultCredentialResolver(); // 宿主实现 IIntegrationCredentialResolver
services.AddBitzsoftRest(
    new RestEndpoint(
        new Uri("https://partner.example.com/api/v2/"),
        authenticationMode: RestAuthenticationMode.OAuth2ClientCredentials,
        oauthTokenEndpoint: new Uri("https://partner.example.com/oauth/token"),
        oauthScopes: new[] { "orders.read", "orders.write" }),
    webhook =>
    {
        webhook.SignatureHeaderName = "X-Partner-Signature";
        webhook.TimestampHeaderName = "X-Partner-Timestamp";
        webhook.DeliveryIdHeaderName = "X-Partner-Delivery";
    });

不同租户或区域使用不同端点时，实现 IRestEndpointResolver：

services.AddBitzsoftRest<TenantRestEndpointResolver>();

JWT Bearer 服务账号

需要 Google Workspace 等服务账号授权时：

services.AddBitzsoftRest(
    new RestEndpoint(
        new Uri("https://admin.googleapis.com/admin/directory/v1/"),
        authenticationMode: RestAuthenticationMode.OAuth2JwtBearer,
        oauthTokenEndpoint: new Uri("https://oauth2.googleapis.com/token"),
        oauthScopes: new[]
        {
            "https://www.googleapis.com/auth/admin.directory.user.readonly"
        }));

凭据解析器按租户提供：

• OAuthJwtIssuer：服务账号 email / JWT iss；
• OAuthJwtPrivateKey：PKCS#8 PEM RSA 私钥；
• OAuthJwtKeyId：可选 JWT kid；
• OAuthJwtSubject：可选委托用户 / JWT sub。

assertion 使用 RS256，aud 默认精确绑定 token endpoint，生命周期最大一小时。 私钥通过 IntegrationCredential.UseSecret 直接导入临时 RSA 实例，不写入 ToString()、异常或日志。若供应商字段名不同，可用 RestOAuthJwtBearerOptions 显式映射。域级委派等必须包含 sub 的场景应设置 requireSubject: true，缺少委托主体时会在发送 token 请求前失败。

调用

var context = new RestRequestContext(
    tenantId: "customer-a",
    profileId: "orders",
    region: "cn",
    environment: IntegrationEnvironments.Production,
    credentialName: "partner-api");

await using var response = await client.SendAsync(
    context,
    new RestRequest(
        HttpMethod.Get,
        "orders",
        query: new[]
        {
            new KeyValuePair<string, string>("updatedAfter", watermark)
        }),
    cancellationToken: cancellationToken);

await using var body = await response.OpenBodyStreamAsync(cancellationToken);

有请求正文时，输入流归调用方所有，客户端不会释放。HMAC 对可 seek 流计算摘要后会恢复 原 position；非 seek 流必须由调用方传入预先计算的 bodySha256。服务端状态异常只包含 状态码、request id、重试提示和安全分类，不复制可能含敏感信息的大正文。

Webhook

注册方法会把 Rest:standard 的 HMAC verifier 加入 Webhook resolver。宿主仍需明确选择 生产级 IWebhookReplayStore 与 IWebhookInboxStore；进程内实现只用于开发和测试。 验签 secret 默认字段为 WebhookSecret，出站签名 secret 默认字段为 RequestSigningSecret，两者可独立轮换。

边界

• 内置 OAuth 覆盖 client-credentials 与 RFC 7523 JWT Bearer；授权码、 设备码和 refresh-token 生命周期应由宿主身份层管理。
• 内置分页只解释 RFC Link。JSON body cursor、offset/page-number 和 OData nextLink 由相应 typed adapter 实现。
• mTLS PFX 以 Base64 存入凭据解析器；生产环境应连接 Vault/KMS，并约束证书导出、轮换和审计。
• 此包不声明厂商资源 schema、速率配额或业务幂等规则；正式接入仍需 Certification sandbox 契约。