Agent Skills
返回列表
💻

Azure Cosmos DB Python 服务

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @org-02qudk26/azure-cosmos-db-py。

技能介绍

要解决什么问题

在 Python 里接 Azure Cosmos DB NoSQL，常见痛点是：连接串或 API 密钥写进代码、同步/异步客户端混用、查询用字符串拼接，以及 Cosmos 短暂不可用时整站报错。团队还需要可测的服务层，而不是在路由里直接调 SDK。

技能如何组织实现

本技能按生产级服务拆成可落地的约定与参考文档，而不是零散代码片段。

  • 鉴权与客户端：优先 DefaultAzureCredential（本地 Azure CLI / VS Code，云端托管标识）；生产可通过 AZURE_TOKEN_CREDENTIALS 收紧凭据链。客户端与异步凭据均用上下文管理器释放连接与令牌缓存；客户端模块提供带双鉴权（含模拟器）的单例，细节见 references/client-setup.md。
  • 模型与服务层：采用五层 Pydantic 模型分离职责；服务层负责 CRUD、_doc_to_model / _model_to_doc 转换，Cosmos 不可用时优雅降级（返回 None 或 []），完整模式见 references/service-layer.md。
  • 安全与查询：RBAC 鉴权、仅本地模拟器使用众所周知的密钥、@parameter 参数化查询、分区键与授权一致性的校验。
  • TDD：实现前先写测试；Mock 与集成设置见 references/testing.md；另有 assets/ 下的客户端、服务类与 conftest 模板。

分区策略、错误映射（如 CosmosResourceNotFoundError）分别指向 references/partitioning.md 与 references/error-handling.md。

适用边界

  • 同一调用链内只选同步或异步一种，不要混用 azure.cosmos 与 azure.cosmos.aio。
  • 技能侧重 NoSQL API 与服务层架构；跨分区扫描、迁移等需结合分区文档自行权衡性能与成本。
  • 参考实现假设 FastAPI 等场景下的异步封装需求，但核心模式可迁移到其他框架。

使用场景

  • 在 Azure 部署 FastAPI 等 Python 服务时，用托管标识连接 Cosmos 容器，并实现独立 CRUD 服务层而非在路由里直接调 SDK。
  • 遗留代码仍用连接字符串或 API 密钥访问 Cosmos，需要改为 DefaultAzureCredential，并统一客户端单例与上下文管理器生命周期。
  • 新实体入库前先按 references/testing.md 用 Mock 容器写好 pytest，再实现 _doc_to_model 与服务层 CRUD。
  • 多租户或按用户隔离的数据模型下，选型分区键并实现 @parameter 查询，同时校验分区键与授权范围一致。

适合人员

  • 在 Azure 上交付 Python 微服务的后端工程师，要求 Cosmos 零硬编码密钥且服务层可 Mock 单测。
  • 接手含 Cosmos 字符串拼接查询的旧仓库，需要改成参数化查询、优雅降级与一致命名约定的维护者。
  • 采用整洁架构的团队技术负责人，希望统一五层 Pydantic 模型与服务层模板 across 多个 Cosmos 实体。
  • 本地用模拟器开发、上线切换 RBAC 的全栈工程师，需要双鉴权客户端模块与模拟器/生产环境切换说明。