使用azcosmos SDK创建CosmosDB项时分区键不匹配错误排查

可能的原因及解决步骤 #

1. 文档对象分区键字段名不匹配 #

检查Go结构体是否正确映射容器配置的_partitionKey字段，注意下划线是必填项：

• 错误示例：字段名不符

  type Item struct {
      ID            string `json:"id"`
      PartitionKey string `json:"partitionKey"` // 与容器/_partitionKey不匹配
  }
  

• 正确示例：

  type Item struct {
      ID            string `json:"id"`
      PartitionKey string `json:"_partitionKey"` // 匹配容器配置的分区键路径
  }
  

2. 指定的分区键值与文档内不一致 #

调用CreateItem时，通过azcosmos.PartitionKey传入的值必须和文档结构体中_partitionKey字段的值完全一致：

• 错误示例：值不匹配

  item := Item{ID: "123", PartitionKey: "user1"}
  // 传入的"user2"与item内的"user1"不一致
  _, err := container.CreateItem(ctx, azcosmos.NewPartitionKeyString("user2"), item)
  

• 正确示例：保持值一致

  item := Item{ID: "123", PartitionKey: "user1"}
  _, err := container.CreateItem(ctx, azcosmos.NewPartitionKeyString(item.PartitionKey), item)
  

3. 分区键值类型不匹配 #

确保分区键构造方法的类型和文档字段类型一致：

• 错误示例：类型不匹配

  type Item struct {
      ID            string `json:"id"`
      PartitionKey int    `json:"_partitionKey"` // 数字类型
  }
  item := Item{ID: "123", PartitionKey: 100}
  // 错误使用字符串类型构造方法
  _, err := container.CreateItem(ctx, azcosmos.NewPartitionKeyString("100"), item)
  

• 正确示例：匹配类型

  _, err := container.CreateItem(ctx, azcosmos.NewPartitionKeyInt(item.PartitionKey), item)
  

4. 序列化丢失分区键字段 #

确保结构体字段是导出状态（首字母大写），否则JSON序列化时会忽略该字段：

• 错误示例：字段未导出

  type Item struct {
      id            string `json:"id"`
      partitionKey string `json:"_partitionKey"` // 小写字段，无法被序列化
  }
  

• 正确示例：导出字段

  type Item struct {
      ID            string `json:"id"`
      PartitionKey string `json:"_partitionKey"` // 首字母大写，可正常序列化
  }
  

5. 错误使用分区键构造方法 #

azcosmos针对不同数据类型提供了对应构造方法，需匹配使用：

• 字符串类型：NewPartitionKeyString
• 整数类型：NewPartitionKeyInt
• 布尔类型：NewPartitionKeyBool
• 浮点类型：NewPartitionKeyFloat
• 空值类型：NewPartitionKeyNull

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