根据Google API文档的定义，resultSizeEstimate 是估计的结果总数，并且明确说明这个数值不应随每页返回条目数（即maxResults参数）的修改而变化。但实际调用 gmail.users.messages.list() 接口时，却出现了调整maxResults导致该估计值大幅波动的情况，以下是具体测试案例：

测试案例 #

示例A：maxResults=1 #

{ 
    "config": { 
        "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=1", 
        "method": "GET", 
        "headers": { 
            "Accept-Encoding": "gzip", 
            "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)", 
            "Authorization": "Bearer [snip]", 
            "Accept": "application/json" 
        }, 
        "params": { 
            "q": "before:2021/1/9", 
            "maxResults": 1 
        }, 
        "responseType": "json" 
    }, 
    "data": { 
        "messages": [ ... ], 
        "nextPageToken": "14911817971227869758", 
        "resultSizeEstimate": 8 
    }, 
    "headers": { 
        "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"", 
        "cache-control": "private", 
        "connection": "close", 
        "content-encoding": "gzip", 
        "content-type": "application/json; charset=UTF-8", 
        "date": "Sun, 09 Jan 2022 12:59:48 GMT", 
        "server": "ESF", 
        "transfer-encoding": "chunked", 
        "vary": "Origin, X-Origin, Referer", 
        "x-content-type-options": "nosniff", 
        "x-frame-options": "SAMEORIGIN", 
        "x-xss-protection": "0" 
    }, 
    "status": 200, 
    "statusText": "OK" 
}

结果：resultSizeEstimate: 8

示例B：maxResults=2 #

{ 
    "config": { 
        "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=2", 
        "method": "GET", 
        "headers": { 
            "Accept-Encoding": "gzip", 
            "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)", 
            "Authorization": "Bearer [snip]", 
            "Accept": "application/json" 
        }, 
        "params": { 
            "q": "before:2021/1/9", 
            "maxResults": 2 
        }, 
        "responseType": "json" 
    }, 
    "data": { 
        "messages": [ ... ], 
        "nextPageToken": "16903415066875011466", 
        "resultSizeEstimate": 12 
    }, 
    "headers": { 
        "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"", 
        "cache-control": "private", 
        "connection": "close", 
        "content-encoding": "gzip", 
        "content-type": "application/json; charset=UTF-8", 
        "date": "Sun, 09 Jan 2022 13:10:48 GMT", 
        "server": "ESF", 
        "transfer-encoding": "chunked", 
        "vary": "Origin, X-Origin, Referer", 
        "x-content-type-options": "nosniff", 
        "x-frame-options": "SAMEORIGIN", 
        "x-xss-protection": "0" 
    }, 
    "status": 200, 
    "statusText": "OK" 
}

结果：resultSizeEstimate: 12

示例C：未设置maxResults（使用默认值） #

{ 
    "config": { 
        "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9", 
        "method": "GET", 
        "headers": { 
            "Accept-Encoding": "gzip", 
            "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)", 
            "Authorization": "Bearer [snip]", 
            "Accept": "application/json" 
        }, 
        "params": { 
            "q": "before:2021/1/9" 
        }, 
        "responseType": "json" 
    }, 
    "data": { 
        "messages": [ ... ], 
        "nextPageToken": "16942818266524948378", 
        "resultSizeEstimate": 412 
    }, 
    "headers": { 
        "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"", 
        "cache-control": "private", 
        "connection": "close", 
        "content-encoding": "gzip", 
        "content-type": "application/json; charset=UTF-8", 
        "date": "Sun, 09 Jan 2022 13:09:05 GMT", 
        "server": "ESF", 
        "transfer-encoding": "chunked", 
        "vary": "Origin, X-Origin, Referer", 
        "x-content-type-options": "nosniff", 
        "x-frame-options": "SAMEORIGIN", 
        "x-xss-protection": "0" 
    }, 
    "status": 200, 
    "statusText": "OK" 
}

结果：resultSizeEstimate: 412

分析与说明 #

这种现象看起来和文档描述不符，但需要注意resultSizeEstimate本身带有“估计”属性，Gmail API的后端可能在不同分页参数下采用了不同的统计策略：

• 当maxResults设置为较小值时，API可能仅基于返回的少量数据做粗略估算；
• 当使用默认值（或较大的maxResults）时，API会执行更完整的统计，返回更接近真实值的估计数。

如果需要获取更准确的结果总数，建议通过遍历所有分页（使用nextPageToken）来统计实际的消息数量，而不是依赖resultSizeEstimate的数值。

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