mongodb-schema-design

MongoDB 模式设计

MongoDB 维护的 MongoDB 数据建模模式与反模式。不良模式是大多数 MongoDB 性能和成本问题的根源——查询和索引无法修复根本错误的数据模型。

适用场景

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

• 从头开始设计新的 MongoDB 模式
• 从 SQL／关系型数据库迁移到 MongoDB
• 审查现有数据模型中的性能问题
• 排查查询缓慢或文档大小不断增长的问题
• 决定采用嵌入还是引用
• 对关系建模（一对一、一对多、多对多）
• 实现树形／层级结构
• 看到 Atlas Schema Suggestions 或 Performance Advisor 警告
• 达到 16MB 文档大小限制
• 为现有集合添加模式验证

快速参考

1. 模式反模式 - 3 条规则

• antipattern-unnecessary-collections - 将同类数据拆分到多个集合通常是一种反模式；请参阅此参考资料，确认是否属于这种情况。
• antipattern-excessive-lookups - 如果遇到过度规范化且彼此引用的集合，或频繁且可能缓慢的 $lookup 操作，请参阅此参考资料，确认这是否存在问题以及如何解决。
• antipattern-unnecessary-indexes - 如果索引相互重叠或未被查询使用，请参阅此参考资料，找出并删除那些增加开销却没有收益的不必要索引。

2. 模式基础 - 4 条规则

• fundamental-embed-vs-reference - 有关不同类型关系（一对一、一对少、一对多、多对多、树形／层级数据）的建模方法，以及如何根据访问模式决定采用嵌入还是引用，请参阅此参考资料。
• fundamental-document-model - 文档模型基础。从 SQL 或其他规范化数据迁移到 MongoDB 这类文档数据库时，请参阅此参考资料。
• fundamental-schema-validation - 创建新集合或为现有集合添加验证时，请参阅此参考资料，例如发现文档结构不一致或数据质量问题时。
• fundamental-document-size - 文档达到 16MB 硬性限制，或因文档过大导致访问速度低于预期时，请参阅此参考资料。

3. 设计模式 - 11 条规则

• pattern-approximation - 对高频计数器使用近似值
• pattern-archive - 将历史数据移至单独的冷存储，以提升性能
• pattern-attribute - 将多个可选字段合并为键值属性
• pattern-bucket - 将时序数据或 IoT 数据分组存入桶
• pattern-computed - 预先计算开销较大的聚合结果
• pattern-document-versioning - 跟踪文档变更，以支持历史查询和审计追踪
• pattern-extended-reference - 缓存相关实体中经常访问的数据
• pattern-outlier - 处理少数文档远大于其余文档的集合，避免异常值占用过多内存并增加索引成本
• pattern-polymorphic - 在同一集合中存储不同类型的实体，常用于存储同一基类实体的不同类型（例如，不同类型的用户或产品）
• pattern-schema-versioning - 模式演进、防止偏移以及安全的在线迁移。遇到文档结构不一致，或计划进行无法原子应用的模式变更时，请参考此规则。
• pattern-time-series-collections - 对高频时序数据使用原生时序集合

访问模式分析

在了解更广泛的背景之前，不要立即推荐模式或模式变更。与用户一起分析访问模式，找出痛点和优化机会。

工作流

步骤 1：评估环境 询问用户：

• 这是全新设计，还是已有生产数据库可供分析其访问模式？
• 如果已有生产数据，它是否托管在 Atlas 上？如果是，使用的是哪个层级？（M0/M2/M5 与 M10+）

步骤 2：确定工作负载类型 工作负载是读密集型、写密集型还是读写均衡？这会影响哪些诊断数据来源最相关。 询问用户：

• 这些集合的主要工作负载是什么——读密集型（分析、报告、搜索）、写密集型（日志记录、IoT 数据摄取、频繁更新）还是读写均衡？

通过 db.serverStatus().opcounters 进行验证。

步骤 3：与用户一起选择最佳数据来源 根据用户的情况推荐最佳数据来源，并说明其中的权衡。对于模式设计决策，我们通常需要结合多个数据来源，才能全面了解情况。

步骤 4：开始分析 只有在选定数据来源后，才获取数据或指导用户进行分析。

来源

• 查询统计信息 - 返回已记录查询的运行时统计信息，展示查询形态及其频率。限制：目前仅捕获读操作（可与其他来源结合，以了解写入模式）。需要 Atlas M10+ 层级。
• Atlas 慢查询日志 - 查看慢查询（实际查询，而非查询形态），以识别性能瓶颈。捕获所有读写操作。需要 Atlas M10+ 层级。
• 代码库 - 检查应用程序代码中的实际查询，了解访问模式，尤其适用于新应用程序或工作负载不断变化的情况。可与查询统计信息结合使用，以获得更完整的情况。
• 自然语言输入 - 请用户用自然语言描述其典型查询和访问模式。可单独作为信息来源，也可用于补充和验证其他来源——用户可能掌握数据或代码库中未体现的背景知识。

结合查询统计信息和慢查询日志：

同时使用两者进行全面分析：

