使用 Azure Cosmos DB…

在编写、审查或重构与 Azure Cosmos DB 交互的代码、设计数据模型、优化查询或实现高性能数据库操作时，按主题加载对应规则文件获取具体做法。

适用场景

解决思路

1. 按问题主题只加载相关前缀的规则文件，不要一次性加载全部 73 个规则文件：数据建模读 rules/model-*.md，分区键读 rules/partition-*.md，SDK/客户端读 rules/sdk-*.md，依此类推。
2. 数据建模（model-）：将一起检索的相关数据内嵌（embed）；当条目变大时改用引用（reference）；保持条目远低于 2MB 限制；遵守 ID 值的长度和字符约束；嵌套深度不超过 128 层；理解 IEEE 754 数值精度限制；为读密集负载做反规范化；对文档 schema 做版本管理；对多态数据使用类型判别字段；正确处理 JSON 序列化；使用 ID 引用并配合临时水合（transient hydration）。
3. 分区键设计（partition-）：选择高基数的分区键；均匀分布写入以避免热点；使用分层分区键以获得灵活性；让分区键与查询模式对齐；必要时创建合成键；遵守分区键值长度限制；为 20GB 逻辑分区上限做规划。
4. 查询优化（query-）：尽量减少跨分区查询；只投影需要的字段；使用 continuation token 做分页；避免全容器扫描；使用参数化查询；按选择性排列过滤条件顺序。
5. SDK 最佳实践（sdk-）：将 CosmosClient 作为单例复用；使用异步 API 提升吞吐；用 retry-after 处理 429；生产环境使用 Direct 模式；配置首选区域；排除出现问题的区域；配置可用性策略以增强韧性；使用熔断器实现容错；记录诊断信息以便排查；将枚举序列化为字符串而非整数；为 Cosmos DB Emulator 配置 SSL 和连接模式；使用 ETag 实现乐观并发；在 Java 中为写操作启用内容响应；在 Spring Boot 中用依赖 Bean 配置 Cosmos DB；匹配 Java 版本与 Spring Boot 要求；配置本地开发以避免与云端冲突；在 .NET 中显式引用 Newtonsoft.Json 包；为 Spring Data Cosmos 实体添加注解；正确使用 CosmosRepository。
6. 索引策略（index-）：排除从不查询的路径；使用复合索引支持 ORDER BY；为地理查询添加空间索引；选择合适的索引类型（range vs hash）；理解索引模式（lazy/consistent）。
7. 吞吐与扩展（throughput-）：对波动负载使用自动缩放；合理调整预置吞吐量；开发/测试可考虑无服务器模式；理解突发容量；明智选择在容器级还是数据库级分配吞吐量。
8. 全局分发（global-）：配置多区域写入；选择合适的 consistency 级别；实现冲突解决；配置自动故障转移；在用户附近添加只读区域；启用区域冗余以实现高可用。
9. 监控与诊断（monitoring-）：跟踪 RU 消耗；监控 P99 延迟；对限流设置告警；集成 Azure Monitor；启用诊断日志。
10. 设计模式（pattern-）：使用 Change Feed 构建物化视图；使用基于计数或缓存的方式做排名；使用服务层水合文档引用。
11. 向量搜索（vector-）：在账户上启用向量搜索功能；在容器上定义向量嵌入策略；配置向量索引（QuantizedFlat 或 DiskANN）；使用 VectorDistance() 做相似度搜索；为余弦相似度归一化嵌入向量；为向量搜索实现仓储模式。
12. 每个规则文件包含：为什么重要的简要说明、带解释的错误代码示例、带解释的正确代码示例，以及额外上下文和参考链接。

适用边界 · 注意事项

• 不涉及 Azure Cosmos DB 的项目或场景。
• 没有 Azure 订阅或 Cosmos DB 资源、无法实际应用这些配置时。
• 只想泛泛了解 NoSQL 而不打算落地到 Cosmos DB 特定 API 与限制时。