Table of Contents

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 驱动项目/应用层

想深入