手册

存在一对少的关联关系，其中相关数据是有限的、小的，并且经常一起读取。

→将相关数据作为嵌套对象或数组嵌入到主文档中。

原因: 通过单点读取检索所有必要数据来优化读取性能，最大程度地降低 RU 成本和延迟。避免客户端连接。

参考↗

一对多的关联关系，其中“多”方无限制增长或独立于“一”方进行更新。

→将相关项作为单独的文档存储，并使用父文档的 ID 作为引用。

原因: 防止文档超出 2 MB 的大小限制，并避免对大型嵌入数组进行更新时产生高昂的 RU 成本。

参考↗

文档包含一个可能随时间无限增长的数组，存在超出 2 MB 文档大小限制的风险（例如，事件日志、评论）。

→将数组拆分到多个“桶”文档中。当一个桶达到大小/项目阈值时，创建一个新的桶。

原因: 在保持相关数据逻辑分组的同时，使单个文档大小可管理。

建模多对多关系，例如学生与课程，或文章与标签。

→对于有限的关系，在双方复制关系数据（例如，将课程 ID 嵌入到学生文档中，将学生 ID 嵌入到课程文档中）。对于无限的关系，使用单独的“连接”或“边缘”文档容器。

原因: 非规范化优化了两种查询方向（课程中的学生，学生的课程），而无需连接。连接容器用于无限情况。

建模分层数据（例如，组织结构图、产品类别），并需要查询节点的所有后代。

→在每个文档中存储所有祖先 ID 或名称的数组（路径）。

原因: 通过单个 `ARRAY_CONTAINS` 过滤器实现高效的子树查询，避免了昂贵的递归查找。

文档包含一个无限制数组（例如，博客评论），但最常见的查询只需要最新的 N 个项目。

→在主文档中嵌入最近项目的子集，并将所有项目存储为单独的引用文档。

原因: 优化主要读取路径的性能和成本，同时在需要时仍允许访问完整数据集。

为实体存储一系列不可变事件，并需要查询当前状态或分析聚合。

→将事件存储在一个按实体 ID 分区的容器中。使用 Change Feed 或 Synapse Link 计算并存储物化视图或聚合。

原因: 提供完整的审计跟踪，并将写入模型与各种读取模型解耦，提供高灵活性。

需要保留相关数据在特定时间点的状态（例如，订单上的客户地址）。

→在文档中嵌入相关数据的副本（快照），而不是引用它。

原因: 通过将文档与对引用数据未来的更改解耦，确保历史准确性。

摄取高频时序数据（例如，IoT 传感器读数），并按设备在时间范围内进行查询。

→使用设备 ID 作为分区键。将读数聚合到按时间分桶的文档中（例如，每小时或每分钟），而不是每个读数一个文档。

原因: 显著减少文档数量和写入 RU，同时将数据共置，以实现分区内高效的时间范围查询。

需要将多个创建、更新或删除操作作为单个原子事务执行。

→使用 SDK 的 TransactionalBatch 功能。所有操作必须针对同一个逻辑分区键。

原因: 在单个分区内为多达 100 个操作提供 ACID 保证，确保所有操作要么全部成功，要么全部失败。

文档应在特定时间段（例如，30 天）后从容器中自动删除。

→在容器上启用生存时间 (TTL) 并设置以秒为单位的默认 `ttl` 值（例如，30 天为 2592000）。单个文档上的 `ttl` 值为 -1 会覆盖默认值并阻止过期。

原因: TTL 是一项免费功能，它利用剩余的 RU 执行后台删除，提供了一种高效、无需干预的数据生命周期管理方式。

需要存储与 Cosmos DB 元数据关联的大型二进制对象（图像、视频、大于 2 MB 的文档）。

→将二进制对象存储在 Azure Blob Storage 中。将 blob 的 URI 与元数据一起存储在 Cosmos DB 文档中。

原因: Cosmos DB 针对结构化元数据进行了优化，并具有 2 MB 的文档限制。Blob Storage 是一种经济高效且可扩展的大对象存储服务。

相同的数据需要通过不同的属性进行查询，导致效率低下的跨分区查询（例如，先按客户查询订单，再按产品查询）。

→使用 Change Feed 将相同数据填充到第二个容器（物化视图）中，但按次要查询属性进行分区。

原因: 将计算从读取时转移到写入时，为多种访问模式实现高效的单分区查询。

需要在实时操作数据上运行复杂的分析查询（聚合、连接），而不影响事务性工作负载。

