配 TaoToken：settings.json 骨架与校验动作)
1. 为什么 mongoose 的 Data Validation 总在“最后一公里”翻车
如果你写过 Node.js + MongoDB 的后端，大概率经历过这种场景：接口在 Postman 里跑得好好的，字段该填的都填了，结果某天运营同学直接连数据库批量导入，或者另一个服务用原生 driver 写了一条记录，线上就冒出一堆name为null的脏数据。问题不在 MongoDB，它本身是 schema-less 的，你给它什么它就存什么；问题在于我们把“数据验证”这件事全押在了应用层的 mongoose Schema 上，而 mongoose 的 Data Validation 只在save()、validate()、create()这些走 Model 的路径上生效。
这篇就聚焦 mongoose Schema 里 Data Validation 的落地配置：必填、类型、长度、枚举、自定义 validator、异步 validator，以及报错怎么定位。同时我会给出一份可复制的settings.json骨架，把 TaoToken 的统一 Key 和 API 通道接进你的 AI 编码工具里，让写 Schema、查报错、补 validator 这些动作能在一个通道里完成。适合已经能跑通 Express + mongoose 基础 CRUD、但校验链路还没理顺的 Node.js 后端开发者。
先说清楚一个前提：mongoose 的验证是“应用层验证”，不是数据库约束。MongoDB 里没有required这个概念，所以任何绕过 mongoose 的写入都不会被拦。理解这一点，后面所有配置你才知道边界在哪。
2. TaoToken 前置：统一 Key 与 API 通道接入 AI 工具
在写校验代码之前，先把工具链理顺。TaoToken 的作用是给 AI 编码工具提供一个统一的 API 通道和 Key 管理入口，你不用在多个工具里反复填不同的地址和密钥。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个不加 UTM）。
你需要先拿到 Key。进入控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 列表页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到之后，下面这份settings.json骨架可以直接复制，把YOUR_TAOTOKEN_KEY替换成你自己的 Key 即可。这份骨架的用途是让支持读取settings.json的 AI 编码工具（比如 Claude Code 这类）走统一通道，写 Schema、排查 validator 报错时不用来回切配置。
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_TAOTOKEN_KEY", "ANTHROPIC_MODEL": "claude-sonnet-4-5" }, "permissions": { "allow": [ "Read", "Write", "Bash(npm run test:*)", "Bash(node scripts/validate-demo.js)" ] }, "includeCoAuthoredBy": false }几个字段说明一下。ANTHROPIC_BASE_URL指向 TaoToken 的 API 通道，ANTHROPIC_AUTH_TOKEN放你的 Key，ANTHROPIC_MODEL按你实际可用的模型名填。permissions.allow里我特意放了node scripts/validate-demo.js，因为后面验证校验链路时会反复跑这个脚本，提前放行省得每次确认。如果你用的是别的工具，只要它支持自定义 base URL 和 token，把这两个值对应填进去就行。
注意：Key 不要硬编码进业务代码仓库，
settings.json建议放在用户级配置目录或加进.gitignore。生产环境的 Key 和本地开发用的 Key 最好分开管理。
配置好之后，你可以用模型对话入口快速验证通道是否通： https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。如果对话能正常返回，说明 Key 和通道没问题，接下来写校验代码时遇到报错，可以直接把错误栈贴进去让它帮你定位。
3. 可复制配置：从 Schema 骨架到自定义 validator
这一节是主体，我按“必填 → 类型与内建验证器 → 自定义 validator → 异步 validator → 错误定位”的顺序给完整代码。你可以新建一个scripts/validate-demo.js，把下面的片段拼起来跑。
3.1 基础 Schema 与必填验证
先定义一个课程 Schema。注意初始版本所有字段都是可选的，这意味着你完全可以new Course({})然后save()成功，MongoDB 不会拦你。
const mongoose = require('mongoose'); const courseSchema = new mongoose.Schema({ name: String, author: String, tags: [String], date: { type: Date, default: Date.now }, isPublished: Boolean, }); const Course = mongoose.model('Course', courseSchema);把name改成必填，只需要加required: true：
const courseSchema = new mongoose.Schema({ name: { type: String, required: true }, author: String, tags: [String], date: { type: Date, default: Date.now }, isPublished: Boolean, });现在提交一个没有name的课程会失败。关键点是：save()返回的是 Promise，验证失败会 reject，所以必须放在try/catch里，否则就是一个未处理的 rejection。
async function createCourse() { const course = new Course({ author: 'leo', isPublished: true }); try { const result = await course.save(); console.log(result); } catch (ex) { console.log(ex.message); } }这里有个容易踩的点：course.validate()也可以触发验证，但它返回的是一个空 Promise，你拿不到布尔值做判断，只能靠 reject 进 catch，或者用 callback 形式。所以日常我更推荐直接用save()的 try/catch。
3.2 内建验证器：长度、枚举、数字范围
String 类型可以加minlength、maxlength、match：
name: { type: String, required: true, minlength: 5, maxlength: 255, // match: /^[a-zA-Z]/, },枚举用enum，限定值只能是列表里的几个：
category: { type: String, required: true, enum: ['web', 'mobile', 'network'], },数字类型有min、max。这里有个经典坑：required如果写成箭头函数，this会指向最近的外层对象而不是当前文档，导致条件必填失效。必须用普通函数：
price: { type: Number, required: function () { return this.isPublished; }, min: 20, max: 200, },这段的意思是：只有当isPublished为 true 时，price才必填。用普通函数才能拿到当前 course 实例的this。
3.3 自定义 validator 与异步 validator
tags是数组，required对它没用——你传一个空数组[]也能通过，因为空数组不是undefined。所以要自己写 validator：
tags: { type: Array, validate: { validator: function (v) { return v && v.length > 0; }, message: 'A course should have at least one tag', }, },如果验证逻辑要读数据库或调远端服务，就改成异步 validator。注意新版 mongoose 里isAsync已经不需要显式写了，返回 Promise 或使用 callback 都能被识别：
tags: { type: Array, validate: { validator: function (v) { return new Promise((resolve) => { // 模拟异步检查，比如查标签是否在允许列表里 setTimeout(() => resolve(v && v.length > 0), 50); }); }, message: 'A course should have at least one tag', }, },3.4 错误定位：遍历 ex.errors
验证失败时，ex.message只给你一句概括，真正有用的是ex.errors。每个字段的错误单独挂在这个对象上：
try { const result = await course.save(); console.log(result); } catch (ex) { for (const field in ex.errors) { console.log(`[${field}] ${ex.errors[field].message}`); } }这样你能精确知道是哪个字段、哪条规则挂了。如果字段多，还可以打印ex.errors[field].kind和ex.errors[field].path，前者是验证器类型（required、minlength、user defined等），后者是字段路径。
3.5 Schema Type Options：trim、lowercase、get/set
除了验证，Schema 还能做数据清洗。trim去掉字符串前后空格，lowercase/uppercase自动转换大小写：
category: { type: String, required: true, enum: ['web', 'mobile', 'network'], lowercase: true, trim: true, },数字可以用get/set做四舍五入。set在写入时生效，get在读取时生效：
price: { type: Number, required: function () { return this.isPublished; }, min: 20, max: 200, get: (v) => Math.round(v), set: (v) => Math.round(v), },注意get要生效，查询时需要开启toObject({ getters: true })或在 Schema 上配置toJSON: { getters: true }，否则读出来的还是原始小数。
4. 验证请求与成功结果：一次跑通校验链路
把上面的片段拼成一个完整脚本，连本地 MongoDB 跑一遍。假设你的 MongoDB 在mongodb://localhost:27017/validation_demo。
const mongoose = require('mongoose'); const courseSchema = new mongoose.Schema({ name: { type: String, required: true, minlength: 5, maxlength: 255 }, author: String, category: { type: String, required: true, enum: ['web', 'mobile', 'network'], lowercase: true, trim: true, }, tags: { type: Array, validate: { validator: (v) => v && v.length > 0, message: 'A course should have at least one tag', }, }, price: { type: Number, required: function () { return this.isPublished; }, min: 20, max: 200, }, isPublished: Boolean, date: { type: Date, default: Date.now }, }); const Course = mongoose.model('Course', courseSchema); async function run() { await mongoose.connect('mongodb://localhost:27017/validation_demo'); // 用例 1：缺 name，应报 required try { await new Course({ category: 'web', tags: ['js'], isPublished: false }).save(); } catch (ex) { for (const f in ex.errors) console.log(`[case1][${f}] ${ex.errors[f].message}`); } // 用例 2：name 太短，应报 minlength try { await new Course({ name: 'abc', category: 'web', tags: ['js'], isPublished: false }).save(); } catch (ex) { for (const f in ex.errors) console.log(`[case2][${f}] ${ex.errors[f].message}`); } // 用例 3：category 不在枚举内 try { await new Course({ name: 'Node 实战', category: 'desktop', tags: ['js'], isPublished: false }).save(); } catch (ex) { for (const f in ex.errors) console.log(`[case3][${f}] ${ex.errors[f].message}`); } // 用例 4：tags 为空数组，自定义 validator 拦截 try { await new Course({ name: 'Node 实战', category: 'web', tags: [], isPublished: false }).save(); } catch (ex) { for (const f in ex.errors) console.log(`[case4][${f}] ${ex.errors[f].message}`); } // 用例 5：isPublished 为 true 但缺 price，条件必填生效 try { await new Course({ name: 'Node 实战', category: 'web', tags: ['js'], isPublished: true }).save(); } catch (ex) { for (const f in ex.errors) console.log(`[case5][${f}] ${ex.errors[f].message}`); } // 用例 6：全部合法，应成功 const ok = await new Course({ name: 'Node 实战', category: 'WEB', tags: ['js'], price: 99.6, isPublished: true, }).save(); console.log('[case6] saved:', ok._id, 'category=', ok.category, 'price=', ok.price); await mongoose.disconnect(); } run().catch((e) => console.error(e));跑node scripts/validate-demo.js，预期输出大致是：
[case1][name] Path `name` is required. [case2][name] Path `name` (`abc`) is shorter than the minimum allowed length (5). [case3][category] `desktop` is not a valid enum value for path `category`. [case4][tags] A course should have at least one tag [case5][price] Path `price` is required. [case6] saved: 65f... category= web price= 100注意 case6 里我故意传了category: 'WEB'和price: 99.6，输出里category变成了小写web，price变成了100，说明lowercase和set都生效了。到这里，必填、类型、长度、枚举、自定义 validator、条件必填、数据清洗，整条链路一次跑通。
5. 本篇常见错排查
5.1 验证没生效，脏数据还是写进去了
最常见的原因是写入路径绕过了 mongoose Model。比如直接用db.collection('courses').insertOne(...)，或者用Model.collection.insertMany()，这些都不走 Schema 验证。排查方法：在save()前后打日志，确认走的是 Model 实例。另外findOneAndUpdate、updateOne默认也不跑 validator，需要显式加runValidators: true：
await Course.findByIdAndUpdate(id, { $set: { name: 'ab' } }, { new: true, runValidators: true });5.2 required 用箭头函数导致条件必填失效
前面提过，required: () => this.isPublished里的this不是文档实例，结果永远是undefined，条件必填要么恒真要么恒假。改成function () { return this.isPublished; }即可。这个坑在default和validate里同样存在，凡是需要this的地方都别用箭头函数。
5.3 自定义 validator 里拿不到最新值
如果你在 validator 里读this.xxx，注意this指向的是当前文档，但某些更新场景下它可能是旧值。更稳的做法是直接用 validator 的参数v，它一定是当前正在验证的值。需要跨字段验证时，用this.get('otherField')而不是this.otherField。
5.4 异步 validator 报 “Validator failed for path”
异步 validator 如果 Promise reject 或者 callback 传了错误，mongoose 会把它当成验证失败。排查时先确认你的异步逻辑本身没抛异常，再确认返回的是布尔值而不是 undefined。如果异步 validator 里查数据库超时，也会表现为验证失败，日志里要区分是业务校验不过还是基础设施问题。
5.5 enum 报错但值看起来没问题
检查大小写和空格。enum: ['web']遇到'Web'或' web '都会失败。如果你同时配了lowercase: true和trim: true，注意执行顺序——清洗在验证之前还是之后，不同 mongoose 版本行为有差异，实测下来把清洗配在字段上、验证也配在同一字段，通常清洗先生效。拿不准就打印ex.errors.category.value看实际参与验证的值是什么。
6. 把校验链路接进日常编码流程
Schema 写完之后，真正花时间的是反复调 validator 和读报错。我的做法是把scripts/validate-demo.js当成一个可回归的用例集，每加一条校验规则就补一个 case，跑一遍看输出是否符合预期。遇到ex.errors里看不懂的kind或堆栈，直接把错误贴到模型对话里问，比翻文档快。入口还是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。
如果你要长期做后端编码、写 Agent 或者批量生成 Schema 模板，可以看下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合把这类重复性的校验代码生成和排障动作固化下来。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理还是走 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。API 基址统一用 https://taotoken.net/api 。
最后留一个我踩过的坑：别把validate()的返回值和save()混用。validate()成功时返回 undefined，失败时 reject，你没法用if (await course.validate())做判断。要么用 try/catch，要么用 callback 形式，二选一，别两种写法混在一个函数里，否则错误处理会变得很难读。
