EF Core与Terraform配置匹配仍遇CosmosDB PartitionKey错误

问题背景 #

在ASP.NET Core应用中使用EF Core操作CosmosDB，将Post类的Slug属性设为分区键，但保存Post对象时出现分区键不匹配错误。

相关代码 #

Post实体类 #

public partial class Post 
{
    public string Id { get; set; }

    [Key]
    public string Slug { get; set; }

    [Required]
    [MaxLength(100)]
    public string Title { get; set; }

    [Required]
    [MaxLength(100)]
    public string Subtitle { get; set; }

    public string Markdown { get; set; }

    [Required]
    [MaxLength(50)]
    public string Author { get; set; }

    [DataMember(Name = "created_at")]
    [JsonPropertyName("created_at")]
    public DateTime? CreatedAt { get; set; }

    [DataMember(Name = "updated_at")]
    [JsonPropertyName("updated_at")]
    public DateTime? UpdatedAt { get; set; }
}

创建Post的代码 #

public async Task<Post> CreatePostAsync(PostInput postInput)
{
    PostInputValidator.CheckPostInputRequiredFields(postInput);

    Post post = new()
    {
        Id = Guid.NewGuid().ToString(),
        Slug = Guid.NewGuid().ToString() + "-" + postInput.Title.ToLower().Replace(" ", "-") + "-" + postInput.Author.ToLower(),
        Title = postInput.Title,
        Subtitle = postInput.Subtitle,
        Author = postInput.Author,
        Markdown = postInput.Markdown,
        CreatedAt = DateTime.UtcNow
    };

    _context.Posts.Add(post);

    await _context.SaveChangesAsync();

    return post;
}

DbContext配置 #

public class BlogContext : DbContext, IBlogContext
{
    public BlogContext(DbContextOptions<BlogContext> options)
        : base(options)
    {
    }

    public DbSet<Post> Posts { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Post>().ToContainer("Posts"); 
        modelBuilder.Entity<Post>().HasPartitionKey(p => p.Slug);
        modelBuilder.Entity<Post>().HasNoDiscriminator();
    }
}

Terraform CosmosDB配置 #

resource "azurerm_cosmosdb_account" "gt_cosmosdb" {
  name                = "gt-cosmosdb"
  location            = azurerm_resource_group.gt_rg.location
  resource_group_name = azurerm_resource_group.gt_rg.name
  offer_type          = "Standard"
  kind                = "GlobalDocumentDB"
  enable_free_tier    = true
  consistency_policy {
    consistency_level = "Session"
  }
  geo_location {
    location          = azurerm_resource_group.gt_rg.location
    failover_priority = 0
  }
}

resource "azurerm_cosmosdb_sql_database" "gt_database" {
  name                = "gt-db"
  resource_group_name = azurerm_cosmosdb_account.gt_cosmosdb.resource_group_name
  account_name        = azurerm_cosmosdb_account.gt_cosmosdb.name
}

resource "azurerm_cosmosdb_sql_container" "gt_container" {
  name                = "Posts"
  resource_group_name = azurerm_cosmosdb_account.gt_cosmosdb.resource_group_name
  account_name        = azurerm_cosmosdb_account.gt_cosmosdb.name
  database_name       = azurerm_cosmosdb_sql_database.gt_database.name
  partition_key_path  = "/slug"
  throughput          = 400
}

错误信息 #

PartitionKey extracted from document doesn't match the one specified in the header.

已尝试的解决方法 #

• 在EF Core和CosmosDB中将分区键设为Id
• 生成Id为GUID并调用ToString()
• 将分区键类型在string和int间切换
• 改回使用/slug作为分区键

疑问 #

1. 导致文档中提取的分区键与请求头中指定的分区键不匹配的原因是什么？
2. 生成或设置分区键的方式是否存在问题？
3. Terraform中的分区键配置是否存在问题？

解答 #

1. 分区键不匹配的核心原因 #

EF Core Cosmos提供程序默认会将实体属性名转换为驼峰命名，同时[Key]特性会强制将属性映射到Cosmos的id字段。你的Post类中Slug标记了[Key]，导致EF Core将其映射到Cosmos的id字段，而你手动设置的Id属性会被序列化为额外字段；同时Slug未指定序列化名称，默认会变成slug（小驼峰），但EF Core在请求头中传递的分区键值基于属性名Slug的逻辑，和Cosmos从文档中提取的slug字段值产生映射冲突，最终导致不匹配。

2. 分区键生成/设置的问题 #

• [Key]特性误用：EF Core Cosmos中[Key]标记的属性会映射到Cosmos的id字段，你同时保留Id和带[Key]的Slug，导致文档标识逻辑混乱，干扰分区键的传递。
• 序列化名称不统一：Slug未指定[JsonPropertyName("slug")]，默认序列化后字段名为slug，但EF Core传递分区键时的逻辑和该字段名未正确关联，导致Cosmos提取的分区键值和请求头不一致。

3. Terraform配置的问题 #

Terraform中的partition_key_path = "/slug"配置本身是正确的，问题不在Terraform，而是实体类的EF Core映射规则和序列化逻辑与该配置不匹配导致的。

修复方案 #

方案1：修正实体类映射与序列化 #

1. 移除Slug上的[Key]特性，明确指定Id映射到Cosmos的id字段，同时给Slug指定序列化名称：

public partial class Post 
{
    [JsonPropertyName("id")]
    public string Id { get; set; }

    [JsonPropertyName("slug")]
    public string Slug { get; set; }

    // 其他属性保持不变
}

2. 保持DbContext配置不变，确保HasPartitionKey指向Slug属性：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Post>().ToContainer("Posts"); 
    modelBuilder.Entity<Post>().HasPartitionKey(p => p.Slug);
    modelBuilder.Entity<Post>().HasNoDiscriminator();
}

方案2：统一分区键与Cosmos id（可选） #

如果希望Slug同时作为文档标识和分区键，可以移除单独的Id属性，将Slug设为[Key]：

public partial class Post 
{
    [Key]
    [JsonPropertyName("id")]
    public string Slug { get; set; }

    // 移除原Id属性
    // 其他属性保持不变
}

同时将Terraform的partition_key_path改为/id，DbContext的HasPartitionKey(p => p.Slug)保持不变。

方案3：手动指定分区键（兜底方案） #

如果上述修改后仍有问题，可在添加实体时手动指定分区键值：

await _context.Posts.AddAsync(post);
_context.Entry(post).Metadata.SetPartitionKey(post.Slug);
await _context.SaveChangesAsync();

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