企业官网建设流程全解析

玩MongoDB的聚合，我见过太多人在$project上卡壳。$match用得溜，$group也能凑合，但一到投影这步就开始不顺手——要么不知道该怎么把嵌套文档里的某个字段拎出来，要么想算个"含税总金额"这样的新列，翻半天文档也拼不出表达式。说白了，$project是聚合管道里最容易被低估的阶段，它决定了后面每个阶段看到的数据长什么样。

这篇拿电商订单数据当例子，把聚合中的投影从头到尾捋一遍。先讲清楚$project在管道里扮演什么角色，再拆解常用表达式操作符，最后用真实场景演示完整管道。刚接触聚合的朋友，可以把它当投影实操手册来读；已经用了一阵的老手，重点看第4节的坑和性能建议，应该能帮你在生产环境省点排查时间。

1. 理解聚合投影：$project在管道里到底扮演什么角色

先别急着写语法。很多人在聚合里用不好$project，不是因为不会写，而是没想明白它出现的时机和执行的位置。

1.1 聚合管道中的投影：裁剪、重塑、计算三合一

MongoDB聚合管道是按顺序执行的一组阶段（Stage），每个阶段接收上一阶段的输出文档，处理后传给下一阶段。$project是其中最灵活的阶段之一，职责可以归纳为三件事。

第一，裁剪字段。原始文档可能有二三十个字段，下游只需要三四个。用$project把不需要的字段切掉，后续的$sort、$group、$limit处理的数据量都会变小。打个比方，做菜前先把菜洗干净切好，后面炒起来才快。

第二，重塑结构。把嵌套文档里的深层字段提升到顶层，比如把shipping.addr变成shippingAddr；或者反过来，把多个字段组合成一个新对象。对接外部系统、生成报表时这个能力很关键。

第三，计算派生字段。基于已有字段做运算，生成全新字段值。比如用$total乘以税率得到tax，用$concat拼出订单编号，用$dateToString把日期转成指定格式字符串。

关键点在于：$project执行后，输出的文档结构完全由你定义。没有出现在$project里的字段，除了_id默认保留外，其他一律不保留。这就是它和普通查询投影最大的区别——普通find()投影是"从原文档里挑字段"，$project可以创造原文档里根本不存在的字段。

1.2 $project与find()投影：看着像，机制完全不同

从find()投影转过来的同学容易踩惯性坑，以为能把find的风格直接搬到聚合里。

find()投影长这样：

db.orders.find({}, { user: 1, total: 1 })

返回的文档只有user和total，但你不能在find的投影里生成新字段，也不能对字段做加减乘除。它更适合"挑几列出来看看"这类需求。

$project则完全不是这个思路。它接收表达式，表达式计算结果才是最终字段值：

db.orders.aggregate([ { $project: { user: 1, totalWithTax: { $multiply: ["$total", 1.1] } } } ])

totalWithTax在源文档里不存在，是$project现场算出来的。把$project理解成"可以自由加工字段的映射阶段"，比理解成"投影"准确得多。

另外还有两点容易混淆：find()投影里，包含和排除同样不能混用，但$project的灵活性更强，它允许用表达式覆盖字段。find()投影返回"匹配文档的某个切片"，$project返回"计算后的新文档"。前者查询数据，后者加工数据。

所以临时看一眼数据，用find就够；一旦开始写报表、统计、数据清洗，$project基本躲不掉。

2. 手把手拆解$project语法与表达式操作符

按"规则→数值→字符串/日期→条件→数组"的顺序，把最常用的写法从头过一遍。

2.1 字段包含、排除与新字段的三套用法

$project基础语法就是给字段赋值，但赋什么值决定行为：

{ $project: { _id: 0, user: 1, status: 0, newField: <表达式> } }

三种常见写法和含义：

• 字段值设为1：表示包含该字段。这里的1不是"值等于1"，而是"保留这个字段"的标记。
• 字段值设为0：表示排除该字段。通常配合其他包含字段使用，但排包含规则有讲究，这点第4节细说。
• 字段名等于表达式：用表达式结果生成新字段，表达式里引用字段要用$前缀，比如"$total"。

有个高频误解必须点出来：把字段改名时，不是写成 { newName: "oldName" }，而是要写成 { newName: "$oldName" }。漏了$符号，结果就是把字符串常量"oldName"赋给了newName。这个错误我见过太多次，每次都是调试半天才发现。

再看一个容易踩的点：如果$project里只写了一个字段为1，比如 { user: 1 }，返回结果里除了user，还会带上_id。想去掉_id必须显式写 _id: 0。

2.2 数值计算：从$add到$mod的字段运算

数值运算在报表里出现频率最高。$project中常用的数值运算符：

