本文详解为何使用 $gte 和 $lt（或 $lte）进行日期范围查询时返回空结果，重点剖析边界逻辑错误、数据类型不一致、时区混淆及字段名误用等核心问题，并提供可直接复用的修复方案与验证示例。
本文详解为何使用 `$gte` 和 `$lt`（或 `$lte`）进行日期范围查询时返回空结果，重点剖析边界逻辑错误、数据类型不一致、时区混淆及字段名误用等核心问题，并提供可直接复用的修复方案与验证示例。
在 MongoDB 应用开发中，一个高频却极易被忽视的问题是：使用 $gte 与 $lt 组合进行日期范围查询时，始终返回空数组（"documents": []）。正如你在 PHP + cURL 调用 Atlas Data API 时所遇——当 filter 设置为：
{
"type": { "$eq": "top" },
"createdOn": {
"$gte": "2022-04-11T00:08:54Z",
"$lt": "2022-04-11T00:08:54Z"
}
}
该查询逻辑上永远无法匹配任何文档：因为一个时间值不可能同时满足 ≥ X 且 空区间（empty interval）错误，等价于数学中的 X ≤ t
✅ 正确的日期范围写法：闭左开右（推荐）或闭区间
MongoDB 原生支持 ISODate 格式，但通过 HTTP API（如 Atlas Data API）传入的字符串需确保：
- 格式严格为 YYYY-MM-DDTHH:mm:ssZ（UTC）；
- $gte 与 $lt 配对构成「左闭右开」区间，语义清晰且避免重复计数（尤其在分页或增量同步场景）；
- 若需包含右端点，则改用 $lte，但必须确保 $gte ≤ $lte。
✅ 正确示例（查询 2022-04-11 全天数据）：
{
"type": { "$eq": "top" },
"createdOn": {
"$gte": "2022-04-11T00:00:00Z",
"$lt": "2022-04-12T00:00:00Z"
}
}
? 提示："2022-04-12T00:00:00Z" 是 2022-04-11 的下一个自然日起点，确保覆盖至 23:59:59.999。
✅ 若坚持使用 $lte（闭区间）：
{
"type": { "$eq": "top" },
"createdOn": {
"$gte": "2022-04-11T00:00:00Z",
"$lte": "2022-04-11T23:59:59Z"
}
}
⚠️ 注意：手动指定秒级终点易遗漏毫秒，且受时区影响大，强烈推荐左闭右开模式。
⚠️ 其他导致“查不到”的关键原因（常被忽略）
1. 字段名不一致：createdAt ≠ createdOn
你示例文档中实际字段为 "createdAt": "2022-04-11T00:08:54Z"，但查询中却使用 "createdOn" —— 字段名拼写错误将导致全量过滤失败。务必核对：
- 文档真实字段名（用 db.collection.findOne() 查看）；
- 查询 filter 中的键名是否完全一致（含大小写）。
2. 数据类型错误：字符串 vs Date 对象
若数据库中 createdAt 以字符串形式存储（如 "2022-04-11T00:08:54Z"），而你期望按时间比较，MongoDB 会执行字典序字符串比较，而非时间计算。例如：
- "2022-04-11T23:59:59Z"
- 但 "2022-04-2T00:00:00Z" > "2022-04-11T00:00:00Z" ❌（因 '2' > '1'，月/日未补零导致错乱）
✅ 解决方案：
- 插入时统一用 new Date("2022-04-11T00:08:54Z") 存储；
- 或通过聚合 $dateFromString 转换（适用于存量数据修复）：
db.collection.aggregate([ { $addFields: { createdAtISO: { $dateFromString: { dateString: "$createdAt" } } } } ])
3. 时区陷阱：Zulu 时间（UTC）是唯一安全基准
所有 T...Z 格式均解析为 UTC。若前端传入本地时间（如 2022-04-11 10:00:00 东八区），未转为 UTC 直接拼接，会导致查询偏移 8 小时。
✅ 安全做法：
- 前端使用 toISOString()（自动转 UTC）；
- 后端 PHP 用 date('c', strtotime($input)) 确保输出带 Z。
4. 索引缺失：范围查询性能与可行性依赖索引
对 createdOn 字段未建索引时，大数据集下查询可能超时或被拒绝。创建高效索引：
db.collection.createIndex({ "createdOn": 1, "type": 1 })
复合索引按查询顺序排列，显著提升 type + createdOn 组合查询效率。
? 快速自检清单
| 检查项 | 验证命令 / 方法 |
|---|---|
| ✅ 字段名是否准确？ | db.collection.findOne({}, { projection: { createdAt: 1, createdOn: 1 } }) |
| ✅ 数据类型是否为 Date？ | db.collection.aggregate([ { $project: { type: { $type: "$createdAt" } } } ])（应返回 "date"） |
| ✅ 时间范围是否非空？ | 确保 $gte 值 ≤ $lt 值，且 $lt > $gte |
| ✅ 是否存在匹配文档？ | 先用 db.collection.find({ type: "top" }).limit(1) 确认基础查询有效 |
? 总结：写出健壮日期查询的三条铁律
- 永远使用左闭右开区间：$gte: startISO, $lt: endNextDayISO，杜绝 $gte + $lte 在临界点的歧义；
- 字段名、类型、时区三统一：查文档确认字段名；存 Date 对象而非字符串；全程用 UTC ISO 格式；
- 索引先行，验证兜底：对高频范围字段建立复合索引，并在代码中添加 countDocuments 快速校验逻辑有效性。
遵循以上原则，即可彻底规避“日期查询总为空”的陷阱，让时间维度的数据检索既精准又高效。
