Table of Contents

SPI 扩展点

全部宿主供给缝与替换点:接口 / 职责 / 缺省实现 / 接入方式。 家族纪律:"缺省实现 + SPI 替换"——缺省走安全语义,升级靠整体替换,不留半吊子钩子。 上位:总览。

缝接口总表

SPI 职责 缺省行为 接入方式
ILoomAuditIdentity 身份缝——审计归因与租户值来源(已派生 ILoomIdentitySource) 审计记 system;租户写入显式拒绝 DI AddSingleton<ILoomAuditIdentity>;桥接形态 LoomAuditIdentityAdapter(mySource)
ILoomIdentitySource 身份来源(宿主自管会话/网关头/内部 SS) 缺省 = AsyncLocal 环境位(LoomIdentityScope.Run) DI AddSingleton<ILoomIdentitySource> 整体接管
ILoomIdGenerator ID 缝——雪花键赋值 未注册 = 显式异常(雪花键实体保存指路) DI AddSingleton<ILoomIdGenerator>(new LoomSnowflakeIdGenerator())
ILoomSecondLevelCache 二级缓存缝——查询结果缓存 + 前缀失效协议 loom.SecondLevelCache.Enabled = true(缺省)自动注册 LoomMemorySecondLevelCache(TTL/容量/前缀失效) DI 整体替换(Redis 等分布式实现);失效协议只要求 RemoveByPrefix(见查询一致性边界)
ILoomAuditTrailSink 审计外发落点 Outbox 宿主时缺省进 Outbox(Audit.OutboxDefault);否则无外发 loom.AddAuditTrailSink(sink)(提交门读选项不读 DI)
ILoomWatchFailureHandler watch 失败缝——失败事件载体交给业务 计数器 + 日志(行为兼容缺省) loom.Watch.FailureHandler = myHandler(选项注入)
LoomReadConnectionStringProvider(抽象类) 从库连串解析——Produce() 产出候选串序列 四档内置:Fixed/RoundRobin/Weighted/Failover 继承实现 Produce()(动态源场景);故障转移横切在路由器层自动生效
ILoomOutboxStore outbox 存储租借 loom.Outbox = true 自动注册(Scoped/Factory 自动选型) 一般不替换;确需替换须理解租借形态(反模式见messaging)
ILoomOutboxDelivery outbox 投递策略(外部 MQ/HTTP/任意通道接管点) 无内置传输——消费层供 DI AddSingleton<ILoomOutboxDelivery, MyDelivery>
ILoomInbox inbox 幂等占位 loom.Inbox = true 自动注册 一般不替换
ILoomSeedProvider 种子提供者([EfSeed] 标注收集) 无种子 = 空目录 实现类打 [EfSeed(Order, Version)] 即被编译期收集
ILoomUnitOfWork / ILoomUowFactory / ILoomUowParticipant / ILoomUowOutbox UoW 边界族 AddLoomUow 装配 参与者 = 上下文挂能力根接口(泛型形态编不过即拦截)
ILoomDbContext 上下文壳声明(能力根) 生成物补 LoomDbContext 基类 上下文实现该接口,其余生成
ILoomChangeSink 变更收集挂钩(提交门 Capture 段) 框架内审计/watch 消费 框架扩展位——业务一般不触碰
ILoomEfDescriptorSource / ILoomEfModelSource 生成描述符/模型的供给源(测试与工具注入位) 生成物注册表 高级面——工具链/测试用

查询面缝(Query.Runtime 契约,EF 表达式绑定)

SPI 职责 缺省
IDictionaryValueTranslator 字典编码字段翻译(显示名→存储码) 未注册 = 类型驱动字面量转换
IDataScopeProvider 数据范围缝——动态条件自动 AndAlso,范围永不被绕过 未注册 = 无范围附加

缺省安全语义(缝未注册时)

缝缺失 行为 为什么不是反方向
身份缝未注册 审计记 system;租户写入显式异常;租户查询空匹配 静默看全量/静默写入 = 泄露与污染方向
ID 缝未注册 雪花键实体保存显式异常 静默全 0 键 = 数据损坏
审计 sink 未注册 Outbox 宿主缺省进 Outbox;非宿主无外发(计数器可见) 丢审计不炸业务(增强面故障隔离)

替换纪律

  • 整体替换:SPI 缺省实现可被宿主实现整体替换(外部 DI Replace 同效)——不做特性开关式半替换。
  • 选项注入 vs DI 注入:loom.* 选项对象上的 SPI 属性(FailureHandler/TrailSink)走选项(提交门读选项不读 DI);无状态服务型 SPI(Delivery/IdentitySource)走 DI。
  • 横切免费:自实现连串解析自动获得故障转移横切(横切在路由器层);自实现 watch 失败处理不改变重试/超时语义(缝在派发口收敛后)。

反模式

症状 为什么错 正确形态
手写 AddSingleton<ILoomOutboxStore> 绕过租借选型——根容器解析 scoped = 捕获依赖必炸 loom.Outbox = true 自动注册
想给 watch 失败处理加"开关"而不换实现 失败缝语义单一——分支进业务实现 实现 ILoomWatchFailureHandler 自己分支
自定义 ID 生成器绕过时钟回拨守卫 静默续发 = 重复键不可接受 继承 LoomSnowflakeIdGeneratorBase 保留守卫,只覆盖 ResolveWorkerId

想深入

各主题页的 SPI 使用上下文:多租户与身份基座 · 审计与操作日志 · 监听路由与消费完整性 · 主从读写分离 · 工作单元与消息面