• $add：求和，{ $add: ["$price", 10] }表示价格加10。
• $subtract：求差，可以算普通数值相减，也能算两个日期的间隔毫秒数。
• $multiply：乘法，支持两个及以上参数。
• $divide：除法，注意除数不能为0。
• $mod：取模。

典型场景是计算含税金额、折扣金额、单价乘以数量求小计。比如订单里每个item有qty和price，想算小计：

{ $project: { subtotal: { $multiply: ["$items.qty", "$items.price"] } } }

提醒一点：这些运算符里的字段会被"转换"为数值参与计算。如果字段是字符串类型的数字，比如"120"，直接做乘法可能报错或返回null。遇到这种情况，先用$toInt或$toDouble转型：

{ $project: { amount: { $multiply: [{ $toDouble: "$totalStr" }, 0.9] } } }

从CSV或外部接口导入的数据里，字符串数字极其常见。千万别跳过类型转换直接算，不然结果很可能是一堆null。

2.3 字符串、日期与条件逻辑表达式

字符串处理常用$concat、$toUpper/$toLower、$substrBytes、$trim。比如拼接订单标签：

{ $project: { orderTag: { $concat: ["ORDER-", { $toString: "$_id" }] } } }

字段路径引用必须写在$concat数组里，普通字符串常量也在数组中，区分方法就是看有没有$前缀。

日期处理方面，最常用的是$year、$month、$dayOfMonth、$hour，以及$dateToString。把日期字段格式化成报表常见的"YYYY-MM-DD HH:mm"：

{ $project: { createTime: { $dateToString: { format: "%Y-%m-%d %H:%M", date: "$createdAt" } } } }

$dateToString只能处理真正的Date类型字段。如果字段存的是字符串"2024-03-10"，直接扔给$dateToString会报错，需要先用$toDate转。

条件逻辑主要靠$cond和$ifNull。$cond是三选结构：

{ $cond: { if: { $gte: ["$total", 100] }, then: "VIP", else: "普通" } }

$ifNull专门处理空字段，字段缺失或为null时走替换值：

{ $project: { remark: { $ifNull: ["$note", "无备注"] } } }

$ifNull在$lookup之后特别实用。外键字段经常缺失，用$ifNull兜个底，后面就不用反复写条件分支了。

2.4 数组操作：从$size到$arrayElemAt

订单里的items是数组，报表里常常要统计数量、取第一个元素、截取前几个。数组运算符正好解决这些问题：

• $size：返回数组长度。
• $arrayElemAt：按索引取元素，支持负数从末尾取。
• $slice：截取子数组，{ $slice: ["$items", 2] }取前两个；{ $slice: ["$items", 1, 2] }从索引1开始取2个。
• $filter：按条件过滤元素。
• $map：对每个元素做变换。

统计商品种类数、取出第一件商品名、截取前两件：

db.orders.aggregate([ { $project: { itemCount: { $size: "$items" }, firstItem: { $arrayElemAt: ["$items.name", 0] }, top2: { $slice: ["$items", 2] } } } ])

$slice有个细节：数组长度小于截取数量时不会报错，只返回实际存在的元素。这在业务上往往正是我们想要的效果。

$filter和$map稍微复杂，但数据处理里非常关键。过滤出数量大于1的商品：

{ $project: { hotItems: { $filter: { input: "$items", as: "it", cond: { $gt: ["$$it.qty", 1] } } } } }

注意$filter里的as变量用双$符引用，这是MongoDB聚合表达式的固定写法。很多人在这一步卡过，其实就是没记住这个规则。

3. 实战：用$project把订单数据变成可读报表

理论知识差不多，下面用一组真实订单数据，把$project从易到难完整演示一遍，你可以在测试库里直接跑。

3.1 准备演示数据：一份电商订单集合

创建orders集合并插入4份订单，涵盖正常、待付款、取消等状态，带嵌套商品数组和收货信息：

db.orders.insertMany([ { _id: 1001, user: "zhangsan", email: "zs@example.com", items: [ { name: "机械键盘", qty: 1, price: 299 }, { name: "显示器支架", qty: 2, price: 89 } ], total: 477, status: "completed", createdAt: ISODate("2024-03-10T09:20:00Z"), shipping: { addr: "北京市朝阳区", fee: 0 } }, { _id: 1002, user: "lisi", email: "ls@example.com", items: [ { name: "USB-C扩展坞", qty: 1, price: 159 } ], total: 159, status: "pending", createdAt: ISODate("2024-03-12T14:05:00Z"), shipping: { addr: "上海市浦东新区", fee: 12 } }, { _id: 1003, user: "wangwu", email: "ww@example.com", items: [ { name: "4K显示器", qty: 1, price: 1999 }, { name: "HDMI线", qty: 3, price: 25 } ], total: 2074, status: "completed", createdAt: ISODate("2024-03-18T18:42:00Z"), shipping: { addr: "广州市天河区", fee: 0 }, note: null }, { _id: 1004, user: "zhaoliu", email: null, items: [], total: 0, status: "cancelled", createdAt: ISODate("2024-03-22T08:10:00Z"), shipping: { addr: "杭州市西湖区", fee: 8 } } ])

