数据质量问题是很多项目中后期的隐形成本。MongoDB作为Schema-free文档数据库，灵活是优点，但如果对插入数据不做任何约束，很容易出现同一个集合里字段名拼写不一致、类型混乱、必填字段缺失等问题，等数据量大了再清理代价极高。MongoDB从3.2版本开始提供了Document Validation功能，允许为集合定义验证规则，而不符合规则的操作可以被拒绝。Compass图形化客户端内置了Validation面板，可以直接可视化编写、测试和调试这些验证规则，也就是常说的mongodb-compass-validation功能，下面详细介绍它的使用方法。
验证规则的基本原理和语法
MongoDB的文档验证基于查询操作符来构建，本质上是把一个查询条件作为校验器（validator），插入或更新的文档必须满足这个条件才能通过。校验器使用JSON格式编写，支持的常用操作符包括$type（限制字段类型）、$exists（要求字段必须存在）、$eq、$gt、$in（限制取值范围）、$regex（正则匹配）等。
例如要求用户集合中name字段必须是字符串且必填，age必须是0到150之间的整数，可以这样写：
{
$jsonSchema: {
bsonType: "object",
required: ["name", "age"],
properties: {
name: {
bsonType: "string",
description: "name必须是字符串且必填"
},
age: {
bsonType: "int",
minimum: 0,
maximum: 150,
description: "age必须是0到150的整数"
},
email: {
bsonType: "string",
pattern: "^[^@]+@[^@]+\\.[^@]+$",
description: "email格式必须合法"
}
}
}
}校验器有两种主流写法：一种是上面使用的$jsonSchema，结构清晰、可读性强，是官方推荐的方式；另一种是直接使用查询操作符的组合，比如{ name: { $type: "string" } }，写法更简洁但表达复杂逻辑时不如jsonSchema直观。两种方式也可以混用，但在同一层面使用时需要注意兼容性，建议新项目统一采用$jsonSchema。
在Compass中创建和调试验证规则
打开Compass后进入目标集合，顶部标签栏可以看到Validation选项卡。如果集合还没有验证规则，页面会提示Validator Disabled，点击Create Rule按钮即可开始编写。编写区分为可视化表单和JSON文本两种模式，可视化模式下可以通过下拉框选择字段、操作符和值，适合快速上手；JSON模式则直接编辑完整的校验器，适合复杂规则。编辑过程中Compass支持从现有文档生成规则草稿，也就是把某个字段较多的样例文档的结构转成初始校验器，再人工调整，这个功能在字段多的时候非常省事。
Validation面板最有价值的功能是实时测试。Compass会自动从集合中抽样文档，分别展示Passes Validation和Fails Validation两组结果，编辑规则时右侧结果会即时刷新。这让你能在应用规则之前就清楚地知道有多少存量数据不满足新规则，避免规则上线后大量写入失败的尴尬局面。如果失败文档较多，可以直接查看具体是哪些文档、哪个字段不符合要求，针对性修正数据。
规则确认无误后点击Save，Compass会执行类似下面的底层命令，为集合创建或更新验证器：
// 底层等价于collMod命令
db.runCommand({
collMod: "users",
validator: {
$jsonSchema: {
bsonType: "object",
required: ["name", "age"],
properties: {
name: { bsonType: "string" }
}
}
},
validationLevel: "strict",
validationAction: "error"
})需要注意，修改验证规则只影响之后的写入操作，已有数据不会被回溯校验或修改，存量数据的清洗需要另行处理。
validationLevel和validationAction的深入理解
除了validator本身，还有两个关键参数控制校验行为的严格程度。第一个是validationLevel，它决定规则应用于哪些操作。可选值有三个：strict是默认值，所有插入和更新操作都必须通过校验，包括对已有文档的修改；moderate则只对插入的新文档和已经满足现有规则的文档生效，对原本就不合规的存量文档的更新不做校验，适合逐步收紧规则而不阻塞历史数据维护的场景；off则完全关闭校验，常用于临时排障。
第二个是validationAction，决定校验失败时的处理方式。error是默认值，不合规的写入直接报错并被拒绝；warn则只在日志中记录警告，写入照常成功，适合规则灰度上线阶段，先观察影响面再切换为error。两者的组合策略很实用：新规则先设置moderate加warn上线，观察日志确认没有误伤后，再改为strict加error严格生效。
Compass的Validation面板顶部提供了这两个参数的下拉选择，配合实时抽样测试，可以完整覆盖规则从起草、灰度到严格执行的全流程。
常见问题与排查思路
实际使用中最常见的问题是类型不匹配。MongoDB中的数字类型区分int、long、double等，如果校验器要求bsonType: "int"，而应用通过驱动写入的是JavaScript的普通数字（默认会存为double），校验就会失败。解决办法要么在校验器中放宽为$type: "number"，要么在写入时明确使用Int32类型。这类问题在Node.js驱动中尤其常见。
其次是嵌套文档的校验。jsonSchema支持在properties中对嵌套对象继续定义bsonType为object的子schema，配合required约束子文档内的必填字段，数组字段则用bsonType加items来约束每个元素的结构。规则越复杂，越建议利用Compass的实时测试面板逐字段验证，不要一次性写完再排查。
最后提醒一点，验证规则并不能替代应用层的完整业务校验，它更像数据库层面的最后一道防线，适合约束结构性和类型层面的问题。规则数量过多、嵌套过深也会影响写入性能，核心集合的校验器应保持精简，把复杂业务规则留给应用层处理，两层配合才能兼顾数据质量和系统性能。
MongoDB Compassvalidation验证规则文档校验修改时间：2026-09-09 08:18:35