→在 Cosmos DB 容器上启用 Azure Synapse Link。使用 Synapse 无服务器 SQL 或 Spark 池对容器的分析存储运行分析查询。

原因: 提供无 ETL 的云原生 HTAP 解决方案。对列式分析存储的查询不消耗事务性 RU，并且性能极高。

需要以可伸缩、可靠和无服务器的方式响应数据更改触发下游操作。

→使用带有 Cosmos DB 触发器的 Azure Function。该触发器自动利用 Change Feed Processor 库。

原因: 这是事件驱动架构的推荐模式。它提供自动伸缩、检查点和分区租约管理。

参考↗

一个操作必须原子地更新数据库并发布消息到消息系统（例如，Service Bus, Event Hubs）。

→执行数据库写入。使用 Change Feed 处理器可靠地读取已提交的更改并发布相应的消息，并附带重试逻辑。

原因: 避免不可靠的双重写入和分布式事务的需要。Change Feed 作为持久性的发件箱，保证消息的最终交付。

为新容器选择分区键以确保性能和可伸缩性。

→选择一个具有高基数且存在于大多数（如果不是所有）点读取和查询操作中的属性。

原因: 将分区键与最常见的查询过滤器对齐，可确保大多数操作都路由到单个逻辑分区，这是最高效的访问模式。

参考↗

单个分区键值接收到不成比例的大量请求，导致限制（“热分区”）。

→通过将原始键与随机后缀或另一个高基数属性（例如，`userId + "-" + random(1-10)`）连接起来，创建合成（synthetic）分区键。

原因: 将单个逻辑实体的写入和读取负载分配到多个物理分区，从而缓解限制。

数据需要按多个级别（例如，租户，然后是年份，然后是月份）进行分区，以避免大型分区并支持多级别查询。

→配置一个具有有序路径数组的分层分区键，例如 `["/tenantId", "/year"]`。

原因: 允许子分区以防止 20 GB 的逻辑分区限制，并为按层次结构筛选的查询实现更高效的路由。

启用多区域写入的全球分布式应用程序需要处理对同一文档的并发更新。

→对于简单的覆盖，使用 Last-Writer-Wins (LWW) 策略。对于需要合并逻辑的操作（例如，递增计数器、更新库存），使用带有合并存储过程的自定义冲突解决策略。

原因: 自定义合并逻辑可防止使用 LWW 策略时可能发生的数据丢失（例如，丢失的增量），确保关键业务操作的数据完整性。

为全球分布式应用程序平衡读取延迟、可用性和数据一致性。

→默认使用会话（Session）一致性以实现良好的平衡和读己所写。使用有限过期（Bounded Staleness）以实现可预测的读取延迟。根据需要，将特定的关键写入/读取操作覆盖为强（Strong）一致性。

原因: 会话（Session）是最广泛使用的一致性级别，在客户端会话中提供低延迟和强保证。按请求覆盖允许灵活性。

写入操作消耗过多的 RU，并且只有一小部分文档属性用于查询过滤器。

→从默认索引策略切换到自定义策略。明确包含查询属性的路径，并排除所有其他路径（`excludedPaths` 中的 `“/*”`）。

原因: 每个索引属性在写入时都会产生 RU 成本。排除未使用的属性可以显著减少写入 RU 消耗和索引存储大小。

参考↗

一个频繁的查询在一个属性上进行筛选，并按另一个属性进行排序（例如，`WHERE c.status = "active" ORDER BY c.timestamp DESC`）。

→按查询中出现的顺序在属性上创建复合索引：`(status ASC, timestamp DESC)`。

原因: 允许查询引擎直接从索引中提供筛选和排序结果，避免了昂贵的内存排序操作，并显著降低了 RU 费用。

查询检索大型文档，但应用程序只需要其中一两个小属性。

→使用查询投影仅选择所需的属性（例如，`SELECT c.id, c.name FROM c`），而不是 `SELECT *`。

原因: 通过降低从数据库引擎传输到客户端的数据负载大小来减少 RU 成本。

应用程序频繁轮询文档更新，但数据不常更改，导致读取的 RU 成本很高。

→存储上次读取的 ETag。在后续读取时，在 `If-None-Match` 头中发送 ETag。

原因: 如果文档未更改，Cosmos DB 将返回 304 未修改状态，并收取最低限度的 RU 费用（通常约为 1 RU），从而节省成本和带宽。

工作负载具有可变或不可预测的流量模式，具有显著的峰值和低谷。

→在数据库或容器上配置自动缩放吞吐量。设置峰值负载所需的最大 RU/秒。

