EF Core 9.0中处理JSON嵌套实体映射的异常分析与解决方案

问题现象

在使用EF Core 9.0.1版本时，开发者在尝试插入或更新包含JSON属性的实体时遇到了System.ArgumentNullException: Value cannot be null. (Parameter 'key')异常。这种情况通常发生在实体模型中包含多层嵌套的JSON映射配置时。

技术背景

EF Core从某个版本开始支持将复杂类型映射到数据库的JSON列，这是通过ToJson()方法实现的。这种映射方式允许我们将.NET对象直接序列化为JSON存储到数据库中，非常适合处理半结构化数据。然而，在嵌套使用这种映射时存在一些特殊限制。

问题根源

经过分析，这个异常的根本原因是开发者在配置嵌套的JSON映射时，对每一层嵌套都调用了ToJson()方法。实际上，EF Core要求只有最外层的实体需要调用ToJson()，内层的嵌套实体应该保持默认配置。

解决方案

正确的配置方式应该是：

modelBuilder.Entity<Entity>(entity =>
{
    entity.ToTable("Entities");
    entity.HasKey(e => e.Id);

    entity.OwnsMany(e => e.L1OwnedEntities, ownedNavigationBuilder =>
    {
        ownedNavigationBuilder.ToJson(); // 只有这一层调用ToJson()

        ownedNavigationBuilder.OwnsMany(e => e.L2OwnedEntities, foundValuesOwnedNavigationBuilder =>
        {
            // 内层不再调用ToJson()
            foundValuesOwnedNavigationBuilder.OwnsMany(e => e.Values, valuesOwnedNavigationBuilder =>
            {
                // 最内层也不调用ToJson()
            });
        });
    });
});

技术原理

EF Core在处理JSON映射时，会将整个对象图视为一个单一的JSON文档。如果在多层嵌套中都调用ToJson()，会导致EF Core无法正确构建更新命令，从而引发空键异常。这是因为EF Core期望所有嵌套实体都属于同一个JSON文档结构。

版本演进

值得注意的是，在EF Core 10中已经增加了相关验证，当检测到这种错误配置时会抛出明确的错误信息："Entity 'EntityValue' is mapped to JSON column 'Values', but its owner 'OwnedEntityLevel2' is mapped to a different JSON column 'L2OwnedEntities'. All owned entities must be mapped to the same JSON column. Only call '.ToJson()' on the outermost owned entity type."

最佳实践

1. 对于JSON映射，只在最外层的实体配置中调用ToJson()
2. 内层的嵌套实体保持默认配置
3. 将整个嵌套结构视为一个单一的JSON文档
4. 升级到EF Core 10可以获得更好的错误提示

总结

EF Core的JSON映射功能虽然强大，但在使用时需要注意其配置规则。理解"整个嵌套结构属于同一个JSON文档"这一概念非常重要。通过遵循正确的配置方式，可以避免这类异常，并充分利用JSON存储的优势来处理复杂的数据结构。