这份数据里藏了几个坑点：有email为空、有items空数组、有note为null。后面做投影时，这些会引发意外结果，正好演示怎么处理。

3.2 基础投影：字段裁剪与重命名

裸查orders，你会发现字段很多，下游报表根本用不上。先用$project裁剪到user、total、status：

db.orders.aggregate([ { $project: { _id: 0, user: 1, total: 1, status: 1 } } ])

结果干净很多，每条订单只输出3个业务字段。这个写法适合当管道的第一道闸门，尤其集合文档字段多、又有明细数据的时候。

再做字段重命名，把total改成amount，status改成orderStatus：

db.orders.aggregate([ { $project: { _id: 0, customer: "$user", amount: "$total", orderStatus: "$status" } } ])

输出前三行：

这里用的是"新字段: $旧字段"写法，$符号不能丢。写customer: "$user"是对的，写customer: "user"会让customer值固定为字符串"user"。

3.3 派生字段：计算含税金额和订单等级

接下来是$project最有价值的场景：根据已有字段生成新字段。

先给每笔订单计算10%税费和含税总金额：

db.orders.aggregate([ { $project: { _id: 0, user: 1, total: 1, tax: { $multiply: ["$total", 0.1] }, totalWithTax: { $add: ["$total", { $multiply: ["$total", 0.1] }] } } } ])

tax和totalWithTax都是实时算出来的，没有改动源数据，逻辑全在查询层完成。如果不会用$project，你可能就要在应用层循环遍历订单、逐条计算再写入报表，效率和简洁度完全不同。

再根据total划分订单等级：

db.orders.aggregate([ { $project: { _id: 0, user: 1, total: 1, level: { $cond: { if: { $gte: ["$total", 100] }, then: "VIP", else: "普通" } }, noteDisplay: { $ifNull: ["$note", "无备注"] } } } ])

total>=100时level为VIP，否则为普通。同时用$ifNull把缺失或为null的note统一替换成"无备注"，让输出格式保持整齐。

3.4 数组与嵌套文档：商品数量、第一件商品与收货地址

items是数组，shipping是嵌套文档，这两类结构在报表投影里很常见。

先看数组操作：

db.orders.aggregate([ { $project: { _id: 0, user: 1, itemCount: { $size: "$items" }, firstItemName: { $arrayElemAt: ["$items.name", 0] }, top2Items: { $slice: ["$items.name", 2] } } } ])

$arrayElemAt和$slice都可以直接作用在"数组字段的某个子字段"上，比如"$items.name"，它会先从items里取出name数组再操作。不想改原数组结构、又想快速拿摘要信息时很好用。

有个边界情况：第4条订单items是空数组，$arrayElemAt取值得到null，$size返回0。处理空数组可以用$ifNull兜底，或者配合$cond做条件分支：

firstItemName: { $ifNull: [{ $arrayElemAt: ["$items.name", 0] }, "暂无商品"] }

再看嵌套文档，把shipping.addr和shipping.fee提升到顶层：

db.orders.aggregate([ { $project: { _id: 0, user: 1, shippingAddr: "$shipping.addr", shippingFee: "$shipping.fee" } } ])

"点路径引用"在MongoDB聚合里到处都是，作用就是深入嵌套对象取字段。如果想完整保留嵌套对象，也可以直接写shipping: 1，效果是原样保留这个子文档。

3.5 组合使用：$match + $project + $sort形成完整管道

单独写$project当然没问题，但真实场景里它一定和其他阶段配合。典型报表管道是：先$match过滤completed订单，再$project裁剪计算，再$sort排序，最后$limit分页：

db.orders.aggregate([ { $match: { status: "completed" } }, { $project: { _id: 0, customer: "$user", orderDate: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } }, itemCount: { $size: "$items" }, amountWithFee: { $add: ["$total", "$shipping.fee"] } } }, { $sort: { amountWithFee: -1 } }, { $limit: 2 } ])

执行顺序：先过滤状态，只剩2条completed订单；接着投影生成4个新字段；再按含运费金额降序排序；最后取前2条。

