Bitzsoft.Integrations.OData 1.0.0-alpha.10

Bitzsoft.Integrations.OData

面向多租户 ToB 集成的 OData v2.0、v4.0 与 v4.01 协议层。它复用 Bitzsoft.Integrations.Rest 的固定 origin/base-path、认证、凭据隔离和安全错误模型， 并可把 v4 delta feed 接入 Bitzsoft.Integrations.Sync。

安装与兼容性

dotnet add package Bitzsoft.Integrations.OData

包同时支持 net5.0、net8.0 和 net10.0。宿主还必须提供 IIntegrationCredentialResolver 的生产实现；连接器不会隐式启用进程内明文凭据。

已实现能力

• 类型化 entity/key/navigation/property/operation 路径；
• v2/v4 的 $filter、$select、$expand、$orderby、$top、$skip；
• v2 $inlinecount、verbose JSON d.results/__next/__count 和版本头；
• v4 $count、$search、$apply、$compute、parameter alias；
• OData-Version 协商、JSON metadata/streaming/IEEE754 参数；
• ETag、条件请求、Prefer return、track-changes 和 max page size；
• 受 origin 与 service-root 约束的不透明 nextLink/deltaLink；
• multipart/mixed $batch 与 atomic changeset；
• metadata、batch、普通响应的 streaming/full-body API；
• v4 delta feed 到 Sync Engine 的 page source、tombstone 与 410 Gone 失效语义。

本包是通用协议层，不提供 SAP、Dynamics 等厂商的业务对象模型，也不允许通过 continuation URL 绕过配置的服务根。

注册与认证

下面以 OAuth 2.0 Client Credentials 为例。不同认证方式的凭据字段沿用 Bitzsoft.Integrations.Rest：Bearer、Basic、API Key、OAuth2、mTLS 与 HMAC 都由 RestEndpoint 和宿主凭据解析器共同决定。

var endpoint = new ODataEndpoint(
    new RestEndpoint(
        new Uri("https://erp.example.com/odata/"),
        RestAuthenticationMode.OAuth2ClientCredentials,
        oauthTokenEndpoint: new Uri("https://identity.example.com/oauth/token"),
        oauthScopes: new[] { "erp.read" }),
    maxProtocolVersion: ODataProtocolVersion.V4_01,
    metadataLevel: ODataMetadataLevel.Minimal,
    defaultPageSize: 200);

services.AddBitzsoftOData(
    endpoint,
    new[]
    {
        new ODataSyncProfile(
            streamName: "Customers",
            resourcePath: ODataResourcePath.EntitySet("Customers"),
            idProperty: "Id",
            revisionProperty: "@odata.etag")
    });

端点或同步配置随租户变化时，实现 IODataEndpointResolver 与 IODataSyncProfileResolver，使用 AddBitzsoftOData<TEndpointResolver, TSyncProfileResolver>()。

查询与分页

var context = new ODataRequestContext(
    tenantId: "customer-a",
    profileId: "production",
    region: "cn",
    credentialName: "erp-read");

var page = await client.QueryAsync(
    context,
    ODataResourcePath.EntitySet("Customers"),
    new ODataQuery(
        filter: "Status eq 'Active'",
        select: new[] { "Id", "Name", "Status" },
        orderBy: new[] { "Id asc" },
        top: 200),
    trackChanges: true,
    cancellationToken: cancellationToken);

while (page.NextLink is not null)
{
    page = await client.ReadContinuationAsync(
        context,
        page.NextLink,
        cancellationToken: cancellationToken);
}

ODataCursor 是短期、不透明且绑定端点的 continuation。不得持久化或解析其内容； 长期恢复应交给 Sync Engine 保存自己的 SyncCursor。

原始响应由 ODataResponse 持有，调用方必须 Dispose/DisposeAsync。 调用方传入的请求流仍归调用方所有。

写入、并发与批处理

通用写请求使用 ODataRequest。更新和删除应带服务端返回的 ETag，通过 IfMatch 防止丢失更新；只有供应商明确支持幂等键时才设置 IdempotencyKey。 multipart changeset 只提供协议原子分组，不代表网络失败后可以安全重试。

ExecuteBatchAsync 返回原始 multipart 响应，调用方负责按目标服务契约解释各 operation 的业务结果。本包当前不实现 JSON batch。

同步语义

通用 ODataSyncPageSource 只声明 v4 deltaLink：

• continuation 仅用于当前运行翻页，最终 deltaLink 才成为已提交水位；
• 删除条目转换为 tombstone；
• 410 Gone 表示 delta 已过期，任务必须重新 Full；
• profile 可要求最终响应必须包含 deltaLink；
• Sink 必须按记录 ID 与 revision 幂等。

OData v2 没有可安全泛化的 delta 协议。SAP 等厂商必须在专用 Provider 中定义稳定排序、 闭合水位、删除语义，以及 CSRF/session 生命周期。

安全、日志与故障处理

• endpoint 必须使用 HTTPS；仅显式配置的 loopback 开发端点可使用 HTTP；
• continuation/delta URL 不得跨 scheme、host、port 或配置的 base path；
• cursor、凭据和供应商错误正文不会进入异常或 ToString()；
• token/凭据交换禁止记录正文，普通业务正文默认完整记录且不强制限长；
• 协议层不会自动重试可能已生效的写操作；
• IntegrationException.FailureKind、状态码、稳定错误码和 RetryAfter 用于宿主决策；
• 所有异步 API 接受 CancellationToken，取消不会改写成供应商失败。

首次接入每个厂商和版本时，应在 sandbox 验证 metadata、分页、ETag、batch、 delta 保留期、限流头和错误格式，不能仅凭“OData 兼容”推断生产契约。