cosmosdb-best-practices

Azure Cosmos DB 最佳实践

这是一份全面的 Azure Cosmos DB 应用性能优化指南，包含 13 个类别中的 100 多条规则，并按影响程度排序，以指导自动重构和代码生成。

回答前，请阅读与用户问题相关的规则文件。以下快速参考是索引，而非完整指南：SDK API、限制、配置前提条件和注意事项均在规则正文中。若有适用于特定语言的集成规则，请优先使用，不要以通用模式替代。回答应简洁，但需包含使建议适用于用户场景的约束条件。

适用场景

在以下场景中参考这些指南：

• 为 Cosmos DB 设计数据模型
• 选择分区键
• 编写或优化查询
• 实现 SDK 模式
• 使用 Cosmos DB Emulator 进行本地开发
• 使用开发者工具检查或管理 Cosmos DB 数据
• 在 Cosmos DB 上实现向量搜索或 RAG 功能
• 审查代码中的性能问题
• 配置吞吐量和扩展
• 构建全球分布式应用

按优先级划分的规则类别

优先级	类别	影响	前缀
1	数据建模	严重	model-
2	分区键设计	严重	partition-
3	查询优化	高	query-
4	SDK 最佳实践	高	sdk-
5	索引策略	中高	index-
6	吞吐量和扩展	中	throughput-
7	全球分布	中	global-
8	监控和诊断	低中	monitoring-
9	设计模式	高	pattern-
10	开发者工具	中	tooling-
11	向量搜索	高	vector-
12	全文搜索	高	fts-
13	安全	高	security-

快速参考

1. 数据建模（严重）

• model-embed-related - 将一起检索的相关数据嵌入文档
• model-reference-large - 项目过大时使用数据引用
• model-avoid-2mb-limit - 确保项目大小远低于 2MB 限制
• model-id-constraints - 遵循 ID 值的长度和字符限制
• model-unique-keys - 在正确的逻辑分区范围内确保业务键唯一
• model-nesting-depth - 不超过 128 层嵌套深度限制
• model-numeric-precision - 了解 IEEE 754 数值精度限制
• model-denormalize-reads - 针对读密集型工作负载进行反规范化，包括预计算聚合值
• model-schema-versioning - 为文档架构设置版本
• model-type-discriminator - 对多态数据使用类型判别符
• model-json-serialization - 正确处理 Cosmos DB 文档的 JSON 序列化
• model-relationship-references - 对文档关系使用 ID 引用，并在需要时临时填充数据
• model-ttl-expiration - 根据项目的最后更新时间配置 TTL，并设置容器默认值和项目级覆盖值

2. 分区键设计（关键）

• partition-high-cardinality - 选择高基数分区键
• partition-avoid-hotspots - 均匀分布写入
• partition-hierarchical - 使用分层分区键以提升灵活性；层级顺序从宽泛到具体
• partition-query-patterns - 使分区键与查询模式保持一致
• partition-synthetic-keys - 必要时创建合成键
• partition-key-length - 遵守分区键值长度限制
• partition-immutable-key - 选择不可变属性作为分区键
• partition-20gb-limit - 为逻辑分区 20GB 上限做好规划
• partition-rekey-migration - 使用 Change partition key 功能为分区键不匹配的容器重新设定分区键

3. 查询优化（高优先级）

• query-aggregate-single-pass - 使用一次范围限定的聚合查询计算最小值、最大值和平均值
• query-avoid-cross-partition - 尽量减少跨分区查询
• query-use-projections - 仅投影所需字段；投影时优先使用专用结果类型
• query-pagination - 使用延续令牌进行分页
• query-avoid-scans - 避免扫描整个容器
• query-parameterize - 使用参数化查询
• query-order-filters - 让查询引擎决定筛选条件的顺序；优化已索引的谓词，而非调整其文本顺序
• query-top-literal - TOP 使用整数常量，绝不使用参数
• query-latest-by-timestamp - 使用显式的 ORDER BY 和 TOP 1 查询“最新”文档
• query-olap-detection - 检测分析型查询，并将其转离事务型容器
• query-point-reads - 已知 id 和分区键时，使用点读取（ReadItem），而非查询
• query-distinct-keyword - 使用 DISTINCT 返回唯一值，而非在客户端去重

4. SDK 最佳实践（高优先级）

