如何在 TypeScript 中高效使用 Azure Cosmos DB SDK

解决在 Node.js 环境中与 Azure Cosmos DB 交互的开发痛点，提供从身份验证、资源管理到复杂查询和批量操作的完整 TypeScript 实现方案。

为什么需要这个技能

Azure Cosmos DB 是一个分布式的 NoSQL 数据库，其 API 相对复杂。开发者经常混淆“管理平面”（创建账户/容器）与“数据平面”（读写文档）的 SDK，或者在处理分区键（Partition Key）和并发更新时出现性能问题。

掌握 @azure/cosmos SDK 能让你在 TypeScript 中实现类型安全的数据库操作，通过参数化查询防止注入，利用批量操作（Bulk Operations）提升吞吐量，并使用 ETag 确保在并发环境下数据的一致性。

适用场景

• 构建需要高性能、低延迟读写的云原生应用程序。
• 在 TypeScript 项目中实现复杂的 NoSQL 文档查询与分页。
• 需要对大量文档进行高效更新或删除的后台处理任务。
• 构建具备乐观并发控制（Optimistic Concurrency）的分布式系统。

核心工作流

1. 环境配置与身份验证

首先安装依赖 @azure/cosmos 和 @azure/identity。推荐使用 DefaultAzureCredential 进行 AAD 认证，避免在代码中硬编码密钥。

import { CosmosClient } from "@azure/cosmos";
import { DefaultAzureCredential } from "@azure/identity";

const client = new CosmosClient({
  endpoint: process.env.COSMOS_ENDPOINT!,
  aadCredentials: new DefaultAzureCredential(),
});

2. 资源操作 (CRUD)

Cosmos DB 的资源层级为 Client -> Database -> Container -> Item。在进行读写时，必须提供 id 和 partitionKey 以实现最优性能。

• 创建与写入：使用 container.items.create 或 upsert。
• 局部更新：使用 PatchOperation 仅修改文档中的特定字段，减少带宽开销。

import { PatchOperation } from "@azure/cosmos";

const operations: PatchOperation[] = [
  { op: "replace", path: "/price", value: 799.99 },
  { op: "add", path: "/discount", value: true },
];
await container.item("product-1", "electronics").patch(operations);

3. 高效查询与分页

严禁使用字符串拼接构建查询，必须使用 SqlQuerySpec 参数化查询。对于大数据集，通过 continuationToken 实现分页。

import { SqlQuerySpec } from "@azure/cosmos";

const querySpec: SqlQuerySpec = {
  query: "SELECT * FROM c WHERE c.partitionKey = @category AND c.price < @maxPrice",
  parameters: [
    { name: "@category", value: "electronics" },
    { name: "@maxPrice", value: 1000 },
  ],
};
const { resources } = await container.items.query<Product>(querySpec).fetchAll();

4. 批量操作与并发控制

使用 executeBulkOperations 将多个请求合并，大幅减少网络往返次数。同时，利用 ETag 机制实现“检查-并-设置”（Check-and-Set）逻辑，防止数据被覆盖。

下载和安装

下载 azure-cosmos-ts 中文版 Skill ZIP

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

你可能还需要

暂无推荐