使用 Python 构建生产级 Azure Cosmos DB NoSQL 服务

本技能提供一套完整的架构方案，引导开发者在 Python 环境下构建符合生产标准、具备高安全性且易于测试的 Azure Cosmos DB 数据访问层。

为什么需要这个技能

在实际的生产环境中，直接在业务代码中调用数据库 SDK 往往会导致代码耦合严重、难以测试且存在安全隐患（如硬编码密钥）。

通过引入单例客户端模式、五层 Pydantic 模型定义以及解耦的服务层（Service Layer），可以将数据库的物理存储细节与业务逻辑彻底分离。这不仅能实现开发环境（模拟器）与生产环境（RBAC 认证）的无缝切换，还能确保通过参数化查询防止注入攻击。

适用场景

• 使用 FastAPI 或 Flask 构建需要集成 Azure Cosmos DB 的后端服务。
• 需要在本地开发（Cosmos Emulator）与 Azure 云端环境之间快速切换。
• 追求高代码质量，要求实现完整的测试驱动开发（TDD）流程。
• 处理复杂文档结构，需要严格的类型检查和数据验证。

核心工作流

1. 构建双模认证客户端

实现一个单例客户端，根据端点地址自动判断是使用本地模拟器的 Key 认证，还是使用生产环境的 DefaultAzureCredential（基于 RBAC），避免密钥泄露。

# 核心逻辑示例：区分模拟器与生产环境
async def get_container():
    global _cosmos_container
    if _cosmos_container is None:
        if _is_emulator_endpoint(settings.cosmos_endpoint):
            client = CosmosClient(url=settings.cosmos_endpoint, credential=settings.cosmos_key, connection_verify=False)
        else:
            client = CosmosClient(url=settings.cosmos_endpoint, credential=DefaultAzureCredential())
        # ... 获取容器实例
    return _cosmos_container

2. 定义五层模型架构

为了实现干净的代码分离，建议将模型分为五层：Base（共有字段） Create（创建请求） Update（部分更新） Response（API 响应） InDB（含内部文档类型）。

3. 实现服务层模式

Service Layer 负责业务逻辑、文档与模型的转换以及在数据库不可用时的优雅降级处理，确保 API 接口不直接依赖数据库 SDK。

4. TDD 测试驱动

在编写功能前，利用 pytest 和 mocker 模拟 Cosmos 容器的行为，确保数据转换逻辑和业务分支在无数据库环境的情况下也能通过验证。

下载和安装

下载 azure-cosmos-db-py 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