EF Core 9 中 Cosmos DB 文档 ID 包含竖线字符的查询问题解析

问题背景

在 EF Core 9 版本中，当使用 Cosmos DB 提供程序时，如果文档 ID 包含竖线字符（"|"），会出现查询失败的情况。这个问题在 EF Core 8 及更早版本中并不存在，是 EF Core 9 引入的一个行为变更。

问题表现

当应用程序尝试查询 ID 中包含竖线字符的文档时，EF Core 9 会在内部将查询的 ID 值进行修改，自动插入一个脱字符（"^"），导致查询无法找到正确的文档。例如：

• 应用程序查询 ID 为 "Cat|1" 的文档
• EF Core 9 实际发送给 Cosmos DB 的查询 ID 变为 "Cat^|1"
• 结果导致查询返回空结果

技术原因

这个问题的根源在于 EF Core 9 对 Cosmos DB 文档 ID 生成机制的变更。在 EF Core 9 中，团队对键值生成方式进行了重构，以简化 ID 属性处理。新的实现默认不再将鉴别器（Discriminator）值包含在 ID 中，而是直接使用实体键值。

然而，在处理包含特殊字符（特别是竖线字符）的 ID 时，新的键值生成逻辑会错误地插入额外的转义字符，导致查询失败。

解决方案

对于遇到此问题的开发者，EF Core 团队提供了明确的解决方案：

1. 使用兼容模式：通过在模型构建器中调用 HasDiscriminatorInJsonIds 方法，可以恢复 EF Core 8 及更早版本的行为。

modelBuilder.HasDiscriminatorInJsonIds();

2. 避免在 ID 中使用特殊字符：虽然 Cosmos DB 技术上允许使用竖线字符，但官方文档建议仅使用字母数字字符作为 ID，这可以避免各种潜在问题。

深入分析

值得注意的是，这个问题只影响查询操作，不影响数据插入。文档保存时，ID 值会按应用程序指定的原样存储。问题仅出现在 EF Core 生成查询条件时对 ID 值的处理上。

对于复合键的情况，问题可能更加复杂。例如，当使用 FindAsync 方法并同时指定 ID 和分区键时，如果两者都包含竖线字符，同样会出现查询失败的情况。此时，虽然原始 SQL 查询可以正常工作，但通过 EF Core 的 API 却无法获取正确结果。

最佳实践建议

1. 如果必须升级到 EF Core 9 且无法修改现有 ID 格式，应立即应用 HasDiscriminatorInJsonIds 解决方案
2. 在新项目中，遵循 Cosmos DB 的最佳实践，使用简单的字母数字 ID
3. 对于关键业务逻辑，考虑添加额外的查询验证，确保查询条件与发送到数据库的实际值一致
4. 在升级前，针对包含特殊字符 ID 的文档进行全面测试

总结

EF Core 9 对 Cosmos DB 的 ID 处理逻辑进行了优化，但在处理特殊字符时引入了兼容性问题。开发者需要了解这一变更，并根据实际情况选择合适的解决方案。这个问题再次提醒我们，在数据库设计中遵循官方建议的重要性，以及在升级 ORM 框架时进行全面测试的必要性。