azure-cosmos-ts

用途

@azure/cosmos 是 Azure Cosmos DB NoSQL API 的数据平面（Data Plane）SDK，面向 JavaScript/TypeScript 开发者，用于对文档执行 CRUD、查询、批量操作与存储过程等操作。

需要注意数据平面与管理平面的区别：本 SDK（@azure/cosmos）负责文档 CRUD、查询、存储过程；而创建账户、数据库、容器等管理操作需使用管理平面 SDK（@azure/arm-cosmosdb，通过 ARM）。

安装命令：

npm install @azure/cosmos @azure/identity

当前版本：4.9.0；Node.js 要求：>= 20.0.0。

环境变量示例：

COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/ COSMOS_DATABASE=<database-name> COSMOS_CONTAINER=<container-name>

COSMOS_KEY=<account-key>

推荐使用 AAD 配合 DefaultAzureCredential：

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

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

也可使用密钥认证（端点 + 密钥，或连接字符串）：

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

// 方式一：端点 + 密钥 const client = new CosmosClient({ endpoint: process.env.COSMOS_ENDPOINT!, key: process.env.COSMOS_KEY!, });

// 方式二：连接字符串 const client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING!);

CosmosClient → Database → Container → Items（文档）、Scripts（存储过程、触发器、UDF）、Conflicts。

数据库与容器创建：使用 databases.createIfNotExists 与 containers.createIfNotExists，可指定分区键路径。
文档操作：create、read、replace（更新）、upsert、delete，以及 patch 局部更新（支持 replace/add/remove 等操作）。
查询：支持简单 SQL 查询、参数化查询（推荐）、分页查询（maxItemCount 与 continuationToken）、跨分区查询（enableCrossPartitionQuery）。
批量操作：executeBulkOperations 支持 Create、Upsert、Read、Replace、Delete、Patch 等操作类型，并可按返回状态码逐条判断成功与否。
分区键：支持简单分区键与分层分区键（MultiHash，需 PartitionKeyDefinitionVersion.V2 与 PartitionKeyKind.MultiHash），分层分区键操作需传入分区键值数组。
错误处理：通过 ErrorResponse 判断状态码，如 404（未找到）、409（冲突）、412（前置条件失败/ETag 不匹配）、429（限流，可读取 retryAfterInMs）。
乐观并发：基于 ETag 的 IfMatch 访问条件，防止并发更新丢失。

类型导入：可从 @azure/cosmos 导入 CosmosClient、Database、Container、Item、Items、OperationInput、BulkOperationType、PatchOperation、SqlQuerySpec、SqlParameter、FeedOptions、PartitionKeyDefinition、PartitionKeyDefinitionVersion、PartitionKeyKind、ItemResponse、FeedResponse、ResourceResponse、ErrorResponse 等。
服务层模式：可将 Container 封装进服务类（如 ProductService），提供 getById、create、findByCategory 等方法，并在 404 时返回 null。

适用于在 JavaScript/TypeScript 应用中操作 Azure Cosmos DB NoSQL API 数据平面的任务，包括文档增删改查、参数化与分页查询、批量写入、分区键设计、ETag 并发控制与错误重试等。