Spring Data MongoDB长值时间范围查询异常排查与解决

AI 小北

2026-5-6

Spring Data MongoDB查询时间范围时返回无结果，日志显示条件带有$numberLong

我在使用Spring Data MongoDB查询指定时间范围内的文档时遇到了问题，具体情况如下：

环境与代码

MongoDB中的文档（RoboMongo显示）：

{ "_id": ObjectId("5e579c8674f69d1c1451f3ae"), ... "timestamp": NumberLong(1582800002779), ... "_class": "regular" }

对应的实体类：

public class MyObjectModel { 
    @Id @Field(value = ID_FIELD_NAME)
    private String id; 
    @Field(value = TIMESTAMP_FIELD_NAME)
    private Long timestamp; 
    // 其他字段
}

查询代码：

public List<Criteria> generateAllCriteria() { 
    List<Criteria> criteriaList = new ArrayList<>(); 
    Optional.ofNullable(searchCriteria.getFromTimestamp())
            .map(ts -> criteriaList.add(generateFromTimestampCriteria(ts))); 
    Optional.ofNullable(searchCriteria.getToTimestamp())
            .map(ts -> criteriaList.add(generateToTimestampCriteria(ts))); 
    return criteriaList; 
}

private Criteria generateFromTimestampCriteria(Long fromTimestamp) { 
    Criteria critFromTimestamp = Criteria.where(TIMESTAMP_FIELD_NAME).gte(fromTimestamp); 
    log.debug("From Timestamp criteria {}", critFromTimestamp.getCriteriaObject().toJson()); 
    return critFromTimestamp; 
}

private Criteria generateToTimestampCriteria(Long toTimestamp) { 
    Criteria critToTimestamp = Criteria.where(TIMESTAMP_FIELD_NAME).lt(toTimestamp); 
    log.debug("To Timestamp criteria {}", critToTimestamp.getCriteriaObject().toJson()); 
    return critToTimestamp; 
}

// 执行查询
List<Criteria> criteriaList = generateAllCriteria(); 
Criteria finalCriteria = new Criteria(); 
finalCriteria = finalCriteria.andOperator(criteriaList.toArray(new Criteria[criteriaList.size()])); 
log.debug("Final criteria {}", finalCriteria); 
Query query = new Query(); 
query.addCriteria(finalCriteria); 
List<MyObjectModel> myObjects = mongoTemplate.find(query, MyObjectModel.class);

问题现象

日志中打印的查询条件里，timestamp的比较值带有$numberLong前缀，比如：

{"timestamp": {"$gte": {"$numberLong": "1582800000000"}}}

我手动在RoboMongo中执行这个查询时返回无结果，但去掉$numberLong包裹，直接用数值查询（比如{"timestamp": {"$gte": 1582800000000}}）就能得到正确结果。请问我哪里出错了？如何让Spring Data MongoDB生成正确的查询？

首先要澄清一个关键点：你在日志中看到的$numberLong只是BSON 64位整数的JSON序列化表示，并不是Spring Data MongoDB发送给MongoDB的实际查询内容。MongoDB的BSON格式中，64位整数是一个独立的类型，而$numberLong是MongoDB用来在JSON中表示这种类型的扩展语法，直接在RoboMongo中执行带有$numberLong的JSON查询会被当成嵌套文档处理，自然匹配不到存储的NumberLong值。

那为什么你的代码查询不到结果呢？可以从以下几个方向排查和解决：

1. 确认时间范围参数的正确性

先检查searchCriteria中的fromTimestamp和toTimestamp值是否真的覆盖了MongoDB中文档的timestamp值。比如你文档中的timestamp是1582800002779，需要确保fromTimestamp <= 1582800002779且toTimestamp > 1582800002779，否则查询自然返回空。

2. 显式指定字段的BSON类型

虽然Long类型默认应该映射到MongoDB的Int64（即NumberLong），但可以显式在实体类的timestamp字段上指定类型，避免潜在的映射错误：

@Field(value = TIMESTAMP_FIELD_NAME, targetType = FieldType.INT64)
private Long timestamp;

这会明确告诉Spring Data MongoDB该字段对应BSON的64位整数类型，确保查询时的类型匹配。

3. 检查字段名映射是否正确

确认TIMESTAMP_FIELD_NAME常量的值确实是"timestamp"，和MongoDB文档中的字段名完全一致。如果字段名拼写错误，查询会匹配不到任何数据。

4. 查看MongoDB的实际查询日志

开启MongoDB的查询日志，直接查看Spring Data MongoDB发送的实际查询请求（而不是Spring日志中的JSON序列化结果）。可以在MongoDB的配置文件中添加：

systemLog:
  verbosity: 2

或者在运行时执行db.setLogLevel(2)，这样就能看到实际的BSON查询内容，确认是否和你预期的一致。

5. 简化查询条件的构建代码

你构建最终条件的代码可以简化，避免不必要的数组转换：

Criteria finalCriteria = Criteria.where("").andOperator(criteriaList);
// 或者更清晰的方式：
if (!criteriaList.isEmpty()) {
    finalCriteria = new Criteria().andOperator(criteriaList);
    query.addCriteria(finalCriteria);
}

这样代码更简洁，也能避免空条件列表导致的潜在问题。

6. 检查Spring Data MongoDB版本

如果使用的是较旧的版本，可能存在Long类型查询的bug。建议升级到最新的稳定版本（比如3.x或4.x系列），很多旧版本的类型映射问题已经被修复。

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