EF Core 9 中 CosmosDB 对自定义值类型支持的变更解析

在 EF Core 与 CosmosDB 集成的使用场景中，许多开发者习惯将自定义结构体(struct)和特殊ID类型(如Ulid)直接作为实体属性使用。然而，从 EF Core 8 升级到 9 版本后，这一常见用法突然出现了兼容性问题，导致系统无法正常保存和加载这些类型的数据。

问题背景

在 EF Core 8 及更早版本中，CosmosDB 提供程序对值类型的处理相对宽松，允许开发者直接将自定义结构体作为实体属性使用。这种设计源于 CosmosDB 的文档型数据库特性——数据以 JSON 格式存储，理论上任何可序列化的类型都应该能够直接存储和读取。

典型的应用场景包括：

• 使用 Ulid 替代 Guid 作为主键类型
• 定义 DateTimeRange 等值对象来表示业务概念
• 在实体中包含复杂但不可变的数据结构

版本变更带来的影响

EF Core 9 对类型系统进行了更严格的约束，CosmosDB 提供程序现在只映射已知兼容的类型。这一变更是为了与其他数据库提供程序保持一致性，但却破坏了之前能够正常工作的代码。

受影响的主要情况包括：

1. 之前能自动序列化为字符串的 Ulid 类型现在需要显式配置值转换器
2. 自定义结构体属性需要明确配置为复杂类型(ComplexType)
3. 可为空的自定义结构体处理变得更加复杂

技术原理分析

这一变更背后的技术考量在于：

• 类型安全性：确保只有经过验证的类型才能被映射
• 行为一致性：使 CosmosDB 提供程序与其他关系型数据库提供程序保持相似的行为
• 可预测性：避免隐式的类型转换导致难以调试的问题

然而，这种严格性在文档型数据库场景下可能显得过度约束，因为 CosmosDB 本身对存储的 JSON 结构没有严格的模式要求。

解决方案与最佳实践

对于必须升级到 EF Core 9 的用户，目前有以下几种解决方案：

1. 自定义类型映射器(临时方案)

通过替换内置的类型映射服务，可以恢复对值类型的宽松处理：

public class ReplacementCosmosTypeMappingSource : CosmosTypeMappingSource
{
    protected override CoreTypeMapping? FindMapping(in TypeMappingInfo mappingInfo)
    {
        var mapping = base.FindMapping(mappingInfo);
        
        if (mapping is null && mappingInfo.ClrType?.IsValueType == true)
        {
            return new CosmosTypeMapping(mappingInfo.ClrType);
        }

        return mapping;
    }
}

// 在DbContext中配置
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.ReplaceService<ITypeMappingSource, ReplacementCosmosTypeMappingSource>();
}

2. 显式配置复杂类型

对于自定义结构体，可以明确标记为复杂类型：

modelBuilder.Entity<MyEntity>().ComplexProperty(e => e.MyStructProperty);

3. 使用值转换器(适用于简单类型)

对于像Ulid这样的类型，可以配置值转换器：

modelBuilder.Entity<MyEntity>()
    .Property(e => e.UlidId)
    .HasConversion(new UlidToStringConverter());

未来展望

EF Core 团队已经将完整的自定义序列化支持纳入规划，这将在未来的版本中提供更灵活的类型处理能力。在此之前，开发者需要根据实际情况选择上述临时解决方案。

对于新项目，建议在设计阶段就考虑类型映射的显式配置，避免依赖隐式行为。同时，对于复杂的值对象，可以考虑将其设计为类而不是结构体，这样可以更自然地适应EF Core的类型系统。

这一变更虽然带来了短期的适配成本，但从长远看有助于建立更健壮、更可预测的数据访问层，特别是在大型应用程序中。