1. 从一次本地 CRUD 跑不通说起mongoose 是 Node.js 里操作 MongoDB 最常用的 ODM 库它把「集合」抽象成 Schema把「文档」抽象成 Model 和 Entity让你不用手写原生驱动那套回调也能完成增删改查。这篇面向的是刚接触 Node.js、想在本机把第一个数据模型跑起来的新手从 npm 安装 mongoose、定义 Schema 与 Model到本地 CRUD 验证一条链路走完。适合谁写过一点 JavaScript、装过 Node、但还没真正让数据落进 MongoDB 的人。我试过最典型的翻车场景是这样的npm install mongoose装完mongoose.connect也写了脚本一跑却卡在连接上或者save回调里err一直有值控制台只丢一句超时。问题往往不在 mongoose 本身而在连接串、服务是否启动、以及调用凭证散落在各处难管理。所以这篇除了把 Schema 建模和 CRUD 讲透还会顺带说清楚怎么用 TaoToken 把调用凭证统一管起来避免以后接模型能力时 Key 到处复制。下面按「装依赖 → 连库 → 建模 → 增删改查 → 排错」的顺序来每一步都给可复制的代码你跟着敲就能在本地看到结果。2. TaoToken 前置把调用凭证先收拢在写业务代码之前先把凭证这件事理清楚。TaoToken 是一个统一 Key / API 通道的管理入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。它的价值在于你后面不管是接模型对话、跑 coding plan还是给 Agent 配通道都不用把一堆 Key 硬编码进app.js。具体操作路径很直接。先到控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 建好项目再去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一把 Key。生成后不要写死在代码里放进.env# .env TAOTOKEN_API_KEY你的Key MONGODB_URImongodb://127.0.0.1:27017/mongoose_demo注意.env一定要进.gitignore凭证进仓库是新手最容易犯的错。如果你只是想先验证模型能不能通可以直接用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 试一条请求确认 Key 有效再写进项目。长期要跑编码或 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有对应的套餐说明按需选就行。接入细节和参数以接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 为准别凭记忆猜字段。这一步做完你手里应该有两样东西一把可用的 TaoToken Key一个本地 MongoDB 连接串。接下来进入正题。3. 可复制配置依赖、连接与 Schema 建模3.1 package.json 依赖片段先初始化项目装 mongoose 和 dotenvnpm init -y npm install mongoose dotenv装完package.json的依赖部分大概长这样版本号以你实际安装为准{ name: mongoose-demo, version: 1.0.0, type: commonjs, scripts: { start: node app.js }, dependencies: { dotenv: ^16.4.5, mongoose: ^8.5.0 } }mongoose 8.x 默认已经支持 Promise不需要再手动mongoose.Promise global.Promise老教程里那行可以省掉。3.2 连接配置骨架新建db.js把连接逻辑单独抽出来方便复用// db.js const mongoose require(mongoose); require(dotenv).config(); async function connectDB() { try { await mongoose.connect(process.env.MONGODB_URI, { serverSelectionTimeoutMS: 5000, }); console.log(MongoDB 连接成功); } catch (err) { console.error(MongoDB 连接失败:, err.message); process.exit(1); } } module.exports connectDB;serverSelectionTimeoutMS设成 5000是为了连不上时快速报错而不是默认等 30 秒。本地开发这个值很实用。3.3 Schema 与 Modelmongoose 里三个概念要分清Schema 是骨架只描述字段结构不能直接操作数据库Model 由 Schema 编译而来具备操作能力Entity 是 Model 实例化出来的具体文档用save落库。新建models/user.js// models/user.js const mongoose require(mongoose); const Schema mongoose.Schema; const userSchema new Schema( { username: { type: String, unique: true, required: true }, name: String, password: String, mobile: String, email: String, age: Number, tags: [String], createdAt: { type: Date, default: Date.now }, }, { collection: users } ); module.exports mongoose.model(User, userSchema);字段类型支持字符串、日期、数值、布尔、数组、内嵌文档等。unique: true只是建索引约束真正生效需要索引建好第一次插入重复值不一定立刻报错这点后面排错会讲。4. 验证请求一条可执行的 CRUD 脚本新建app.js把连接、建模、增删改查串起来// app.js const connectDB require(./db); const User require(./models/user); async function main() { await connectDB(); // 增创建并保存 const created await User.create({ username: alice, name: Alice, password: 123456, email: aliceexample.com, age: 22, tags: [node, mongodb], }); console.log(新增成功, _id , created._id.toString()); // 查条件查询 限制数量 排序 const list await User.find({ age: { $gte: 18 } }) .sort({ age: -1 }) .limit(10) .exec(); console.log(查询到, list.length, 条); // 改更新一条 const updated await User.findByIdAndUpdate( created._id, { $set: { name: Alice Chen } }, { new: true } ); console.log(更新后 name , updated.name); // 删删除一条 const removed await User.findByIdAndDelete(created._id); console.log(已删除:, removed ? removed.username : 无匹配); await require(mongoose).disconnect(); } main().catch((err) { console.error(执行出错:, err); process.exit(1); });跑之前确认本地 MongoDB 已启动。用node app.js执行正常输出类似MongoDB 连接成功 新增成功, _id 66f1a2b3c4d5e6f7a8b9c0d1 查询到 1 条 更新后 name Alice Chen 已删除: alice看到这四行说明 Schema 建模和 CRUD 全通了。几个常用查询操作对照一下操作写法说明查全部User.find({})不传条件默认返回所有文档条件查User.find({ age: { $gt: 18 } })$gt大于$lt小于$gte大于等于查一条User.findOne({ username: alice })只返回第一条匹配按 ID 查User.findById(id)只接收_id返回单个文档限制数量User.find({}, null, { limit: 20 })第三个参数是 options排序User.find({}).sort({ age: 1 })1 升序-1 降序5. 本篇常见错排查连不上库报MongooseServerSelectionError。九成是 MongoDB 服务没起或者连接串端口不对。本地默认27017先确认服务在跑再检查.env里的MONGODB_URI有没有写错库名。save回调里err一直有值。先看err.message常见是必填字段缺失或类型不匹配。Schema 里required: true的字段没传插入就会失败。unique: true没拦住重复。唯一索引是异步建的第一次插入时索引可能还没建好。可以手动await User.init()等索引建完再插或者用syncIndexes。查询返回空数组但数据明明在。检查集合名。mongoose 默认把 Model 名User转成复数users如果你手动建过user集合就对不上。上面 Schema 里用collection: users显式指定能避免这个坑。回调风格和 Promise 混用。mongoose 8.x 推荐async/await老教程里的find(cond, callback)也能用但别在同一个调用里既传 callback 又await会拿到 undefined。凭证管理混乱。如果你后面还要接模型能力别把 TaoToken Key 和 MongoDB 连接串混在一个文件里硬编码。统一走.envKey 从 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成接入参数对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 核对。6. 把凭证和模型能力接上本地 CRUD 跑通只是第一步。真实项目里你往往还要在 Node 服务里调模型能力比如给用户输入做摘要、给数据打标签。这时候凭证管理就重要了MongoDB 连接串管数据TaoToken Key 管模型调用两者都放.env代码里只读环境变量。验证模型通道是否可用去模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条测试请求最直观。要长期跑编码或 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有对应方案。接入时如果遇到鉴权或参数报错先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 再回 API Keys 页面确认 Key 状态。一个实用习惯把connectDB和模型调用封装成独立模块app.js只负责编排流程。这样以后换库、换通道改动都集中在一处不会牵一发动全身。mongoose 的 Schema 建模和 CRUD 是地基凭证统一管理是让地基能往上盖楼的前提两件事一起做后面接什么能力都不慌。
1. 从一次本地 CRUD 跑不通说起mongoose 是 Node.js 里操作 MongoDB 最常用的 ODM 库它把「集合」抽象成 Schema把「文档」抽象成 Model 和 Entity让你不用手写原生驱动那套回调也能完成增删改查。这篇面向的是刚接触 Node.js、想在本机把第一个数据模型跑起来的新手从 npm 安装 mongoose、定义 Schema 与 Model到本地 CRUD 验证一条链路走完。适合谁写过一点 JavaScript、装过 Node、但还没真正让数据落进 MongoDB 的人。我试过最典型的翻车场景是这样的npm install mongoose装完mongoose.connect也写了脚本一跑却卡在连接上或者save回调里err一直有值控制台只丢一句超时。问题往往不在 mongoose 本身而在连接串、服务是否启动、以及调用凭证散落在各处难管理。所以这篇除了把 Schema 建模和 CRUD 讲透还会顺带说清楚怎么用 TaoToken 把调用凭证统一管起来避免以后接模型能力时 Key 到处复制。下面按「装依赖 → 连库 → 建模 → 增删改查 → 排错」的顺序来每一步都给可复制的代码你跟着敲就能在本地看到结果。2. TaoToken 前置把调用凭证先收拢在写业务代码之前先把凭证这件事理清楚。TaoToken 是一个统一 Key / API 通道的管理入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。它的价值在于你后面不管是接模型对话、跑 coding plan还是给 Agent 配通道都不用把一堆 Key 硬编码进app.js。具体操作路径很直接。先到控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 建好项目再去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一把 Key。生成后不要写死在代码里放进.env# .env TAOTOKEN_API_KEY你的Key MONGODB_URImongodb://127.0.0.1:27017/mongoose_demo注意.env一定要进.gitignore凭证进仓库是新手最容易犯的错。如果你只是想先验证模型能不能通可以直接用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 试一条请求确认 Key 有效再写进项目。长期要跑编码或 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有对应的套餐说明按需选就行。接入细节和参数以接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 为准别凭记忆猜字段。这一步做完你手里应该有两样东西一把可用的 TaoToken Key一个本地 MongoDB 连接串。接下来进入正题。3. 可复制配置依赖、连接与 Schema 建模3.1 package.json 依赖片段先初始化项目装 mongoose 和 dotenvnpm init -y npm install mongoose dotenv装完package.json的依赖部分大概长这样版本号以你实际安装为准{ name: mongoose-demo, version: 1.0.0, type: commonjs, scripts: { start: node app.js }, dependencies: { dotenv: ^16.4.5, mongoose: ^8.5.0 } }mongoose 8.x 默认已经支持 Promise不需要再手动mongoose.Promise global.Promise老教程里那行可以省掉。3.2 连接配置骨架新建db.js把连接逻辑单独抽出来方便复用// db.js const mongoose require(mongoose); require(dotenv).config(); async function connectDB() { try { await mongoose.connect(process.env.MONGODB_URI, { serverSelectionTimeoutMS: 5000, }); console.log(MongoDB 连接成功); } catch (err) { console.error(MongoDB 连接失败:, err.message); process.exit(1); } } module.exports connectDB;serverSelectionTimeoutMS设成 5000是为了连不上时快速报错而不是默认等 30 秒。本地开发这个值很实用。3.3 Schema 与 Modelmongoose 里三个概念要分清Schema 是骨架只描述字段结构不能直接操作数据库Model 由 Schema 编译而来具备操作能力Entity 是 Model 实例化出来的具体文档用save落库。新建models/user.js// models/user.js const mongoose require(mongoose); const Schema mongoose.Schema; const userSchema new Schema( { username: { type: String, unique: true, required: true }, name: String, password: String, mobile: String, email: String, age: Number, tags: [String], createdAt: { type: Date, default: Date.now }, }, { collection: users } ); module.exports mongoose.model(User, userSchema);字段类型支持字符串、日期、数值、布尔、数组、内嵌文档等。unique: true只是建索引约束真正生效需要索引建好第一次插入重复值不一定立刻报错这点后面排错会讲。4. 验证请求一条可执行的 CRUD 脚本新建app.js把连接、建模、增删改查串起来// app.js const connectDB require(./db); const User require(./models/user); async function main() { await connectDB(); // 增创建并保存 const created await User.create({ username: alice, name: Alice, password: 123456, email: aliceexample.com, age: 22, tags: [node, mongodb], }); console.log(新增成功, _id , created._id.toString()); // 查条件查询 限制数量 排序 const list await User.find({ age: { $gte: 18 } }) .sort({ age: -1 }) .limit(10) .exec(); console.log(查询到, list.length, 条); // 改更新一条 const updated await User.findByIdAndUpdate( created._id, { $set: { name: Alice Chen } }, { new: true } ); console.log(更新后 name , updated.name); // 删删除一条 const removed await User.findByIdAndDelete(created._id); console.log(已删除:, removed ? removed.username : 无匹配); await require(mongoose).disconnect(); } main().catch((err) { console.error(执行出错:, err); process.exit(1); });跑之前确认本地 MongoDB 已启动。用node app.js执行正常输出类似MongoDB 连接成功 新增成功, _id 66f1a2b3c4d5e6f7a8b9c0d1 查询到 1 条 更新后 name Alice Chen 已删除: alice看到这四行说明 Schema 建模和 CRUD 全通了。几个常用查询操作对照一下操作写法说明查全部User.find({})不传条件默认返回所有文档条件查User.find({ age: { $gt: 18 } })$gt大于$lt小于$gte大于等于查一条User.findOne({ username: alice })只返回第一条匹配按 ID 查User.findById(id)只接收_id返回单个文档限制数量User.find({}, null, { limit: 20 })第三个参数是 options排序User.find({}).sort({ age: 1 })1 升序-1 降序5. 本篇常见错排查连不上库报MongooseServerSelectionError。九成是 MongoDB 服务没起或者连接串端口不对。本地默认27017先确认服务在跑再检查.env里的MONGODB_URI有没有写错库名。save回调里err一直有值。先看err.message常见是必填字段缺失或类型不匹配。Schema 里required: true的字段没传插入就会失败。unique: true没拦住重复。唯一索引是异步建的第一次插入时索引可能还没建好。可以手动await User.init()等索引建完再插或者用syncIndexes。查询返回空数组但数据明明在。检查集合名。mongoose 默认把 Model 名User转成复数users如果你手动建过user集合就对不上。上面 Schema 里用collection: users显式指定能避免这个坑。回调风格和 Promise 混用。mongoose 8.x 推荐async/await老教程里的find(cond, callback)也能用但别在同一个调用里既传 callback 又await会拿到 undefined。凭证管理混乱。如果你后面还要接模型能力别把 TaoToken Key 和 MongoDB 连接串混在一个文件里硬编码。统一走.envKey 从 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成接入参数对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 核对。6. 把凭证和模型能力接上本地 CRUD 跑通只是第一步。真实项目里你往往还要在 Node 服务里调模型能力比如给用户输入做摘要、给数据打标签。这时候凭证管理就重要了MongoDB 连接串管数据TaoToken Key 管模型调用两者都放.env代码里只读环境变量。验证模型通道是否可用去模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条测试请求最直观。要长期跑编码或 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有对应方案。接入时如果遇到鉴权或参数报错先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 再回 API Keys 页面确认 Key 状态。一个实用习惯把connectDB和模型调用封装成独立模块app.js只负责编排流程。这样以后换库、换通道改动都集中在一处不会牵一发动全身。mongoose 的 Schema 建模和 CRUD 是地基凭证统一管理是让地基能往上盖楼的前提两件事一起做后面接什么能力都不慌。
