EF Core 8中JSON列实体类Schema变更的问题咨询

一、添加JSON嵌套属性时的兼容处理 #

问题原因 #

使用ToJson()映射的嵌套实体/集合时，EF Core会生成基于JSON路径的严格查询语句。当现有JSON数据缺少新添加的属性（如DeviceSettings）时，SQL Server会因找不到对应JSON节点抛出错误，且EF Core迁移无法自动更新JSON内部结构。

解决方案 #

1. 配置默认值，让查询兼容缺失属性
   在映射新集合属性时，通过HasDefaultValueSql指定默认空数组，确保查询时即使JSON中无该属性也能返回合法的默认值：

   builder.Entity<User>(b =>
   {
       b.ToTable("Users");
       b.HasKey(x => x.Id);
       b.OwnsOne(x => x.Settings, cfg =>
       {
           cfg.ToJson();
           cfg.WithOwner();
           cfg.OwnsMany(x => x.UiSettings, pcfg => pcfg.WithOwner());
           // 为新集合配置默认空数组
           cfg.OwnsMany(x => x.DeviceSettings, pcfg => 
           {
               pcfg.WithOwner();
               pcfg.Property(x => x.Name).HasDefaultValueSql("''");
               pcfg.Property(x => x.Value).HasDefaultValueSql("''");
           })
           .HasDefaultValueSql("'[]'");
       });
   });
   

2. 批量更新现有JSON数据（可选）
   若需要让现有数据也包含新属性，可编写迁移脚本批量更新JSON列：

   UPDATE Users
   SET Settings = JSON_MODIFY(Settings, '$.DeviceSettings', '[]')
   WHERE JSON_VALUE(Settings, '$.DeviceSettings') IS NULL;
   

二、移除JSON嵌套属性后的错误处理 #

问题原因 #

移除属性（如UiSettings）后，EF Core的模型元数据可能存在缓存，或查询时仍尝试解析JSON中残留的旧属性节点，导致集合解析时出现索引越界错误。

解决方案 #

1. 清除模型缓存并重启应用
   开发环境中EF Core可能缓存了旧的模型结构，重启应用可强制加载新的映射配置。

2. 批量清理JSON中的旧属性
   编写SQL脚本移除JSON中已废弃的属性节点，避免EF尝试解析无效数据：

   UPDATE Users
   SET Settings = JSON_MODIFY(Settings, '$.UiSettings', NULL)
   WHERE JSON_VALUE(Settings, '$.UiSettings') IS NOT NULL;
   

3. 使用自定义JSON序列化配置增强兼容性
   替代默认的ToJson()映射，通过ValueConverter配置自定义JsonSerializerOptions，设置忽略未知属性：

   builder.Entity<User>(b =>
   {
       b.ToTable("Users");
       b.HasKey(x => x.Id);
       // 使用自定义ValueConverter处理JSON序列化
       b.Property(x => x.Settings)
         .HasColumnType("json") // SQL Server可指定nvarchar(max)或json类型
         .HasConversion(
             v => JsonSerializer.Serialize(v, new JsonSerializerOptions { WriteIndented = true }),
             v => JsonSerializer.Deserialize<UserSettings>(v, new JsonSerializerOptions { IgnoreUnknownProperties = true })
         );
   });
   

   这种方式脱离了EF Core的owned entity严格映射，更灵活处理JSON结构变更。

内容的提问来源于stack exchange，提问作者Luka