1. mongoskin aggregate group 到底解决什么问题如果你正在维护一个 Node.js 老项目数据库层用的是 mongoskin最近又接到「按年月统计用户注册量」「按分类统计水果销量」这类需求那你大概率会碰到aggregate加$group的组合。mongoskin 本身是对原生 MongoDB Driver 的薄封装它没有 ORM 那套链式 API写聚合管道时全靠手拼数组稍不留神就是err和空数组二选一。这篇内容面向 Node.js 后端开发者聚焦 mongoskin 里 aggregate group 聚合管道的落地配置。我会交付三样东西可复制的 mongoskin 连接与 group 聚合代码骨架、TaoToken 统一 Key/API 通道的 settings.json 配置片段、以及聚合结果校验与报错排查动作。适合谁适合手上跑着 Express/Koa mongoskin、需要快速把统计接口跑通、又不想大改数据访问层的人。先说清楚 mongoskin 的定位。它把db.collection(user).aggregate([...], callback)这种调用方式保留下来管道数组原样透传给 MongoDB。也就是说$match、$group、$sort、$project这些 stage 的写法跟你在 mongosh 里写的一模一样区别只在回调风格和连接管理。理解这一点后面所有配置都是围绕「怎么把管道拼对 怎么把连接管好」展开。我试过在同一个项目里混用 mongoskin 和官方 driver结论是没必要但前提是你得把连接池和错误回调处理干净。下面从环境准备开始一步步把骨架搭起来。2. TaoToken 统一 Key 与 API 通道前置配置在写聚合代码之前先把模型调用通道配好。很多统计接口跑通之后下一步就是接一个「自然语言查数据」或者「报表摘要生成」的能力这时候如果每个服务各自管一套 Key维护成本会很高。TaoToken 的做法是提供一个统一的 API 入口你只需要在配置文件里维护一份 Key 和 base URL。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串带进去。统一 Key 的核心价值在于你的 Node 服务、脚本、CI 任务都读同一份 settings.json换 Key 只改一处。下面是一个可直接落地的配置片段放在项目根目录的config/settings.json{ taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的统一Key, defaultModel: claude-sonnet-4-5, timeoutMs: 60000, maxRetries: 2 }, mongo: { uri: mongodb://127.0.0.1:27017/your_db, poolSize: 10 } }读取这份配置的代码建议单独抽一个模块避免散落在业务里// config/index.js const fs require(fs); const path require(path); const raw fs.readFileSync(path.join(__dirname, settings.json), utf-8); const settings JSON.parse(raw); module.exports { taotoken: settings.taotoken, mongo: settings.mongo };注意apiKey 不要硬编码进业务文件也不要提交到公开仓库。本地开发可以用环境变量覆盖生产环境走密钥管理服务。如果你后续要做长期编码或 Agent 类任务可以了解 Coding Plan 通道如果只是验证模型对话效果用模型对话入口即可接入和排障相关的文档在接入文档里能查到。这几个入口按需选择不要一股脑全接。3. mongoskin 连接与 group 聚合代码骨架现在进入正题。先装依赖npm install mongoskin --savemongoskin 的连接方式有两种一种是mongoskin.db(uri)一种是mongoskin.db(uri, options)。推荐后者把连接池参数显式写出来// db/mongo.js const mongoskin require(mongoskin); const config require(../config); const db mongoskin.db(config.mongo.uri, { native_parser: true, poolSize: config.mongo.poolSize, socketOptions: { keepAlive: 1, connectTimeoutMS: 10000 } }); module.exports db;接下来是聚合骨架。参考原始需求里的两个统计场景我把它整理成可复用的函数注意回调里先判err再处理data// service/statistics.js const db require(../db/mongo); // 按年月统计用户注册量 exports.userStatistics function (callback) { const fromDate new Date(2015-01-01T14:56:59.301Z); db.collection(user).aggregate([ { $match: { createDate: { $gte: fromDate } } }, { $group: { _id: { year: { $year: $createDate }, month: { $month: $createDate } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); }; // 按年月统计 apple 分类的水果数量 exports.fruitStatistics function (callback) { db.collection(fruit).aggregate([ { $match: { category: apple } }, { $group: { _id: { year: { $year: $datetime }, month: { $month: $datetime } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); };这两个函数的骨架是一样的$match先过滤$group按时间维度分组并计数$sort保证输出顺序稳定。区别只在集合名、时间字段名和过滤条件。如果你想让骨架更通用可以抽一个工厂函数// service/aggregateFactory.js const db require(../db/mongo); function groupByMonth(collectionName, dateField, matchStage, callback) { db.collection(collectionName).aggregate([ { $match: matchStage }, { $group: { _id: { year: { $year: $ dateField }, month: { $month: $ dateField } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); } module.exports { groupByMonth };调用时const { groupByMonth } require(./aggregateFactory); groupByMonth(user, createDate, { createDate: { $gte: new Date(2015-01-01) } }, function (err, data) { if (err) { console.error(聚合失败:, err.message); return; } console.log(统计结果:, JSON.stringify(data, null, 2)); });这样新增统计维度时只要传集合名、时间字段和过滤条件不用重复写管道。4. 验证请求与成功结果代码写完先别急着接路由用一段独立脚本验证聚合是否返回预期结构// scripts/verifyAggregate.js const { userStatistics } require(../service/statistics); userStatistics(function (err, data) { if (err) { console.error(执行失败:, err); process.exit(1); } console.log(返回条数:, data.length); console.log(首条样例:, JSON.stringify(data[0], null, 2)); process.exit(0); });运行node scripts/verifyAggregate.js成功时你会看到类似输出返回条数: 12 首条样例: { _id: { year: 2015, month: 1 }, count: 37 }_id里嵌套 year/monthcount是聚合计数这就是$group的标准输出形态。如果返回条数是 0先别怀疑代码去数据库里确认createDate字段是不是真的存在、类型是不是 Date。mongoskin 不会帮你做类型转换字符串日期和 Date 类型在$gte比较下结果完全不同。再验证一下 TaoToken 通道是否可用用一个最小请求确认 Key 和 baseUrl 配置正确// scripts/verifyTaotoken.js const https require(https); const config require(../config); const payload JSON.stringify({ model: config.taotoken.defaultModel, messages: [{ role: user, content: 回复 ok 两个字母即可 }], max_tokens: 16 }); const url new URL(config.taotoken.baseUrl /v1/messages); const options { hostname: url.hostname, path: url.pathname, method: POST, headers: { Content-Type: application/json, x-api-key: config.taotoken.apiKey, anthropic-version: 2023-06-01 } }; const req https.request(options, function (res) { let body ; res.on(data, function (chunk) { body chunk; }); res.on(end, function () { console.log(状态码:, res.statusCode); console.log(响应:, body.slice(0, 200)); }); }); req.on(error, function (e) { console.error(请求异常:, e.message); }); req.write(payload); req.end();状态码 200 且响应里能看到内容说明统一 Key 通道是通的。这一步和聚合验证是两条独立的链路分开排查能快速定位问题出在数据库层还是模型层。5. 本篇常见错排查聚合跑不通九成问题集中在下面几类。我按出现频率排一下。第一类TypeError: db.collection(...).aggregate is not a function。这通常是因为 mongoskin 版本太老或者你误用了mongoskin.db()返回的对象直接调 aggregate。正确姿势是db.collection(name).aggregate(...)collection 对象上才有 aggregate 方法。第二类回调里data是undefined。检查你的回调签名mongoskin 的 aggregate 回调是(err, data)如果你写成(data)就会把 err 当 data。另外确认没有在$group里引用不存在的字段引用不存在的字段不会报错但分组结果会全部落到_id: null下。第三类$match过滤后结果为空。最常见的原因是日期类型不匹配。数据库里存的是 ISO 字符串你传的是 Date 对象比较会失败。用 mongosh 先确认字段类型db.user.findOne({}, { createDate: 1 })如果返回的是字符串要么在写入时统一转 Date要么在聚合前用$toDate转换MongoDB 4.0 支持{ $addFields: { createDateObj: { $toDate: $createDate } } }, { $group: { _id: { year: { $year: $createDateObj } }, count: { $sum: 1 } } }第四类TaoToken 请求返回 401。先确认 apiKey 没有多余空格再确认 baseUrl 是https://taotoken.net/api而不是带 UTM 的完整地址。请求头字段名也要对Anthropic 风格用x-api-key别写成Authorization: Bearer。第五类连接池耗尽导致聚合超时。mongoskin 默认 poolSize 较小高并发统计接口下容易排队。把 poolSize 调到 10 以上并确认每个请求结束后没有泄漏连接。聚合本身是重操作建议对统计接口加缓存别每次请求都打数据库。提示排查顺序建议「先数据库后通道」。聚合结果不对先看数据数据没问题再看代码代码没问题再查 Key 配置。反过来查容易绕远路。6. 后续接入与通道选择骨架跑通之后下一步通常是把它接到真实路由上或者给统计结果加一层自然语言摘要。这时候通道选择就有讲究了如果你只是偶尔调一次模型做摘要用模型对话入口验证效果就够了如果你要把编码辅助、Agent 任务长期跑起来Coding Plan 更合适接入过程中遇到鉴权、参数、报错码的问题直接翻接入文档比在群里问快得多。统一 Key 的好处在这时候体现出来统计服务、摘要服务、CI 脚本读同一份 settings.json换 Key 只改一个文件。API Keys 管理页面可以集中查看和轮换不用挨个服务改配置。最后留一个实用习惯每次改完聚合管道先用scripts/verifyAggregate.js跑一遍确认返回结构再提交。聚合管道是数组多一个逗号少一个括号都不会报语法错但结果会静默变空靠肉眼 review 很容易漏。把验证脚本当成聚合代码的单元测试能省掉大量「上线后才发现统计是 0」的时间。
mongoskin aggregate group 实战：TaoToken 统一 Key 接入与聚合管道配置骨架
1. mongoskin aggregate group 到底解决什么问题如果你正在维护一个 Node.js 老项目数据库层用的是 mongoskin最近又接到「按年月统计用户注册量」「按分类统计水果销量」这类需求那你大概率会碰到aggregate加$group的组合。mongoskin 本身是对原生 MongoDB Driver 的薄封装它没有 ORM 那套链式 API写聚合管道时全靠手拼数组稍不留神就是err和空数组二选一。这篇内容面向 Node.js 后端开发者聚焦 mongoskin 里 aggregate group 聚合管道的落地配置。我会交付三样东西可复制的 mongoskin 连接与 group 聚合代码骨架、TaoToken 统一 Key/API 通道的 settings.json 配置片段、以及聚合结果校验与报错排查动作。适合谁适合手上跑着 Express/Koa mongoskin、需要快速把统计接口跑通、又不想大改数据访问层的人。先说清楚 mongoskin 的定位。它把db.collection(user).aggregate([...], callback)这种调用方式保留下来管道数组原样透传给 MongoDB。也就是说$match、$group、$sort、$project这些 stage 的写法跟你在 mongosh 里写的一模一样区别只在回调风格和连接管理。理解这一点后面所有配置都是围绕「怎么把管道拼对 怎么把连接管好」展开。我试过在同一个项目里混用 mongoskin 和官方 driver结论是没必要但前提是你得把连接池和错误回调处理干净。下面从环境准备开始一步步把骨架搭起来。2. TaoToken 统一 Key 与 API 通道前置配置在写聚合代码之前先把模型调用通道配好。很多统计接口跑通之后下一步就是接一个「自然语言查数据」或者「报表摘要生成」的能力这时候如果每个服务各自管一套 Key维护成本会很高。TaoToken 的做法是提供一个统一的 API 入口你只需要在配置文件里维护一份 Key 和 base URL。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串带进去。统一 Key 的核心价值在于你的 Node 服务、脚本、CI 任务都读同一份 settings.json换 Key 只改一处。下面是一个可直接落地的配置片段放在项目根目录的config/settings.json{ taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的统一Key, defaultModel: claude-sonnet-4-5, timeoutMs: 60000, maxRetries: 2 }, mongo: { uri: mongodb://127.0.0.1:27017/your_db, poolSize: 10 } }读取这份配置的代码建议单独抽一个模块避免散落在业务里// config/index.js const fs require(fs); const path require(path); const raw fs.readFileSync(path.join(__dirname, settings.json), utf-8); const settings JSON.parse(raw); module.exports { taotoken: settings.taotoken, mongo: settings.mongo };注意apiKey 不要硬编码进业务文件也不要提交到公开仓库。本地开发可以用环境变量覆盖生产环境走密钥管理服务。如果你后续要做长期编码或 Agent 类任务可以了解 Coding Plan 通道如果只是验证模型对话效果用模型对话入口即可接入和排障相关的文档在接入文档里能查到。这几个入口按需选择不要一股脑全接。3. mongoskin 连接与 group 聚合代码骨架现在进入正题。先装依赖npm install mongoskin --savemongoskin 的连接方式有两种一种是mongoskin.db(uri)一种是mongoskin.db(uri, options)。推荐后者把连接池参数显式写出来// db/mongo.js const mongoskin require(mongoskin); const config require(../config); const db mongoskin.db(config.mongo.uri, { native_parser: true, poolSize: config.mongo.poolSize, socketOptions: { keepAlive: 1, connectTimeoutMS: 10000 } }); module.exports db;接下来是聚合骨架。参考原始需求里的两个统计场景我把它整理成可复用的函数注意回调里先判err再处理data// service/statistics.js const db require(../db/mongo); // 按年月统计用户注册量 exports.userStatistics function (callback) { const fromDate new Date(2015-01-01T14:56:59.301Z); db.collection(user).aggregate([ { $match: { createDate: { $gte: fromDate } } }, { $group: { _id: { year: { $year: $createDate }, month: { $month: $createDate } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); }; // 按年月统计 apple 分类的水果数量 exports.fruitStatistics function (callback) { db.collection(fruit).aggregate([ { $match: { category: apple } }, { $group: { _id: { year: { $year: $datetime }, month: { $month: $datetime } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); };这两个函数的骨架是一样的$match先过滤$group按时间维度分组并计数$sort保证输出顺序稳定。区别只在集合名、时间字段名和过滤条件。如果你想让骨架更通用可以抽一个工厂函数// service/aggregateFactory.js const db require(../db/mongo); function groupByMonth(collectionName, dateField, matchStage, callback) { db.collection(collectionName).aggregate([ { $match: matchStage }, { $group: { _id: { year: { $year: $ dateField }, month: { $month: $ dateField } }, count: { $sum: 1 } } }, { $sort: { _id: 1 } } ], function (err, data) { if (err) { return callback(err); } return callback(null, data); }); } module.exports { groupByMonth };调用时const { groupByMonth } require(./aggregateFactory); groupByMonth(user, createDate, { createDate: { $gte: new Date(2015-01-01) } }, function (err, data) { if (err) { console.error(聚合失败:, err.message); return; } console.log(统计结果:, JSON.stringify(data, null, 2)); });这样新增统计维度时只要传集合名、时间字段和过滤条件不用重复写管道。4. 验证请求与成功结果代码写完先别急着接路由用一段独立脚本验证聚合是否返回预期结构// scripts/verifyAggregate.js const { userStatistics } require(../service/statistics); userStatistics(function (err, data) { if (err) { console.error(执行失败:, err); process.exit(1); } console.log(返回条数:, data.length); console.log(首条样例:, JSON.stringify(data[0], null, 2)); process.exit(0); });运行node scripts/verifyAggregate.js成功时你会看到类似输出返回条数: 12 首条样例: { _id: { year: 2015, month: 1 }, count: 37 }_id里嵌套 year/monthcount是聚合计数这就是$group的标准输出形态。如果返回条数是 0先别怀疑代码去数据库里确认createDate字段是不是真的存在、类型是不是 Date。mongoskin 不会帮你做类型转换字符串日期和 Date 类型在$gte比较下结果完全不同。再验证一下 TaoToken 通道是否可用用一个最小请求确认 Key 和 baseUrl 配置正确// scripts/verifyTaotoken.js const https require(https); const config require(../config); const payload JSON.stringify({ model: config.taotoken.defaultModel, messages: [{ role: user, content: 回复 ok 两个字母即可 }], max_tokens: 16 }); const url new URL(config.taotoken.baseUrl /v1/messages); const options { hostname: url.hostname, path: url.pathname, method: POST, headers: { Content-Type: application/json, x-api-key: config.taotoken.apiKey, anthropic-version: 2023-06-01 } }; const req https.request(options, function (res) { let body ; res.on(data, function (chunk) { body chunk; }); res.on(end, function () { console.log(状态码:, res.statusCode); console.log(响应:, body.slice(0, 200)); }); }); req.on(error, function (e) { console.error(请求异常:, e.message); }); req.write(payload); req.end();状态码 200 且响应里能看到内容说明统一 Key 通道是通的。这一步和聚合验证是两条独立的链路分开排查能快速定位问题出在数据库层还是模型层。5. 本篇常见错排查聚合跑不通九成问题集中在下面几类。我按出现频率排一下。第一类TypeError: db.collection(...).aggregate is not a function。这通常是因为 mongoskin 版本太老或者你误用了mongoskin.db()返回的对象直接调 aggregate。正确姿势是db.collection(name).aggregate(...)collection 对象上才有 aggregate 方法。第二类回调里data是undefined。检查你的回调签名mongoskin 的 aggregate 回调是(err, data)如果你写成(data)就会把 err 当 data。另外确认没有在$group里引用不存在的字段引用不存在的字段不会报错但分组结果会全部落到_id: null下。第三类$match过滤后结果为空。最常见的原因是日期类型不匹配。数据库里存的是 ISO 字符串你传的是 Date 对象比较会失败。用 mongosh 先确认字段类型db.user.findOne({}, { createDate: 1 })如果返回的是字符串要么在写入时统一转 Date要么在聚合前用$toDate转换MongoDB 4.0 支持{ $addFields: { createDateObj: { $toDate: $createDate } } }, { $group: { _id: { year: { $year: $createDateObj } }, count: { $sum: 1 } } }第四类TaoToken 请求返回 401。先确认 apiKey 没有多余空格再确认 baseUrl 是https://taotoken.net/api而不是带 UTM 的完整地址。请求头字段名也要对Anthropic 风格用x-api-key别写成Authorization: Bearer。第五类连接池耗尽导致聚合超时。mongoskin 默认 poolSize 较小高并发统计接口下容易排队。把 poolSize 调到 10 以上并确认每个请求结束后没有泄漏连接。聚合本身是重操作建议对统计接口加缓存别每次请求都打数据库。提示排查顺序建议「先数据库后通道」。聚合结果不对先看数据数据没问题再看代码代码没问题再查 Key 配置。反过来查容易绕远路。6. 后续接入与通道选择骨架跑通之后下一步通常是把它接到真实路由上或者给统计结果加一层自然语言摘要。这时候通道选择就有讲究了如果你只是偶尔调一次模型做摘要用模型对话入口验证效果就够了如果你要把编码辅助、Agent 任务长期跑起来Coding Plan 更合适接入过程中遇到鉴权、参数、报错码的问题直接翻接入文档比在群里问快得多。统一 Key 的好处在这时候体现出来统计服务、摘要服务、CI 脚本读同一份 settings.json换 Key 只改一个文件。API Keys 管理页面可以集中查看和轮换不用挨个服务改配置。最后留一个实用习惯每次改完聚合管道先用scripts/verifyAggregate.js跑一遍确认返回结构再提交。聚合管道是数组多一个逗号少一个括号都不会报语法错但结果会静默变空靠肉眼 review 很容易漏。把验证脚本当成聚合代码的单元测试能省掉大量「上线后才发现统计是 0」的时间。