管道顺序有讲究：$match要放在$project前面。因为$match可以利用索引（如果status上有索引），而且先过滤能减少$project处理的数据量。反过来如果先project把status字段丢了，后面的$match就没法用了——投影阶段已经把status剪掉了。这是新手常犯的顺序错误。

4. 常见坑与性能优化实战笔记

投影虽然不难，但实际项目里我确实遇到不少神坑，也帮别人排查过不少。集中整理如下。

4.1 "包含和排除不能混用"这条规则不能碰

在$project里，除了_id之外，不能同时把某些字段设成1、另外一些设成0。这个写法会直接报错：

// 错误的写法 db.orders.aggregate([ { $project: { user: 1, email: 0 } } ])

报错信息类似"FieldPath field names may not be a mix of inclusion and exclusion"。这是MongoDB的铁律，目的是防止语义歧义，因为系统不知道最终文档里该保留哪些字段。

如果你只想要user、去掉email，正确写法是保留user并按需处理其他字段：

// 正确：只保留user和_id db.orders.aggregate([{ $project: { user: 1 } }]) // 如果还要去掉_id db.orders.aggregate([{ $project: { user: 1, _id: 0 } }])

如果想删掉一个不想要的字段、保留其他全部，可以只用0来排除，前提是不同时把别的字段设为1。"全0排除"和"全1包含"二选一，写代码时务必记住。

4.2 _id字段的特殊性：默认保留而常被忽略

$project里_id的默认行为是"保留"，即使你只写了 { user: 1 }，结果里仍然有_id。很多新手第一次跑聚合，看结果里多出_id，以为出了bug，其实不是。

想彻底去掉_id，必须显式声明 _id: 0。在"包含"模式下，你可以单独写 _id: 0；在"排除"模式下，你也可以把_id设为0。

想把_id改个名字继续保留，可以用表达式赋值：{ customId: "$_id" }。把MongoDB的ObjectId导出给其他系统时很常用——别人不想要_id这个字段名，但主键得带过去。

4.3 投影位置影响性能：不是放在哪都行

$project是CPU密集型操作，对每一条上游文档都要做字段计算和表达式求值。把复杂的字符串拼接、日期换算放到管道前端，面对几十万条文档时性能会明显下滑。

我的经验遵循两个原则。

第一，能用$match先过滤就先用$match。把数据量降下来再投影，而不是先投影再过滤。$match能走索引，数据在进入$project之前已经被压缩到很小。

第二，$project尽量只保留下游真正需要的字段。别图省事把所有字段带进后面的$group、$lookup。每多一个字段，聚合并行阶段的内存占用和传输开销都会增加。

举个例子，这种顺序就不好：

// 不好的管道做法 db.orders.aggregate([ { $project: { user: 1, items: 1, shipping: 1, total: 1, status: 1 } }, { $match: { status: "completed" } } ])

问题在于$match本可以充分利用索引把大量非completed订单筛掉，结果放在$project后面。数据量一大，$project会处理所有订单，白白消耗CPU。调整顺序后效率能提升一个量级。

4.4 选型与替代方案：什么时候别用$project

$project不是万能的。有些同学为了取某个字段，明知文档里本来就有，还专门写个$project包一层。这种场景完全可以直接用find()投影，不需要进聚合管道。

MongoDB 3.4之后有个更轻量的阶段叫$set（以及$unset）。它允许往文档中添加新字段的同时保留其他所有字段，不用像$project那样把需要的字段重新列一遍。只是想"加一个计算字段并保留原文档"，用$set更省事，也不违反包含/排除混用规则：

db.orders.aggregate([ { $set: { tax: { $multiply: ["$total", 0.1] } } } ])

结果里所有原字段都在，同时多了一个tax字段。这个操作很多时候比$project更符合直觉。不过$set内部本质上还是在做投影，性能模型和$project类似。

选型建议这么记：

• 只想裁剪字段、生成多个新字段、重命名，用$project。
• 只想在保留原文档基础上加一两个处理后的字段，用$set。
• 只是查询时临时筛选字段列、不涉及计算，用find()投影。

我个人在实际项目里反复用$project，最大的体会是：聚合管道的可读性往往取决于投影写得干不干净。一个满屏冗余字段的管道，别人接手时根本看不出哪些字段真正参与计算；把$project用好了，字段结构一目了然，后续加$group、$lookup都会顺手很多。

最后分享一个调试小技巧：写投影时，可以在$project后面临时加一个$limit: 5，把样本数据打出来看看结果是否符合预期。确认无误再拿掉limit全量跑，这能避免对着几十万行结果发呆。

聚合里的投影，归根结底是数据整形的思维：先想清楚下游需要什么形状的数据，再用$project把它裁剪成那个形状。这个思路一旦建立，再看任何管道都会轻松不少。