Azure Cosmos DB中ReadDocumentAsync超时设置失效问题

我之前在使用Azure Cosmos DB的DocumentClient时也碰到过一模一样的问题——明明把RequestTimeout设成了1秒，实际操作却经常超时到5秒以上。这主要是因为默认的重试机制会把多次请求的时间累加起来，咱们来一步步解决：

核心原因：默认重试机制会延长总耗时 #

RequestTimeout设置的是单个请求的超时时间，但DocumentClient默认会自动重试节流（429错误）或者其他可重试的请求，每次重试还会有等待时间，最终总耗时就会远超你设置的1秒。

具体解决办法 #

1. 调整重试选项，限制总重试时间或关闭重试 #

你可以在ConnectionPolicy里配置RetryOptions，要么关闭重试，要么设置重试的总等待时间不超过你的预期超时：

// 构建带重试配置的ConnectionPolicy
var connectionPolicy = new ConnectionPolicy 
{ 
    ConnectionMode = ConnectionMode.Gateway, 
    ConnectionProtocol = Protocol.Tcp, 
    RequestTimeout = TimeSpan.FromSeconds(1), // 单个请求超时1秒
    RetryOptions = new RetryOptions
    {
        // 选项1：关闭自动重试（适合严格控制超时的场景，但要自己处理429错误）
        MaxRetryAttemptsOnThrottledRequests = 0,
        // 选项2：限制重试总等待时间（比如总重试等待+单个请求超时不超过1秒）
        MaxRetryWaitTimeInSeconds = 1
    }
};

// 初始化DocumentClient
DocumentClient documentClient = new DocumentClient(
    new Uri(DocumentDbEndpointUrl), 
    DocumentDbKey, 
    connectionPolicy);

2. 尝试切换连接模式优化超时控制 #

你当前用的是Gateway连接模式+Tcp协议，这种模式下底层连接的额外耗时可能会影响超时控制。如果你的网络环境允许，可以尝试切换为Direct模式，它的性能和超时稳定性通常更好：

var connectionPolicy = new ConnectionPolicy 
{ 
    ConnectionMode = ConnectionMode.Direct, // 切换为Direct模式
    ConnectionProtocol = Protocol.Tcp, 
    RequestTimeout = TimeSpan.FromSeconds(1),
    RetryOptions = new RetryOptions
    {
        MaxRetryWaitTimeInSeconds = 1
    }
};

3. 排查代码层面的额外超时逻辑 #

确认你的ReadDocumentAsync调用没有被其他异步操作的超时逻辑包装（比如自定义的Task.WhenAny超时逻辑），这些外部逻辑也可能导致总耗时超过预期。

额外提醒 #

如果你的项目可以升级SDK，建议换成最新的Microsoft.Azure.Cosmos包（使用CosmosClient），它的超时配置更直观，重试策略的可配置性更强，能避免很多旧SDK的隐性坑。

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