CosmosDB未设置MaxItemCount时返回记录数超默认100条问题

安全阿岳

2026-8-28

问题成因

第三方SDK参数传递逻辑与服务端规则不匹配
你认为未设置MaxItemCount时零值0会触发服务端默认100条的限制，但通常该类第三方SDK对int类型零值的处理是在构造请求时直接省略x-ms-max-item-count请求头。而CosmosDB服务端目前已经调整了分页策略：未携带该请求头时不再固定返回100条，会根据单文档大小、查询复杂度、节点当前负载动态调整单页返回条数，最高可达1000条的接口上限，不属于功能故障。
SDK版本变更导致行为变化
如果你近期升级过go-cosmosdb版本，老版本SDK可能在参数为0时硬编码注入x-ms-max-item-count:100请求头，新版本如果给MaxItemCount字段加了序列化时忽略零值的标签，就会出现之前固定返回100条、现在返回条数波动的情况。
单分区查询的固有返回逻辑
你代码中关闭了跨分区查询，单分区场景下服务端如果判断待返回的剩余结果总大小未达到响应包阈值，会直接一次性返回所有剩余结果，不会严格卡100条的数值限制。如果之前查询的分区数据量较大、刚好触发100条截断，现在查询的数据集总大小未到阈值，就会出现返回条数超过100的现象。

排查步骤

校验实际请求头：开启SDK的请求调试日志，或者通过流量抓包工具查看发往CosmosDB的请求中是否携带x-ms-max-item-count头、对应值是多少。如果头不存在，说明SDK零值序列化逻辑触发了参数省略；如果头值为0，说明服务端将0值识别为未设置，走动态分页逻辑。
对比SDK版本差异：将当前go-cosmosdb版本回滚到之前返回100条的正常版本，对比两个版本中QueryDocumentsOptions结构体定义、请求参数拼接逻辑的差异，确认是否存在零值处理规则的改动。
显式传参验证：手动给opts.MaxItemCount赋值100后发起请求，如果返回条数稳定在100条以内，即可确认是默认参数逻辑变动导致的差异。

解决方案

不要依赖默认值，显式指定单页条数：如果需要和之前的单页返回行为保持一致，初始化配置时直接给MaxItemCount赋值100即可，示例代码如下：

opts := cosmosapi.QueryDocumentsOptions{
    IsQuery:              true,
    ContentType:          cosmosapi.QUERY_CONTENT_TYPE,
    ConsistencyLevel:     cosmosapi.ConsistencyLevelStrong,
    EnableCrossPartition: false,
    MaxItemCount:         100, // 显式指定单页最大返回条数
}

resp, err := c.client.QueryDocuments(ctx, DatabaseName, ContainerName, query, &res, opts)

按标准规范实现分页逻辑：所有CosmosDB查询逻辑都不要假设单页返回固定条数，必须以响应中的continuation token作为分页判断依据：只要token不为空，就携带token发起下一页查询，直到token为空时才完成全量拉取，该写法不受单页返回条数波动影响，不会出现漏数、异常问题。
封装公共参数初始化逻辑：在业务代码中封装统一的查询参数构造方法，强制给MaxItemCount赋值业务需要的固定值，避免因Go语言int零值特性、SDK版本变动导致的参数缺失问题。

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