cosmosdb-best-practices

Azure Cosmos DB 最佳实践

Azure Cosmos DB 应用的综合性能优化指南，包含 10 个类别中的 73 条以上规则，并按影响程度排序，以指导自动重构和代码生成。

73 个独立规则文件位于 rules/ 目录中，每条规则对应一个文件， 同步自 AzureCosmosDB/cosmosdb-agent-kit。 回答问题时，只加载相关规则文件，切勿一次性加载所有文件。

适用场景

在以下情况下参考这些指南：

• 设计 Cosmos DB 数据模型
• 选择分区键
• 编写或优化查询
• 实现 SDK 模式
• 审查代码中的性能问题
• 配置吞吐量和扩展
• 构建全球分布式应用
• 实现向量搜索和 RAG 模式

规则索引

规则按类别前缀分组。针对具体问题，加载匹配相关前缀的文件（例如，数据建模使用 model-*.md，SDK 用法使用 sdk-*.md）。 类别说明请参阅 rules/_sections.md。

1. 数据建模 — 严重（前缀：model-）

• model-embed-related.md — 嵌入一同检索的相关数据
• model-reference-large.md — 项目变大时使用数据引用
• model-avoid-2mb-limit.md — 确保项目大小远低于 2MB 限制
• model-id-constraints.md — 遵循 ID 值的长度和字符限制
• model-nesting-depth.md — 不超过 128 层嵌套深度限制
• model-numeric-precision.md — 了解 IEEE 754 数值精度限制
• model-denormalize-reads.md — 针对读取密集型工作负载进行反规范化
• model-schema-versioning.md — 为文档架构进行版本管理
• model-type-discriminator.md — 使用类型判别符处理多态数据
• model-json-serialization.md — 正确处理 JSON 序列化
• model-relationship-references.md — 使用 ID 引用并进行临时数据填充

2. 分区键设计 — 严重（前缀：partition-）

• partition-high-cardinality.md — 选择高基数分区键
• partition-avoid-hotspots.md — 均匀分布写入
• partition-hierarchical.md — 使用分层分区键以提高灵活性
• partition-query-patterns.md — 使分区键与查询模式相匹配
• partition-synthetic-keys.md — 必要时创建合成键
• partition-key-length.md — 遵守分区键值的长度限制
• partition-20gb-limit.md — 为 20GB 逻辑分区限制做好规划

3. 查询优化 — 高（前缀：query-）

• query-avoid-cross-partition.md — 尽量减少跨分区查询
• query-use-projections.md — 仅投影所需字段
• query-pagination.md — 使用延续令牌进行分页
• query-avoid-scans.md — 避免扫描整个容器
• query-parameterize.md — 使用参数化查询
• query-order-filters.md — 按选择性对筛选条件排序

4. SDK 最佳实践 — 高（前缀：sdk-）

• sdk-singleton-client.md — 将 CosmosClient 作为单例重复使用
• sdk-async-api.md — 使用异步 API 提高吞吐量
• sdk-retry-429.md — 使用 retry-after 处理 429 错误
• sdk-connection-mode.md — 在生产环境中使用 Direct 模式
• sdk-preferred-regions.md — 配置首选区域
• sdk-excluded-regions.md — 排除出现问题的区域
• sdk-availability-strategy.md — 配置可用性策略以提高复原能力
• sdk-circuit-breaker.md — 使用断路器实现容错
• sdk-diagnostics.md — 记录诊断信息以排查问题
• sdk-serialization-enums.md — 将枚举序列化为字符串，而非整数
• sdk-emulator-ssl.md — 为 Cosmos DB Emulator 配置 SSL 和连接模式
• sdk-etag-concurrency.md — 使用 ETag 实现乐观并发控制
• sdk-java-content-response.md — 为写入操作启用内容响应（Java）
• sdk-java-cosmos-config.md — 在 Spring Boot 中使用依赖 Bean 配置 Cosmos DB
• sdk-java-spring-boot-versions.md — 使 Java 版本符合 Spring Boot 的要求
• sdk-local-dev-config.md — 配置本地开发环境以避免与云端冲突
• sdk-newtonsoft-dependency.md — 显式引用 Newtonsoft.Json 程序包（.NET）
• sdk-spring-data-annotations.md — 为 Spring Data Cosmos 实体添加注解
• sdk-spring-data-repository.md — 正确使用 CosmosRepository

5. 索引策略 — 中高（前缀：index-）

• index-exclude-unused.md — 排除从不查询的路径
• index-composite.md — 为 ORDER BY 使用复合索引
• index-spatial.md — 为地理空间查询添加空间索引
• index-range-vs-hash.md — 选择合适的索引类型
• index-lazy-consistent.md — 了解索引模式

6. 吞吐量与扩展 — 中（前缀：throughput-）

• throughput-autoscale.md — 对可变工作负载使用自动缩放
• throughput-right-size.md — 合理设置预配吞吐量
• throughput-serverless.md — 考虑在开发/测试环境中使用无服务器模式
• throughput-burst.md — 了解突发容量
• throughput-container-vs-database.md — 明智地选择分配层级

7. 全球分布 — 中（前缀：global-）

• global-multi-region.md — 配置多区域写入
• global-consistency.md — 选择合适的一致性级别
• global-conflict-resolution.md — 实现冲突解决
• global-failover.md — 配置自动故障转移
• global-read-regions.md — 在用户附近添加读取区域
• global-zone-redundancy.md — 启用区域冗余以实现高可用性

8. 监控与诊断 — LOW-MEDIUM（前缀：monitoring-）

• monitoring-ru-consumption.md — 跟踪 RU 消耗
• monitoring-latency.md — 监控 P99 延迟
• monitoring-throttling.md — 在发生限流时发出警报
• monitoring-azure-monitor.md — 集成 Azure Monitor
• monitoring-diagnostic-logs.md — 启用诊断日志记录

9. 设计模式 — HIGH（前缀：pattern-）

• pattern-change-feed-materialized-views.md — 使用 Change Feed 创建物化视图
• pattern-efficient-ranking.md — 使用基于计数或缓存的方法进行排名
• pattern-service-layer-relationships.md — 使用服务层填充文档引用

10. 向量搜索 — HIGH（前缀：vector-）

• vector-enable-feature.md — 在帐户上启用向量搜索功能
• vector-embedding-policy.md — 在容器上定义向量嵌入策略
• vector-index-type.md — 配置向量索引（QuantizedFlat 或 DiskANN）
• vector-distance-query.md — 使用 VectorDistance() 进行相似度搜索
• vector-normalize-embeddings.md — 规范化嵌入以计算余弦相似度
• vector-repository-pattern.md — 为向量搜索实现仓储模式

使用方法

每条规则都位于 rules/ 下的独立文件中。回答 Cosmos DB 问题时， 请根据与主题匹配的前缀，只阅读相关规则文件：

• 数据建模问题 → 阅读 rules/model-*.md 文件
• 分区键问题 → 阅读 rules/partition-*.md 文件
• SDK/客户端问题 → 阅读 rules/sdk-*.md 文件
• 等等

每个规则文件包含：

• 简要说明规则的重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料

来源：AzureCosmosDB/cosmosdb-agent-kit