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 使用上下文:多租户与身份基座 · 审计与操作日志 · 监听路由与消费完整性 · 主从读写分离 · 工作单元与消息面