• sdk-singleton-client - 将 CosmosClient 作为单例重用
• sdk-async-api - 使用异步 API 提高吞吐量
• sdk-retry-429 - 使用 retry-after 处理 429
• sdk-connection-mode - 在生产环境中使用 Direct 模式
• sdk-preferred-regions - 配置首选区域
• sdk-excluded-regions - 排除遇到问题的区域
• sdk-availability-strategy - 配置可用性策略以增强复原能力
• sdk-circuit-breaker - 使用熔断器实现容错
• sdk-diagnostics - 记录诊断信息以排查问题
• sdk-serialization-enums - 将枚举序列化为字符串，而非整数
• sdk-emulator-ssl - 配置 Cosmos DB Emulator 的 SSL 和连接模式
• sdk-ifnonematch-create - 在 createItem 上使用 setIfNoneMatchETag("*")，以原子方式拒绝重复项（冲突时返回 409）
• sdk-no-shared-request-options - 对延迟或并发的 createItem 操作使用单独的 CosmosItemRequestOptions 实例，避免共享状态覆盖分区键
• sdk-patch-incr - 使用 CosmosPatchOperations.increment() 原子递增计数器——无需读取 RU，也不会经历 ETag 冲突循环
• sdk-bypage-empty-token - 调用 byPage() 前检查续页令牌是否为空字符串——第一页传入 null，切勿传入 ""
• sdk-etag-concurrency - 在读取-修改-写入操作中使用 ETag 实现乐观并发控制
• sdk-java-content-response - 在写入操作中启用内容响应（Java）
• sdk-java-cosmos-config - 在 Spring Boot 中正确配置 Cosmos DB 初始化
• sdk-java-spring-boot-versions - 使 Java 版本符合 Spring Boot 的要求
• sdk-local-dev-config - 配置本地开发环境，避免与云端发生冲突
• sdk-dotnet-cosmos-package-id - 使用 Microsoft.Azure.Cosmos，而非已弃用的 Azure.Cosmos v4-preview 包
• sdk-newtonsoft-dependency - 显式引用 Newtonsoft.Json 包
• sdk-python-async-deps - 使用 Python 异步 SDK 时包含 aiohttp
• sdk-spring-data-annotations - 为 Spring Data Cosmos 实体添加注解
• sdk-spring-data-repository - 正确使用 CosmosRepository 并处理 Iterable 返回类型
• sdk-langchain-cosmosdb-saver - 使用 CosmosDBSaver 和异步容器客户端进行 LangGraph 检查点保存
• sdk-langchain-async-checkpointer - 在启动例程中初始化异步 Cosmos DB 容器，而非在模块级别初始化
• sdk-langchain-mcp-persistent-session - 在应用程序的整个生命周期内维护持久的 MCP 客户端会话
• sdk-langchain-mcp-tool-content-format - 处理 MCP ToolMessage 内容的字符串和列表两种格式
• sdk-langgraph-mcp-tool-filtering - 按名称前缀筛选 MCP 工具，为各个 Agent 分配工具
• sdk-dotnet-namespace-collision - 避免 Microsoft.Azure.Cosmos 命名空间与领域模型（User、Database、Container 等）冲突
• sdk-ingestion-rate-control - 对高容量数据摄取实施速率控制（并发、retry-after、吞吐量控制）
• sdk-go-partition-key-metadata - 升级过时的 Go SDK，以便在不同 SDK 之间正确序列化分区键类型元数据
• sdk-python-client-kwargs - 使用扁平关键字参数配置 Python v4 客户端，而非使用旧版 ConnectionPolicy 对象
• sdk-langchain-js-chat-history - 使用 AzureCosmosDBNoSQLChatMessageHistory 持久化彼此隔离的 JS/TS 对话
• sdk-langchain-js-embedding-model - 为 JS/TS 嵌入配置 Azure OpenAI 部署名称
• sdk-langchain-js-filter-injection - 通过参数化 filterClause 绑定向量存储筛选值
• sdk-langchain-js-fulltext-prerequisites - 在混合搜索前配置账户功能、文本策略和索引
• sdk-langchain-js-managed-identity - 使用托管身份和数据平面 RBAC 对 JS/TS LangChain 进行身份验证
• sdk-langchain-js-search-types - 根据查询选择向量、全文或混合检索
• sdk-langchain-js-semantic-cache - 使用 AzureCosmosDBNoSQLSemanticCache 重用等效的大模型响应
• sdk-langchain-js-vectorstore-init - 使用嵌入模型和预先配置的 RBAC 资源初始化 JS/TS 向量存储

5. 索引策略（中高）

