ComplexType 与 JSON
值对象与动态载荷的两种存储形态怎么选、怎么声明;JSON 查询三层定位与护栏。 上位:总览。
场景分界:多列 vs JSON(类型确定性)
[EfComplexType] 多列 |
[EfJson] JSON 列 |
|
|---|---|---|
| 类型确定性 | 确定——编译期已知成员集 | 动态/不确定——结构运行时才定 |
| 生命周期 | 复用值对象——跨实体统一冗余(Address/Money/Period 几表重复) | 单实体私有载荷、纯透传 |
| 使用意图 | 高效查询面(列存储/可索引/规则过滤/审计逐成员) | 免迁移演进、Schema-free |
| 声明 | 类型级 [EfComplex](自动收集——复用主形态)+ 属性级 [EfComplexType](单点) |
属性级 [EfJson] |
| 列名 | 缺省 属性名_成员名 前缀 + [EfComplexType(Prefix=)] 显式覆盖 |
JSON 文档内自描述 |
| 一致性 | KLSG:同 [EfComplex] 类型跨属主成员配置不一致 = Error(冗余不漂移——编译期 Schema 兜底) | Schema-free |
| 值语义推荐 | record 不可变、整对象替换(推荐不强制) |
— |
| 共存 | ComplexType 主体 + [EfJson] 扩展载荷字段——同实体合法 |
同左 |
决策:要过滤/排序/索引/逐成员审计的复用值对象 → 多列形态;免迁移的动态载荷透传 → JSON 列。集合形态(List<Address>)EF8 ComplexType 不支持 = KLSG 指路用 [EfJson] 承载。
声明与发射
[EfComplex] // 类型级:标量成员自动收集 + 查询字段目录自动派生
public sealed record Address(string Province, string City, string Street);
[EfEntity(typeof(OrderCtx))]
public sealed class Order
{
[EfComplexType(Prefix = "ship_addr")] // 属性级:单点声明(与类型级二选一按需)
public Address ShippingAddress { get; set; } = ...;
[EfJson] // 扩展载荷——同实体共存合法
public string? Extensions { get; set; }
}
- 发射
ComplexProperty(x => x.ShippingAddress, cb => {...});嵌套类型内属性走约定档(长度/UTC/枚举存储统一生效);嵌套套嵌套深度上限 4。 - 诊断:ComplexType 属性标
[EfKey](复杂类型无键——Error);集合形态 = KLSG 指路;与[EfJson]同属性双标 = KLSG 互斥。 - AOT 面:ComplexProperty 为 typed API——冻结模型原生兼容(optimize 自检为准)。
审计深账
复杂类型成员展开进审计标量清单(地址.城市 逐成员——Snapshot/AuditedMembers 编译期物化),操作日志深账逐字段可见;[EfAuditIgnore] 支持成员级豁免(规则复用)——见审计与操作日志。
JSON 查询三层
| 层 | 内容 | 归属 |
|---|---|---|
| L1 简单直译(内置承诺) | 基础点路径谓词(eq/ne/gt/lt/contains/in)直译 provider 原生 JSON 函数(SqlServer JSON_VALUE / Sqlite json_extract / Npgsql jsonb)——EF 翻译面内零自研;复杂度守卫复用(MaxDepth/MaxConditions) | Loom.Ef |
L2 内存表达式树模式(显式 opt-in:[FilterField(Mode = Memory)]) |
复杂条件不在 SQL 直译——DB 端粗筛(可翻译部分)+ 内存精筛(表达式树委托求值)+ 内存排序分页;护栏:MaxScanRows(缺省 1000,超限 Throw 指路)+ loom_ef_query_memory_total 命中观测 |
Loom.Ef |
| L3 深度驱动扩展(后置独立项目,触发制) | 原生 JSON 函数 SQL 直译(SqlServer OPENJSON/PG jsonb 操作符/表达式索引引导)——loom.ef.sqlserver/loom.ef.pgjson 驱动包 |
驱动项目 |
显式声明不做自动降级(同规则跨环境行为一致);L2 下排序分页同为内存执行;Mode 标注进 Schema(消费端可见能力边界)。
L2 求值内核
完全基于 System.Text.Json(BCL 内建——零第三方):
- 双内核:①CLR 对象图内核——owned POCO/复杂类型属性,表达式树成员访问链直构(编译期类型已知零反射);②JsonElement 内核——动态 JSON string 列,
JsonDocument.Parse+ JPath 子集求值器(属性导航/数组索引/通配首匹配/等值过滤首匹配——语法子集闭集,完整 JSONPath 不做)+ 类型化求值(InvariantCulture 换型)。 - 诚实语义:畸形 JSON 行 = 未命中(不抛不炸查询)。
- 性能:
JsonDocument逐行 Parse(总量受 MaxScanRows 护栏约束)+ 池化复用;JsonElement 结构体遍历零分配优先。 - AOT:表达式树 JIT = 预编译委托缓存;AOT = 解释求值(自研小表达式解释器,节点面 = 规则操作符面,闭集可控)。
选择指引闭环
重过滤成员应选多列形态(全 provider 一致 + 可索引)——JSON 路径过滤定位 = 轻量补充,不是重过滤载体。字段目录侧的联动:[EfComplex] 类型嵌套标量成员编译期自动进 FilterField 目录与 Schema/补全(查询规则引擎);显式 [FilterField] 亦可声明 JSON 路径字段;未标 [EfComplex] 的对象成员进目录 = KLSG112 带点路径指路。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 复杂类型属性上标 [EfJson] | ComplexType(表内展开)与 owned JSON(独立 JSON 列)互斥 | 二选一——KLSG 指路 |
| JSON 路径过滤超 MaxScanRows 被 Throw | 内存模式护栏——防全表拉内存 | 重过滤成员改用多列形态([EfComplexType])或等驱动扩展 |
| 同一 [EfComplex] 类型在两个实体里成员配置不同 | 冗余漂移——同类型跨属主不一致 = KLSG Error | 一处定义处处一致(这正是编译期 Schema 兜底的价值) |
| 把高频查询字段塞进 JSON | JSON 过滤不可索引(L3 前)且按 provider 翻译能力受限 | 查询面字段升级为真实列/多列形态 |
| 依赖 JPath 完整语法(递归下降等) | 求值器是子集闭集(导航/索引/通配/等值过滤) | 超子集的文档查询归 L3 驱动项目/应用层 |