 把 MongooseDocuments 转成 JS Object 再改 JSON 返回)
1. 为什么 mongoose 查出来的 JSON 改不动：MongooseDocuments 与 JS Object 的类型差异
如果你用 Node.js + mongoose 写过接口，大概率遇到过这种诡异场景：await User.find({ status: 1 })拿到结果，想给每条记录补一个avatarUrl字段，或者把_id改名成id再返回给前端，代码写下去没报错，但返回的 JSON 里那个字段就是死活不出现。你打印console.log(doc)看着明明有值，res.json(doc)出去又没了。这不是玄学，是 mongoose 的文档对象模型在“保护”你。
核心原因一句话：find()、findOne()、findById()默认返回的不是普通 JavaScript 对象，而是MongooseDocument实例。它是 mongoose 基于 Schema 包装出来的类实例，身上挂了一堆内部属性（$__、$isNew、_doc、$__.activePaths等），真正的数据藏在_doc里。你直接doc.newField = 'x'，mongoose 会走它的 setter 逻辑：如果 Schema 里没定义newField，严格模式下这个赋值会被静默丢弃，或者只写进内存但不进入toJSON()的输出路径。所以你“改了”，但序列化时被过滤掉了。
我试过最典型的坑：Schema 定义时开了strict: true（默认就是 true），然后想动态加字段。代码大概长这样：
const user = await User.findById(id); user.tempToken = 'abc'; // 想临时塞个字段 res.json(user); // 返回里根本没有 tempToken打印user.tempToken是'abc'，但JSON.stringify(user)里没有。因为toJSON()只序列化 Schema 里声明过的 path。这就是MongooseDocument和纯 JS Object 的本质区别：前者是“带行为、带校验、带默认值、带虚拟字段”的活对象，后者是“一堆键值对”的死数据。
那什么时候需要纯数据？三种高频场景。第一，聚合多个集合的结果拼装返回，比如查用户再查订单，想合并成一个对象。第二，字段重命名/裁剪，前端要id不要_id，要nickname不要username。第三，把查询结果当普通对象传给模板引擎、缓存层（Redis）、或者再喂给另一个函数做计算。这些场景下，MongooseDocument的“智能”反而成了负担。
lean()就是干这个的：它告诉 mongoose “别给我包装了，直接返回原始 BSON 转成的普通 JS 对象”。加上之后，find()返回的是Array<Object>，findOne()返回Object | null，你可以随便增删改字段，res.json()出去就是你改完的样子。代价是：虚拟字段（virtuals）、getter/setter、save()方法、populate()的某些行为会失效或需要额外处理。所以lean()不是无脑加，得看边界。
这篇就按“问题定位 → 前置准备 → 可复制配置 → 验证请求 → 报错排查 → 联调落地”的顺序走一遍，中间会结合 TaoToken 的统一 Key/API 通道做接口联调演示，让你把“改不动”的问题彻底钉死。
2. 接入前的环境与 TaoToken 统一 Key/API 通道准备
在动手改lean()之前，先把联调环境搭好。很多同学本地 mongoose 跑通了，一接真实 API 就 401，问题往往出在 Key 和 Base URL 没对齐。这里我用 TaoToken 的统一通道来演示，因为它把模型调用收敛成一个 Base URL + 一个 Key，省得你在多个供应商之间来回切配置。
先明确三个东西，后面所有配置都围绕它们：
| 项目 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 所有请求走这个入口，不要带 UTM |
| API Key | 在控制台生成 | 形如sk-...，只显示一次，存好 |
| Model ID | 按需选 | 比如claude-sonnet-4-5、gpt-4o等 |
获取 Key 的路径：打开https://taotoken.net/console，登录后在 API Keys 页面点创建，复制出来。注意这个 Key 是敏感信息，别提交到 Git，建议放.env里，用dotenv加载。
npm init -y npm install mongoose express dotenv node-fetch项目结构建议这样，别把所有东西堆一个文件：
project/ ├── .env ├── server.js ├── models/ │ └── user.js └── routes/ └── users.js.env内容：
TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api MONGO_URI=mongodb://127.0.0.1:27017/lean_demo这里有个容易踩的点：Base URL 结尾不要带斜杠，代码里拼接时统一用${BASE_URL}/v1/...这种形式，否则会出现//v1双斜杠，部分网关会 404。TaoToken 的 API 入口就是https://taotoken.net/api，文档在https://taotoken.net/doc，遇到路径不确定先去文档核对。
mongoose 连接部分：
// server.js require('dotenv').config(); const mongoose = require('mongoose'); mongoose.connect(process.env.MONGO_URI) .then(() => console.log('mongo connected')) .catch(err => console.error('mongo error', err));Schema 定义时故意留一个“想动态加字段”的场景，方便后面验证lean()的效果：
// models/user.js const mongoose = require('mongoose'); const userSchema = new mongoose.Schema({ username: String, email: String, status: { type: Number, default: 1 } }, { strict: true, timestamps: true }); module.exports = mongoose.model('User', userSchema);注意strict: true是默认值，我显式写出来是为了提醒你：这个模式下，非 Schema 字段的赋值会被丢弃。这正是“改不动”的根源之一。环境准备好后，先插几条测试数据，后面验证才有东西可查。
3. 可复制的 lean() 查询写法与返回结构对比
这一节是核心，直接上可复制的代码。先看“不加 lean”和“加 lean”的返回结构差异，你就能明白为什么改不动。
不加lean()的写法：
// routes/users.js const express = require('express'); const router = express.Router(); const User = require('../models/user'); router.get('/users/raw', async (req, res) => { const users = await User.find({ status: 1 }); // users 是 Array<MongooseDocument> users.forEach(u => { u.displayName = u.username + '@demo'; // 想加字段 }); res.json(users); // displayName 不会出现 }); module.exports = router;加lean()的写法：
router.get('/users/lean', async (req, res) => { const users = await User.find({ status: 1 }).lean(); // users 是 Array<plain Object> const shaped = users.map(u => ({ id: u._id.toString(), name: u.username, displayName: `${u.username}@demo`, email: u.email })); res.json(shaped); });对比一下返回结构。不加lean()时，res.json(users)输出大概是这样（简化）：
[ { "_id": "65f1...", "username": "alice", "email": "a@x.com", "status": 1, "createdAt": "2024-03-01T...", "updatedAt": "2024-03-01T...", "__v": 0 } ]你手动加的displayName不在里面。加lean()后，users本身就是普通对象数组，map出来的shaped完全由你控制：
[ { "id": "65f1...", "name": "alice", "displayName": "alice@demo", "email": "a@x.com" } ]_id是 ObjectId 类型，lean()后它还是 ObjectId，直接res.json会被序列化成字符串，但如果你要参与字符串拼接或比较，最好显式.toString()。这是lean()后常见的第二个坑。
findOne场景同理：
const user = await User.findOne({ username: 'alice' }).lean(); if (!user) return res.status(404).json({ error: 'not found' }); user.role = 'admin'; // 直接加，能生效 res.json(user);lean()还支持传参，比如lean({ virtuals: true })可以把虚拟字段带出来，但前提是你 Schema 里定义了 virtuals 并且装了对应插件。默认lean()不带 virtuals，这点要记牢。
再给一个“聚合 + lean”的组合写法，实际项目里很常见：
const result = await User.aggregate([ { $match: { status: 1 } }, { $project: { username: 1, email: 1 } } ]); // aggregate 本身返回的就是 plain object，不需要 lean注意：aggregate()返回的已经是普通对象，加lean()会报错或无效，别画蛇添足。lean()只对find、findOne、findById这类 Query 有效。
如果你用 TypeScript，lean()后类型会变成FlattenMaps<...>，需要断言或定义返回类型，否则u.displayName会报“属性不存在”。这是类型层面的坑，运行时没问题。
4. 验证请求：从本地 curl 到 TaoToken 通道联调
写完代码得验证。先本地起服务：
node server.js用 curl 打两个接口对比：
curl http://localhost:3000/users/raw curl http://localhost:3000/users/lean第一个返回里没有你加的字段，第二个有。这一步确认lean()生效。
接下来做 TaoToken 通道联调。思路是：把lean()查出来的用户数据，作为上下文拼进 prompt，调用 TaoToken 的模型接口，生成一段个性化文案，再返回给前端。这样既验证了lean()改数据的能力，又验证了 API 通道。
先封装一个调用函数：
// utils/taotoken.js const fetch = require('node-fetch'); async function chat(messages, model = 'claude-sonnet-4-5') { const res = await fetch(`${process.env.TAOTOKEN_BASE_URL}/v1/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.TAOTOKEN_API_KEY}` }, body: JSON.stringify({ model, messages }) }); if (!res.ok) { const text = await res.text(); throw new Error(`taotoken ${res.status}: ${text}`); } const data = await res.json(); return data.choices[0].message.content; } module.exports = { chat };然后在路由里用：
const { chat } = require('../utils/taotoken'); router.get('/users/greet', async (req, res) => { const users = await User.find({ status: 1 }).lean(); const shaped = users.map(u => ({ id: u._id.toString(), name: u.username, displayName: `${u.username}@demo` })); const prompt = `为以下用户各写一句 20 字以内的欢迎语，返回 JSON 数组：${JSON.stringify(shaped)}`; const content = await chat([{ role: 'user', content: prompt }]); res.json({ users: shaped, greeting: content }); });验证：
curl http://localhost:3000/users/greet成功的话你会看到users是你改过的结构，greeting是模型返回的文案。如果这里报 401，说明 Key 不对；报local proxy failed之类，说明网络出口或 Base URL 有问题，检查TAOTOKEN_BASE_URL是否写成https://taotoken.net/api，别多加/v1或斜杠。
想快速验证模型通道是否通，也可以直接用模型对话页面https://taotoken.net/model-chat发一条消息，确认 Key 有效后再回到代码。长期做编码和 Agent 的话，可以看下 Coding Plan 页面https://taotoken.net/coding-plan，把常用模型和额度规划好。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把真实会撞到的报错列出来，对照着查。
401 Unauthorized。最常见。原因有三：Key 没读到（.env没加载或变量名拼错）、Key 前后有空格、Key 已失效。排查：console.log(process.env.TAOTOKEN_API_KEY?.slice(0, 8))看前几位对不对。注意dotenv要在require其他模块之前调用，否则环境变量还没注入。
local proxy failed / ECONNREFUSED。通常是 Base URL 写错，或者本地网络出口不通。检查TAOTOKEN_BASE_URL是不是https://taotoken.net/api，别写成http，别带端口。如果你在容器里跑，确认容器能出网。
Cannot read properties of undefined (reading 'choices')。说明data.choices是 undefined，一般是响应体不是预期结构。可能原因：请求路径不对（比如漏了/v1/chat/completions），或者返回的是错误 JSON。加一行console.log(JSON.stringify(data))看实际返回。也有可能是模型 ID 写错，网关返回了错误对象。
OAuth / token 过期类报错。如果你用的是某些需要 OAuth 的客户端（比如 Claude Code 相关配置），Key 和 OAuth 是两套东西。用 TaoToken 的 Key 通道时，走Authorization: Bearer，不要混用 OAuth 流程。配置 Claude Code 时，Base URL 填https://taotoken.net/api，Key 填生成的sk-...，Model ID 填具体模型名，三件套缺一不可。文档在https://taotoken.net/doc，配置项以文档为准。
lean() 后 populate 失效。lean()和populate()可以一起用，但lean()后 populate 出来的子文档也是普通对象，虚拟字段和 getter 不生效。如果发现 populate 的字段是 null，检查populate的路径拼写和 Schema 里的ref是否一致。
改了字段但 res.json 还是没有。先确认你加的是lean()之后的对象，而不是lean()之前的。顺序错了，改的还是MongooseDocument。另外确认没有在toJSON里做二次过滤。
ObjectId 比较失败。lean()后_id还是 ObjectId，用===和字符串比较永远 false。统一.toString()或用String(u._id)。
把这几类报错对照一遍，基本能覆盖 90% 的“改不动”和“联调失败”场景。
6. 把 lean() 结果接到统一通道：长期编码与 Agent 场景的落地建议
最后说落地。lean()解决的是“数据可改”的问题，TaoToken 统一通道解决的是“模型调用配置分散”的问题，两者结合，适合做接口层的 AI 增强。比如用户列表接口，查出来用lean()整形，再批量生成个性化推荐语、摘要、标签，一次性返回给前端。这种模式在内容平台、CRM、客服系统里很常见。
长期做编码和 Agent 的话，建议把模型调用收敛到一个utils/taotoken.js，所有路由都走它，Key 和 Base URL 只在一处配置。这样换模型、调额度、排查 401 都只改一个地方。需要看额度和用量去控制台https://taotoken.net/console，需要生成新 Key 去https://taotoken.net/api-keys，接入细节查文档https://taotoken.net/doc。
再给一个实用技巧：lean()之后如果还要save()，是做不到的，因为普通对象没有save方法。这时候要么用findOneAndUpdate直接更新，要么把改好的字段用updateOne写回。别想着“先 lean 改了再 save”，会报user.save is not a function。
还有一个边界：lean()会跳过 Schema 的 getter，如果你依赖 getter 做格式化（比如日期转字符串），lean()后拿到的是原始 Date 对象，需要自己格式化。这是取舍，不是 bug。
实测下来，把lean()用在“只读 + 整形 + 返回”的查询上最合适，用在“查出来还要改数据库”的场景要谨慎。接口联调时，先用curl确认本地返回结构，再打 TaoToken 通道确认模型返回，两步都过，问题基本就定位完了。
