MongoDB 聚合查询：精准筛选嵌套数组中的匹配项并保留完整父文档结构

本文详解如何使用 mongodb 聚合管道（`$unwind` + `$match` + `$group`）在嵌套数组中搜索部分匹配的字段（如 `pictures.name`），并正确聚合所有匹配子文档到对应父文档的数组中，避免丢失多匹配项。

在实际开发中，常需从 MongoDB 的嵌套数组（如 pictures: [{name: "...", version: "..."}]）中检索满足条件（如模糊匹配 name 字段）的多个子对象，并按原始父文档分组返回，且每个父文档只包含其内部所有匹配的子项——而非仅返回首个或去重后的单个结果。

原代码的问题根源在于冗余的 $replaceRoot 与 $mergeObjects 阶段干扰了 $group 的聚合逻辑，同时错误地引用了 $$ROOT（导致每次 $group 后仅保留一个任意匹配项）。关键修复点有三：

1. 移除 $replaceRoot 和 $project 中对 $$ROOT 的依赖：$$ROOT 在 $unwind 后已展开为多条记录，直接使用会破坏父子关系；
2. 在 $group 中显式提取父级字段（url, source）并用 $addToSet 收集全部匹配的 pictures 子文档；
3. 将 _id 提前转为字符串（{"$toString": "$_id"}）以兼容 JSON 序列化，避免 ObjectId 类型引发前端解析错误。

以下是修正后的完整聚合管道（PyMongo 实现）：

@app.route('/component/find/', methods=['GET'])
def get_component(picture_name):
    pattern = re.compile(picture_name, re.IGNORECASE)

    pipeline = [
        # 展开嵌套 pictures 数组，每条子文档生成独立流水线文档
        {"$unwind": "$pictures"},
        # 筛选 name 字段匹配正则的子文档
        {"$match": {"pictures.name": {"$regex": pattern}}},
        # 按原始文档 _id 分组（转为字符串确保 JSON 兼容）
        {"$group": {
            "_id": {"$toString": "$_id"},
            "url": {"$first": "$url"},      # 父文档 url（同 _id 组内唯一）
            "source": {"$first": "$source"}, # 父文档 source
            "pictures": {"$addToSet": "$pictures"}  # ✅ 收集所有匹配的子文档（非去重！）
        }}
    ]

    result = list(collection.aggregate(pipeline))

    if result:
        return jsonify(result)
    else:
        return jsonify({
            "message": f"Component with picture '{picture_name}' not found."
        }), 404

✅ 关键说明：$addToSet 此处并非“去重”，而是因 $unwind + $match 后，同一 _id 下所有匹配的 pictures 子文档均进入 $group 阶段，$addToSet 会自然聚合该 _id 下全部匹配项（即使 name 相同但 version 不同，也视为不同元素）。若需严格去重（如忽略 version），可改用 {"$addToSet": "$pictures.name"}，但本例目标是保留完整子对象，故保持 "$pictures" 即可。

注意事项：

• 若文档中存在大量 pictures 子项，$unwind 可能引发内存压力，生产环境建议配合 $limit 或建立复合索引 {"pictures.name": 1} 提升性能；
• re.IGNORECASE 已通过正则标志实现大小写不敏感匹配，无需在 $regex 中重复指定；
• 返回结果中 _id 为字符串类型，符合 REST API 规范；如需保留 ObjectId，可在 jsonify 前自定义 JSONEncoder，但通常字符串更安全通用。

此方案简洁、高效、可读性强，精准满足「按父文档分组 + 保留全部匹配嵌套项」的核心需求。