foundatio

Foundatio

Foundatio 提供可插拔的基础设施抽象。使用 context7 MCP 获取完整文档。

文档： 使用 context7 获取最新的 Foundatio API 文档和示例。

核心抽象

接口	用途	内存中	生产环境
ICacheClient	分布式缓存	InMemoryCacheClient	Redis
IQueue<T>	消息队列	InMemoryQueue<T>	Redis/SQS
IMessageBus	发布/订阅消息	InMemoryMessageBus	Redis
IFileStorage	文件存储	InMemoryFileStorage	S3/Azure
ILockProvider	分布式锁	InMemoryLockProvider	Redis
IResiliencePolicyProvider	重试/熔断	不适用	基于 Polly

ICacheClient

var result = await _cache.GetAsync<int>(key);
int value = result.HasValue ? result.Value : 0;

await _cache.IncrementAsync(key, count);
await _cache.ListAddAsync(setKey, organizationId);

IQueue<T>

await _queue.EnqueueAsync(new EventPost { OrganizationId = orgId, ProjectId = projectId, FilePath = path });

IMessageBus

// Subscribe
await _subscriber.SubscribeAsync<EntityChanged>(OnEntityChangedAsync, shutdownToken);

// Publish
await _messagePublisher.PublishAsync(new EntityChanged
{
    ChangeType = ChangeType.Saved, Type = nameof(Organization), Id = organization.Id
});

作业

QueueJobBase — 队列处理

[Job(Description = "Processes queued events.", InitialDelay = "2s")]
public class EventPostsJob : QueueJobBase<EventPost>
{
    public EventPostsJob(IQueue<EventPost> queue, TimeProvider timeProvider,
        IResiliencePolicyProvider resiliencePolicyProvider, ILoggerFactory loggerFactory)
        : base(queue, timeProvider, resiliencePolicyProvider, loggerFactory)
    {
        AutoComplete = false;
    }

    protected override async Task<JobResult> ProcessQueueEntryAsync(QueueEntryContext<EventPost> context)
    {
        var entry = context.QueueEntry;
        // Process the event...
        await entry.CompleteAsync();
        return JobResult.Success;
    }
}

IJob — 定时作业

[Job(Description = "Deletes old data.", InitialDelay = "1m", Interval = "1h")]
public class CleanupDataJob : IJob
{
    public async Task<JobResult> RunAsync(CancellationToken cancellationToken = default) { ... }
}

作业特性

特性	用途	示例
Description	作业描述	—
InitialDelay	首次运行前的延迟	"2s"
Interval	运行频率	"5m"
IterationLimit	运行 N 次后停止	1
IsContinuous	持续运行	true

弹性与可靠性

• 预期会发生故障：网络调用可能失败、资源可能耗尽、并发访问可能发生竞争
• 处处设置超时：绝不无限期等待；使用取消令牌
• 带退避的重试：针对瞬时故障使用带抖动的指数退避
• 优雅降级：在适当情况下返回缓存数据、默认值或部分结果
• 幂等性：设计可安全重试的操作
• 资源限制：限制队列、缓存和缓冲区的大小，以防内存耗尽

队列条目：调用 AbandonAsync() 进行重试，调用 CompleteAsync() 完成处理。不要重试验证错误——它们永远不会成功。