XiHan.Framework.ObjectStorage.Abstractions 5.0.0-preview.1

XiHan.Framework.ObjectStorage.Abstractions

对象存储契约（Ring 2，RFC-0012）。能力 objectstorage.blob@1 由 Provider 提供；默认实现 ObjectStorage.FileSystem。

var put = await store.PutAsync("invoices", "2026/10/inv-1.pdf", stream, new BlobPutOptions { ContentType = "application/pdf" }, ct);
var page = await store.ListAsync("invoices", new BlobQuery { Prefix = "2026/10/", PageSize = 100 }, ct);
var deleted = await store.DeleteAsync("invoices", [key1, key2], ct);   // 逐项结果：存在过 / 不存在 / 失败

实例不存在 → OBJECTSTORAGE_NOTFOUND_003；实例定义不合法 → OBJECTSTORAGE_VALIDATION_003；缺省存储的能力选择不一致（装配时）→ OBJECTSTORAGE_VALIDATION_004；不存在 → OBJECTSTORAGE_NOTFOUND_001；已存在且不覆盖 → OBJECTSTORAGE_CONFLICT_001；IO 失败 → OBJECTSTORAGE_UNAVAILABLE_001；配额 → OBJECTSTORAGE_UNAVAILABLE_002；范围不可满足 → OBJECTSTORAGE_VALIDATION_001；分片清单不合法 → OBJECTSTORAGE_VALIDATION_002；列举的页大小不在 1～1000（不在构造 BlobQuery 时抛出，Provider 经 BlobQuery.Validate() 返回）→ OBJECTSTORAGE_VALIDATION_005；上传不存在 → OBJECTSTORAGE_NOTFOUND_002；签名无效或过期 → OBJECTSTORAGE_DENIED_001；不覆盖写入在本存储上无法保证（S3 服务不认条件写入，或存储关闭了条件写入）→ OBJECTSTORAGE_UNAVAILABLE_003；不覆盖写入暂不可用（S3 是否认条件写入尚未确认，后台在重试）→ OBJECTSTORAGE_UNAVAILABLE_004；条件写入探测被拒绝 → OBJECTSTORAGE_DENIED_002（ADR-0089、ADR-0090、ADR-0093）。不覆盖写入必须原子：并发的不覆盖写入同一个新键只有一个成功。Provider 建命名实例时的探测发现实例不能用（S3 探明服务不认条件写入、探测被拒绝或探测桶不存在）时抛出携带错误码的 FrameworkException，注册表转成同码的失败结果、不登记实例。

// 断点续传：服务端发起，客户端按片直传，服务端完成
var upload = (await multipart.StartAsync("videos", key, new BlobPutOptions { ContentType = "video/mp4" }, ct)).ValueOrThrow();
var partUrl = (await signer.SignAsync("videos", key, BlobUrlRequest.ForPart(upload, 1), ct)).ValueOrThrow();
var done = await multipart.CompleteAsync(upload, parts, ct);
// 限时下载链接（缺省 30 分钟）
var link = (await signer.SignAsync("invoices", key, BlobUrlRequest.ForDownload(downloadFileName: "发票.pdf"), ct)).ValueOrThrow().Url;

// 命名实例：定义来自应用自己的库（存储配置），改了就替换
var definition = new BlobStoreDefinition("tenant-42-oss", "s3", new Dictionary<string, string>
{
    ["ServiceUrl"] = "https://oss-cn-hangzhou.aliyuncs.com", ["AccessKey"] = accessKey, ["SecretKey"] = secretKey,
});
var store = (await stores.GetOrAddAsync(definition, ct)).ValueOrThrow();
var archive = (await stores.GetAsync("archive", ct)).ValueOrThrow();   // XiHan:ObjectStorage:Stores:archive 定义的

依赖方向

依赖 XiHan.Framework.Kernel、XiHan.Framework.Localization.Abstractions、Microsoft.Extensions.Configuration.Abstractions 与 Microsoft.Extensions.DependencyInjection.Abstractions。被 ObjectStorage.FileSystem、ObjectStorage.S3、ObjectStorage.Conformance 与 Hosting.AspNetCore 引用。

状态

P3：可用。