Azure Cosmos DB TypeScript – Node.js 数据层实战模式库 Skill 技能

Azure Cosmos DB TypeScript 技能为 Claude、Codex、Claude Code 提供基于 Node.js 与 @azure/cosmos 4.9.0+ 的实战模式库，覆盖认证、文档 CRUD、查询、批量操作、分区键、错误处理等关键场景。技能把"接 Cosmos DB 不踩坑"这件事工程化为一组可复用模式，让 TypeScript 开发者能快速搭起生产级的数据访问层。

技能简介

Azure Cosmos DB TypeScript 技能系统整理了 Node.js + TypeScript 接入 Cosmos DB 的全链路模式：先用 DefaultAzureCredential 完成认证，再用类型化服务层封装 CRUD/批量/分页查询，最后用 ETag、乐观锁与速率限制处理应对高并发。所有模式都基于 @azure/cosmos 4.9.0+ 文档实测，覆盖从单机脚本到生产微服务的常见场景。

核心能力

• 认证模式详解：覆盖 Azure AD（DefaultAzureCredential）、Account Key、连接字符串三种认证方式，并给出最小权限角色分配建议。
• 文档 CRUD 全栈：覆盖 create、read、replace、upsert、delete、patch 六类操作及对应的 TypeScript 类型签名。
• 参数化与分页查询：展示如何写参数化 SQL、分页拉取、跨分区查询，控制 Request Unit 消耗。
• 批量操作模板：覆盖 create/read/replace/upsert/patch/delete 的批量写法，适合高写入量场景。
• 分区键设计：说明简单分区键与层级分区键的选择权衡，配合 RU 成本分析。
• 错误与并发处理：覆盖 429 速率限制、ETag 冲突、NotFound 错误、客户端 disposal 等关键边界。

安装配置

1. 安装 Skillstore CLI：npm i -g @skillstore/cli。
2. 通过 CLI 安装技能：npx skillstore add sickn33/azure-cosmos-ts。
3. 准备 Node.js 环境：要求 Node.js 20+ 与 @azure/cosmos 4.9.0+。
4. 配置 Azure 凭证：通过 az login 或环境变量提供 Azure AD 凭据，授予 Cosmos DB BuiltIn 操作员。
5. 准备目标项目：把现有 Cosmos DB 接入层代码片段提供给 Agent，便于技能给出针对性建议。

使用步骤

1. 描述任务：告诉 Agent 当前 Cosmos DB 接入需求（如"为订单实体设计类型化服务层"）。
2. 获取模式：技能会按提示模板返回连接初始化、CRUD、查询、错误处理的代码骨架。
3. 集成到项目：把推荐的写法迁移到项目代码，注意保留现有 Connection 复用策略。
4. 写测试覆盖：为关键操作补充单元测试与集成测试，覆盖 RU 成本边界。
5. 生产化加固：用 ETag、retry policy、circuit breaker 完善生产环境容错。

适用场景

• 搭新服务数据层：从 0 到 1 设计订单、用户、产品等实体的 Cosmos DB 类型化服务层。
• 优化既有代码：把零散的 @azure/cosmos 调用按模式库重构为可测试的服务层。
• 生产化评审：让 Agent 在 PR 中按本技能检查认证、参数化查询、ETag、错误处理是否合规。
• 批量写入优化：把单条写入重写为批量操作，控制 RU 成本与吞吐。
• 跨分区查询治理：分析查询是否走分区键，给出 RU 优化建议与索引策略。

适用人群

• Node.js 后端工程师：日常用 @azure/cosmos 开发数据访问层的工程师。
• Azure 云架构师：在 Azure 上搭微服务并需要稳定 Cosmos DB 接入的架构师。
• TypeScript 库作者：为团队封装统一数据访问层的基础设施工程师。
• AI 协作团队：希望 Claude/Codex/Claude Code 按统一模式审查 Cosmos DB 代码的团队。
• 企业平台团队：把内部数据访问规范沉淀为 Skill 并强制推广的负责人。

工作原理

技能以文档化模式库形式存在，所有 TypeScript 代码片段均为 Markdown 示例，不会在技能加载时执行。Agent 按用户任务调用相应模式，输出代码骨架与注意事项；ETag、retry、批量操作等边界条件的判断基于 Azure 官方规则和技能整理的最佳实践。技能本身不会连接真实 Azure 账户，所有改动需开发者人工落地。

官方链接

• 公共页面：https://skillstore.io/skills/sickn33-azure-cosmos-ts
• Manifest：https://skillstore.io/api/skills/sickn33-azure-cosmos-ts/manifest
• 源码：https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/azure-cosmos-ts