azure-cosmos-db-py

azure-cosmos-db-py 技能概览

这个技能适合做什么

azure-cosmos-db-py 技能可以帮助你在 Python 中实现 Azure Cosmos DB NoSQL 持久化，通常用于 FastAPI 或服务层后端。它最适合你需要的是一套可落地的模式：客户端初始化、考虑分区键的 CRUD、参数化查询，以及可测试的数据访问代码，而不是一次性的提示词答案。

最适合哪些用户和任务

如果你在搭建需要从一开始就把 Cosmos DB 接好的后端功能，就该用 azure-cosmos-db-py skill：应用初始化、repository/service 类、适配模拟器的本地开发，以及清晰的错误处理。对于 azure-cosmos-db-py for Backend Development 来说，它尤其适合在你想增加持久化文档存储，但又不想自己从零发明连接和模型转换模式时使用。

它的区别在哪里

它的核心价值在于实用的实现指导：双认证路径、单例式客户端复用、分区键策略，以及面向 TDD 的 fixture。它不只是泛泛讲 Cosmos DB 的说明文，而是直接面向能在本地运行、部署到 Azure、并且更容易测试的代码。

如何使用 azure-cosmos-db-py 技能

安装并打开正确的文件

对于 azure-cosmos-db-py install，先添加技能：

npx skills add microsoft/skills --skill azure-cosmos-db-py

然后先读 SKILL.md，再看 references/client-setup.md、references/partitioning.md、references/service-layer.md、references/error-handling.md 和 references/testing.md。实现时可以把 assets/cosmos_client_template.py、assets/service_template.py 和 assets/conftest_template.py 当作起点。

给技能一个具体的后端任务

azure-cosmos-db-py usage 在你明确说明实体、分区键、认证模式和预期操作时效果最好。比较好的输入示例是：“为 FastAPI 构建一个使用 Cosmos DB 的 ProjectService，按 workspace_id 分区，支持 create/get/update/delete，本地开发要兼容 emulator，并提供用于服务测试的 pytest fixtures。” 这样技能才有足够结构去选择合适的文档模型和 repository 模式。

提示词里要写什么

一条高质量的 azure-cosmos-db-py guide 提示词应当明确写出：

• 实体名称和字段
• 分区键的选择
• 是否需要 Azure 认证、emulator 认证，或者两者都要
• 同步还是异步的应用上下文
• 查询模式，比如 id 查找、过滤列表，或跨分区搜索
• 测试预期，尤其是 pytest 和 mocking

如果你的应用已经有模型，也要注明你想保留的具体 Pydantic 类，或者 JSON 结构。

实际工作流

先做 Cosmos client 模块，再做 service layer，最后写测试。仓库的结构本来就支持这个顺序：先配置客户端，再处理 CRUD/service 模式，最后补 fixtures 和错误处理。按这个顺序做能减少返工，因为分区和认证的决定会影响后面的所有内容。

azure-cosmos-db-py 技能常见问题

这个技能只适用于 Azure 托管应用吗？

不是。azure-cosmos-db-py 技能同时支持本地 emulator 开发和 Azure 部署。当你希望开发和生产环境使用同一套代码时，这种双路径方案是它最实用的能力之一。

如果我已经会 Cosmos SDK，还需要这个技能吗？

如果你想要的是可复用的后端模式，答案是需要。这个技能会在连接复用、服务边界、考虑分区键的访问方式以及测试 fixture 上加入明确的结构化建议。普通提示词可能只会给你 SDK 片段；而这个技能更适合帮你搭出可维护的 service layer。

对初学者友好吗？

如果你已经了解基本的 Python 应用结构，并且希望有人带着你完成实现，它是比较友好的。但如果你现在需要的是从零开始的 Cosmos DB 概念入门，它就不太合适。azure-cosmos-db-py skill FAQ 的答案可以概括为：当你准备开始动手构建时用它，而不是当你还在选数据库时用它。

什么情况下不该用它？

不要把它用在非 Python 技术栈、原始数据迁移脚本，或者 Cosmos DB 本来就不是合适存储模型的场景里。如果你的应用没有清晰的分区策略，它也不适合；这个技能默认你能够定义文档会如何被访问。

如何改进 azure-cosmos-db-py 技能

先把数据访问模式说清楚

要显著提升 azure-cosmos-db-py 的输出质量，关键是先告诉它文档实际会怎么读写。说明查询是按主 ID、按父级范围内的 ID，还是按过滤列表来做。如果不说明，生成的设计在技术上可能没问题，但未必适合你的真实查询模式。

提供明确的约束和环境信息

请写清楚你是否使用 DefaultAzureCredential、Cosmos emulator，还是两者都要；是否需要在异步代码外再包一层同步封装；以及当前已有的环境变量。比如，“本地开发只用 COSMOS_ENDPOINT、COSMOS_DATABASE_NAME、COSMOS_CONTAINER_ID 和 emulator key” 就比“把 Cosmos 配好”有用得多。

先要第一个产物，不要一上来要整个应用

最好的 azure-cosmos-db-py usage 往往是从一个 service 和一个测试文件开始。你可以直接要求输出一个具体成果，比如 client 模块、ProjectService，或者 pytest fixtures。然后在看到文档 schema、错误映射和分区键选择之后再继续迭代。

注意常见失败模式

最常见的问题是分区键选错、把认证假设写死，以及忽略对 not-found 和 conflict 场景的测试。如果第一次输出太泛，就用更强的输入来收紧范围：样本文档字段、预期查询，以及你希望的 FastAPI 路由行为。