原因: 根据使用情况，在最大 RU/秒的 10% 到最大 RU/秒之间自动缩放吞吐量，通过不为闲置的预配容量付费来优化成本。

工作负载用于开发、测试或具有长时间空闲期的低流量应用程序。

→为 Cosmos DB 帐户使用无服务器容量模式。

原因: 您只需为每次操作消耗的 RU 付费，没有最低预配容量。这是零星工作负载最具成本效益的选择。

需要尽快摄取或修改大量文档（数千到数百万）。

→使用 SDK 的批量支持功能（例如，.NET SDK v3 中的 `AllowBulkExecution = true`）。

原因: SDK 通过批量操作、管理并发以及内部处理重试/限制来优化高吞吐量，远远优于顺序操作。

处理大量文档的存储过程正在超时。

→实现有界执行。存储过程应检查是否接近 5 秒的执行限制，如果是，则向客户端返回一个续传令牌。然后，客户端使用该令牌重新调用过程以恢复处理。

原因: 存储过程具有严格的执行时间限制。续传模式是处理长时间运行、多步服务器端逻辑的标准方法。

业务关键型应用程序在区域中断时需要高可用性，并要求最小数据丢失（RPO）和快速恢复时间（RTO）。

→为 Cosmos DB 帐户配置多个写入区域并启用自动故障转移。

原因: 提供最低的 RPO 和 RTO。数据在区域之间复制，在发生中断时，Cosmos DB 会自动将次要区域提升为新的主要写入区域。

需要通过将数据库恢复到特定时间点来从意外数据删除或损坏中恢复的能力。

→在 Cosmos DB 帐户上启用连续备份模式。

原因: 连续备份允许您在保留期（7 或 30 天）内恢复到任何时间点（精确到秒）。恢复操作会创建一个新帐户。

参考↗

合规性要求规定数据加密密钥必须由客户管理和控制。

→使用 Azure Key Vault 中的密钥配置带有客户管理密钥 (CMK) 的 Cosmos DB 帐户。

原因: 提供额外的安全层，您可以在其中控制静态加密的密钥生命周期（包括轮换和撤销）。

需要按照最小权限原则，向应用程序或用户授予对数据的细粒度、基于身份的访问权限。

→使用 Azure AD 集成并分配内置角色（例如，Cosmos DB 内置数据读取器）或自定义 RBAC 角色，范围限定为特定的容器或数据库。

原因: 消除了管理和共享主密钥的需要。RBAC 提供可审计的、基于身份的访问控制。

Cosmos DB 帐户只能从特定的 Azure 虚拟网络 (VNet) 内部访问，且没有通过公共互联网的流量。

→在 VNet 中为 Cosmos DB 帐户创建私有终结点，并在防火墙设置中禁用公共网络访问。

原因: 私有终结点为 VNet 中的 Cosmos DB 帐户提供私有 IP 地址，确保所有流量都通过安全的 Azure 主干网络传输。

诊断 HTTP 429（请求过多）限制错误的根本原因。

→在 Azure Monitor 中监控“规范化 RU 消耗”指标。使用诊断日志 (`CDBPartitionKeyRUConsumption`) 来识别哪些分区键消耗了最多的 RU。

原因: 规范化 RU 消耗显示了整体吞吐量是否已耗尽。分区级日志可以查明热分区，即使总体使用率较低，这也是限制的常见原因。

需要监控请求延迟并发出警报，以确保 SLA 合规性。

→在 Azure Monitor 中监控“服务器端延迟 P99”指标。创建警报规则，当此指标超过 SLA 阈值时发出警报。

原因: P99 延迟代表了 99% 请求的最差体验，也是 Cosmos DB SLA 的基础。它是比平均延迟更有意义的性能问题指标。

合规性要求规定所有数据访问操作（读取、写入、查询）都必须经过审计。

→在 Cosmos DB 帐户上启用诊断设置，并将 `DataPlaneRequests` 日志类别转发到 Log Analytics 工作区或存储帐户。

原因: `DataPlaneRequests` 日志提供每次数据操作的详细信息，包括操作类型、客户端 IP 和访问的资源，这对于安全审计至关重要。

不受信任的客户端（例如，移动应用程序）需要对特定 Cosmos DB 资源（例如，仅限其自己分区中的文档）进行临时、范围受限的访问。

→实现一个可信的中间层服务，该服务对用户进行身份验证，然后使用主密钥生成并向客户端返回一个短期、权限范围受限的资源令牌。

原因: 这是客户端访问最安全的模式，因为它避免了暴露主密钥并提供了细粒度的临时访问控制。