• index-exclude-unused - 排除从未查询的路径
• index-path-syntax - 使用正确的路径表示法（/?、/[]、/*）
• index-composite - 对 ORDER BY 使用复合索引
• index-composite-direction - 使复合索引方向与 ORDER BY 匹配
• index-spatial - 为地理查询添加空间索引
• index-range-vs-hash - 选择合适的索引类型
• index-lazy-consistent - 了解索引模式

6. 吞吐量与扩展（中）

• throughput-autoscale - 为可变工作负载使用自动缩放
• throughput-right-size - 为预配吞吐量选择合适的规模
• throughput-serverless - 为开发/测试考虑使用无服务器
• throughput-burst - 了解突发容量
• throughput-container-vs-database - 谨慎选择分配级别
• throughput-idle-container-review - 检查空闲容器并采取生命周期管理措施
• throughput-ttl-stale-data - 在达到存储限制前，使用 TTL 清除过期数据
• throughput-serverless-migration - 将低流量预配账户迁移到无服务器

7. 全球分布（中）

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

8. 监控与诊断（低至中）

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

9. 设计模式（HIGH）

• pattern-change-feed-materialized-views - 使用 Change Feed 优化跨分区查询
• pattern-efficient-ranking - 使用基于计数或缓存的方法实现高效排名
• pattern-service-layer-relationships - 使用服务层填充文档引用
• pattern-langgraph-multi-agent - 使用带条件边的 StateGraph 实现多 Agent 路由
• pattern-langgraph-interrupt-human - 使用 LangGraph interrupt 实现人在回路中的确认流程
• pattern-langgraph-resume-checkpoint - 中断后从检查点恢复 LangGraph，以支持多轮对话
• pattern-langgraph-agent-routing-cosmosdb - 在 Cosmos DB 中持久化当前 Agent，通过点读取实现确定性路由
• pattern-langgraph-fastapi-startup - 在 FastAPI 启动时初始化 LangGraph Agent，并实现重试逻辑
• pattern-langgraph-chat-history-separate - 将聊天历史存储在专用容器中，而不是检查点存储器中
• pattern-background-task-writes - 使用 FastAPI 后台任务，以非阻塞方式写入聊天历史
• pattern-langgraph-async-cosmos-routing - 在 LangGraph 路由函数中使用 asyncio.to_thread 包装 Cosmos DB 同步调用
• pattern-langgraph-async-cosmos-writes - 在异步节点函数中使用 asyncio.to_thread 写入当前 Agent
• pattern-langgraph-agent-name-attribution - 为 AI 消息标记 Agent 名称，以便在 API 响应中注明来源
• pattern-ai-grounding-access - 已知项目 ID 和分区键时，使用点读取进行 AI grounding

10. 开发者工具（MEDIUM）

• tooling-vscode-extension - 使用 VS Code 扩展进行日常检查和管理
• tooling-emulator-setup - 使用 Emulator 进行本地开发和测试
• tooling-cosmosdb-shell-target - 读取数据前，确认 Cosmos DB Shell 账号和目标
• tooling-cosmosdb-shell-writes - 限定范围、预览并确认 Cosmos DB Shell 的写入和删除操作
• tooling-cosmosdb-shell-setup - 排查 Cosmos DB Shell MCP 问题，不更改用户的环境

11. 向量搜索（HIGH）

• vector-enable-feature - 使用向量功能前，先在账号上启用向量搜索
• vector-embedding-policy - 为向量属性定义向量嵌入策略
• vector-index-type - 在索引策略中配置向量索引
• vector-normalize-embeddings - 对嵌入进行归一化，以实现余弦相似度计算
• vector-distance-query - 使用 VectorDistance 进行相似度搜索
• vector-repository-pattern - 为向量搜索实现仓储模式

12. 全文搜索（HIGH）

• fts-enable-capability - 在账户上启用 EnableNoSQLFullTextSearch 功能；这是所有 FTS 函数的前提条件
• fts-full-text-policy - 在容器上定义 fullTextPolicy，并使用正确的语言代码（en-US，区分大小写）
• fts-index-policy - 在索引策略中添加 fullTextIndexes 条目，以构建倒排索引
• fts-contains-query - 使用 FullTextContains / FullTextContainsAll / FullTextContainsAny，而不是 CONTAINS(LOWER(...))
• fts-score-ranking - 使用 ORDER BY RANK FullTextScore(path, term) 进行 BM25 相关性排序
• fts-hybrid-query - 将 FTS 谓词与具有选择性的索引等值／范围筛选条件结合使用；谓词文本的顺序不会控制执行顺序

13. 安全（HIGH）

• security-continuous-backup - 启用连续备份，以便进行时间点恢复
• security-disable-local-auth - 将客户端迁移到 Entra ID 后，禁用共享密钥身份验证
• security-managed-identity - 使用托管身份和 DefaultAzureCredential，而不是存储密钥
• security-network-restrict - 限制公共访问，并在生产环境中优先使用专用终结点
• security-private-endpoint-dns - 配置专用 DNS 记录和 VNet 链接，同时保留账户主机名
• security-rbac-least-privilege - 分配范围严格受限的 Cosmos DB 数据平面角色

使用方法

请使用上面链接的规则文件查看详细说明和代码示例。这些链接可让 Agent 直接访问相关指南，而无需依赖扫描文件夹或推测文件名。

每个规则文件包含：

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