Azure SDK for Python 中 Cosmos DB 查询参数类型提示问题解析

在 Azure SDK for Python 项目中使用 Cosmos DB 时，开发者可能会遇到一个关于查询参数类型提示的潜在问题。这个问题主要涉及到 query_items 方法的参数类型定义与实际使用场景不符的情况。

问题背景

当使用 Cosmos DB 的 Python SDK 进行查询操作时，query_items 方法接受一个参数列表用于参数化查询。当前 SDK 中的类型提示将参数定义为简单的字典列表，但实际上参数值可以支持多种数据类型，而不仅仅是字符串类型。

技术细节分析

在参数化查询中，开发者通常会构建如下形式的查询参数：

parameters = [
    {"name": "@param1", "value": "string_value"},
    {"name": "@param2", "value": 123},
    {"name": "@param3", "value": True}
]

当前 SDK 的类型提示将参数限制为 List[Dict[str, str]]，这意味着类型检查工具会错误地提示开发者只能使用字符串值。实际上，Cosmos DB 查询参数支持多种数据类型，包括但不限于：

• 字符串 (str)
• 整数 (int)
• 浮点数 (float)
• 布尔值 (bool)
• 其他基本数据类型

解决方案建议

正确的类型提示应该使用更宽松的类型定义，例如：

from typing import Any, Dict, List, Optional

parameters: Optional[List[Dict[str, Any]]] = None

这种定义方式能够准确反映 API 的实际行为，同时为开发者提供正确的类型检查支持。对于更严格的类型检查场景，可以考虑使用 TypedDict 来明确定义参数对象的结构。

对开发者的影响

不准确的类型提示可能导致以下问题：

1. 开发工具（如 VS Code 的 Pylance）会显示错误的类型警告
2. 开发者可能会误以为只能使用字符串参数
3. 静态类型检查工具会产生误报

最佳实践

在实际开发中，建议开发者：

1. 了解参数化查询支持多种数据类型
2. 即使类型提示不准确，也可以安全地使用非字符串参数
3. 关注 SDK 更新，以获得更准确的类型定义

这个问题虽然不影响实际功能使用，但对于依赖类型提示的开发工作流会造成一定困扰。Azure SDK 团队已经注意到这个问题，并将在后续版本中进行修正。