1. 查询统计信息 → 识别高频访问模式（哪些查询运行次数最多）
2. 慢查询日志 → 识别性能瓶颈（哪些查询速度较慢）
3. 将模式优化重点放在既频繁又缓慢的查询上（影响最大）

核心原则

“经常一起访问的数据应存储在一起。”

这是 MongoDB 的核心理念。嵌入相关数据可以消除联接、减少往返次数，并支持原子更新。仅在必要时使用引用。

实现这一理念的一个核心方式是 MongoDB 提供了灵活的模式。这意味着不同文档可以包含不同字段，甚至采用不同结构。这样，你就可以按照最符合访问模式的方式对数据建模，而不受固定模式的约束。例如，只要能满足应用程序的需求，不同文档包含不同的字段集合也完全没问题。你还可以使用模式验证来强制执行某些规则，同时保留灵活性。

这一核心原则的另一项影响是，预期读写工作负载的信息与模式设计密切相关。如果来自不同实体的信息经常一起查询或更新，那么优先将这些数据放在同一文档中，就能显著提升性能。另一方面，如果某些信息很少一起访问，将它们分开存储可能更合适，以避免加载不必要的数据。

Schema 基础要点总结

• 嵌入还是引用：根据访问模式选择嵌入或引用：当数据总是一起访问（1:1、1:少、长度有界的数组，需要原子更新）时嵌入；当数据独立访问、关系是多对多，或数组可能无限增长时引用。
• 一起访问的数据应存放在一起：MongoDB 的核心原则是围绕查询设计 Schema，而不是围绕实体设计。嵌入相关数据，消除跨集合联接并减少往返次数。找出 API 端点/页面，列出每个端点/页面返回的数据，然后调整文档结构以匹配这些查询。
• 善用文档模型：不要将 SQL 表逐一照搬为 MongoDB 集合。应将联接的表反规范化为内容丰富的文档，以便单次查询读取并进行原子更新。从 SQL 迁移时，找出总是一起联接的表，并将它们合并为单个文档。
• Schema 验证：使用 MongoDB 内置的 $jsonSchema 验证器，在数据库层捕获无效数据（类型检查、必填字段、枚举约束、数组大小限制）。对于现有集合，先使用 validationLevel: "moderate" 和 validationAction: "warn"，然后再收紧为 strict/error。
• 16MB 文档限制：MongoDB 文档不得超过 16MB——这是硬性限制，而非建议值。常见原因包括：无界数组、大型嵌入式二进制数据、深层嵌套对象。可通过将无界数据移至单独的集合，并使用 $bsonSize 监控文档大小来缓解。

嵌入/引用决策框架

关系	基数	访问模式	建议
一对一	1:1	总是一起访问	嵌入
一对少	1:N (N < 100)	通常一起访问	嵌入数组
一对多	1:N (N > 100)	通常分开访问	引用
多对多	M:N	不定	双向引用

这只是一个粗略的参考指南，是否嵌入或引用取决于具体的访问模式、数据大小以及读写频率。务必根据实际工作负载进行验证。

使用方法

上面列出的每个参考文件都包含详细说明和代码示例。使用快速参考中的描述，确定哪些文件与当前任务相关。

每个参考文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• “不适用场景”例外情况
• 性能影响和指标
• 验证诊断

---

这些规则的工作方式

MongoDB MCP 集成

如需自动验证，请连接 MongoDB MCP Server。

如果 MCP 服务正在运行并已连接，我可以自动运行验证命令，检查实际的 Schema、文档大小、数组长度、索引使用情况、慢查询日志等。这让我能够根据实际数据（而不仅仅是代码模式）提供量身定制的建议。

⚠️ 安全性：为确保安全，请使用 --readOnly。只有在需要执行写操作时才移除。

连接后，我可以自动：

• 通过 mcp__mongodb__collection-schema 推断 Schema
• 通过 mcp__mongodb__aggregate 测量文档/数组大小
• 通过 mcp__mongodb__db-stats 检查集合统计信息

⚠️ 操作策略

未经你的明确批准，我绝不会执行写入操作。

在通过 MCP 执行任何写入或破坏性操作前，我会：（1）概述具体操作（集合、索引／验证器、预计影响的文档数量）；（2）请求你明确确认（是／否）。对于不完整或含糊的批准，我不会继续操作。

操作类型	MCP 工具	操作
读取（安全）	find、aggregate、collection-schema、db-stats、count	我可以自动运行以进行验证
写入（需要批准）	update-many、insert-many、create-collection	我会展示命令并等待你回复“是”
破坏性操作（需要批准）	delete-many、drop-collection、drop-database	我会提醒你并要求明确确认

当我建议更改架构或修改数据时：

1. 我会说明想做什么以及为什么
2. 我会展示确切的命令
3. 我会在执行前等待你的批准
4. 只有你说“继续”或“是”后，我才会执行

**你的数据库，由你决定。**我会提供建议，不会擅自行动。

携手协作

如果你不确定某项建议：

1. 运行我提供的验证命令
2. 将输出发给我
3. 我会根据你的实际数据调整建议

我们是一个团队——一起把事情做好。