MongoTemplate聚合查询group分组求和未按预期生效问题

问题梳理 #

涉及交易集合字段：_id、transactionId、userId、transactionType、transactionAction、transactionAmount、createdDate
目标需求：筛选指定时间范围内transactionAction为GIFT的记录，按userId分组统计每个用户的获赠总金额，支持排序与分页。
已出现的异常：

• 分组阶段同时传入_id与userId作为分组键，因_id全局唯一导致分组失效，同个用户返回多条记录
• 修正分组键仅保留userId后，添加按createdDate排序的逻辑抛出java.lang.IllegalArgumentException: Invalid reference 'createdDate'!异常
• 移除排序后查询可正常执行，但分组结果中userId值被存储在结果文档的_id字段，无法映射到RecentlyRewardedUsers实体类的userId属性，映射后该字段值为null

根因说明 #

1. 分组失效问题：MongoDB $group 阶段会把传入的所有字段组合作为唯一分组键，原始文档的_id是全局唯一值，加入分组键后每个文档都会单独成为一个分组，自然无法按用户维度聚合。
2. 字段引用无效报错：MongoDB聚合管道是顺序执行的，$group阶段的输出文档仅包含两部分内容：存在_id字段下的分组键值、分组阶段显式定义的聚合计算字段。原始文档的createdDate如果没有在分组阶段做聚合处理，进入下一个管道阶段时该字段已经不存在，排序时自然会报无效引用。
3. 字段映射为null问题：MongoDB 强制要求$group阶段的分组键必须存储在输出文档的_id字段中，按userId分组后用户ID的值会默认存到_id位置，实体类没有配置对应映射的话，自然无法读取到userId的值。

正确实现代码 #

聚合查询逻辑（MongoTemplate实现） #

管道执行顺序严格按照「匹配过滤→分组聚合→字段投影→排序→分页」编写，$match前置可以命中集合索引，大幅减少后续阶段需要处理的数据量：

import org.springframework.data.domain.Sort;
import org.springframework.data.mongodb.core.aggregation.Aggregation;
import org.springframework.data.mongodb.core.aggregation.AggregationResults;
import org.springframework.data.mongodb.core.query.Criteria;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.List;

// 示例：查询最近30天的礼物发放记录
Instant timeThreshold = Instant.now().minus(30, ChronoUnit.DAYS);
int pageNum = 1;
int pageSize = 20;

Aggregation rewardAgg = Aggregation.newAggregation(
        // 1. 匹配阶段：提前过滤符合条件的记录
        Aggregation.match(
                Criteria.where("transactionAction").is("GIFT")
                        .and("createdDate").gte(timeThreshold)
        ),
        // 2. 分组阶段：仅以userId为分组键，同时计算所有后续需要用到的聚合值
        Aggregation.group("userId")
                .sum("transactionAmount").as("totalGiftAmount")
                // 如需按交易时间排序，必须在分组阶段聚合出时间字段，示例取用户最新获赠时间
                .max("createdDate").as("latestRewardTime"),
        // 3. 投影阶段：重命名字段适配实体类结构
        Aggregation.project("totalGiftAmount", "latestRewardTime")
                // 将存在_id中的分组键值映射为userId字段
                .and("_id").as("userId")
                // 排除默认_id字段避免映射干扰
                .andExclude("_id"),
        // 4. 排序阶段：此时所有排序字段已生成，不会出现引用无效问题
        // 示例按最新获赠时间倒序，如需按总金额排序可替换字段为totalGiftAmount
        Aggregation.sort(Sort.by(Sort.Direction.DESC, "latestRewardTime")),
        // 5. 分页阶段
        Aggregation.skip((long) (pageNum - 1) * pageSize),
        Aggregation.limit(pageSize)
);

// 执行查询，映射到自定义实体
AggregationResults<RecentlyRewardedUsers> aggregateResult = mongoTemplate.aggregate(
        rewardAgg,
        "transaction_record", // 替换为实际的集合名称
        RecentlyRewardedUsers.class
);
List<RecentlyRewardedUsers> resultList = aggregateResult.getMappedResults();

实体类定义 #

实体类字段名和投影阶段设置的别名保持一致即可，无需额外注解：

import lombok.Data;
import java.math.BigDecimal;
import java.time.Instant;

@Data
public class RecentlyRewardedUsers {
    private Long userId;
    private BigDecimal totalGiftAmount;
    private Instant latestRewardTime;
}

注意事项 #

• 禁止将原始文档的_id字段加入分组键，除非业务需求是按单条文档粒度做统计，否则必然导致分组失效
• 所有在$group之后的管道阶段（排序、投影、二次匹配等）要用到的字段，必须在分组阶段显式做聚合计算（sum/max/min/first/last等），否则会出现字段不存在的报错
• 分页操作必须放在排序之后执行，否则会出现分页数据乱序问题

内容的提问来源于stack exchange，提问作者MetaCoder