Azure Cosmos DB Java SDK 实战指南基于 agentic-awesome-skills 技能的全局分布式 NoSQL 开发【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本文以 agentic-awesome-skills 仓库中收录的azure-cosmos-java技能SKILL.md为核心系统讲解 Azure Cosmos DB NoSQL API 在 Java 生态中的接入、认证、数据操作与调优实践。读完本文你将掌握 Maven 依赖配置、同步/异步客户端构建、数据库与容器创建、CRUD 与 SQL 查询、分区键设计、一致性级别选择、请求单元RU监控以及异常处理等完整开发链路可直接用于构建具备全球分布能力的高吞吐 Java 应用。技能背景它在 agentic-awesome-skills 中的定位在 agentic-awesome-skills 的 技能索引第 6829 行起与 目录文件第 8134 行起中azure-cosmos-java被登记为IDazure-cosmos-java路径指向skills/azure-cosmos-java分类cloud风险等级critical涉及生产数据库操作需谨慎使用来源community标签与触发词azure、cosmos、java、db、sdk、nosql、database、operations、global、distribution、multi、model该技能在插件层面同时支持 Codex 与 Claude 两类 Agent 目标见索引中的plugin.targets字段且无需额外 setupsetup.type为none。仓库中还收录了同系列的azure-cosmos-py、azure-cosmos-db-py、azure-cosmos-rust、azure-cosmos-ts等变体技能说明这是一个覆盖多语言的 Azure Cosmos DB 技能家族本文聚焦 Java SDKcom.azure:azure-cosmos这一主线。技能描述的定位是Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.——即全局分布、多模型支持与响应式Reactive编程模式是本文展开的三大技术主线。Maven 依赖安装使用 Java SDK v4com.azure:azure-cosmos在pom.xml中声明依赖dependency groupIdcom.azure/groupId artifactIdazure-cosmos/artifactId versionLATEST/version /dependency注意LATEST仅为文档占位写法生产项目请替换为经过验证的具体版本号避免依赖解析不稳定。推荐使用 Azure SDK BOM 统一版本为避免各 Azure SDK 组件版本互相冲突更推荐引入 Azure SDK BOMBill of Materials进行版本管理dependencyManagement dependencies dependency groupIdcom.azure/groupId artifactIdazure-sdk-bom/artifactId version{bom_version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdcom.azure/groupId artifactIdazure-cosmos/artifactId /dependency /dependenciesBOM 模式下无需为azure-cosmos显式指定版本由 BOM 统一锁定显著降低多依赖项目的版本维护成本。环境变量配置SDK 通过环境变量获取账号连接信息推荐按以下方式设置切勿硬编码密钥COSMOS_ENDPOINThttps://account.documents.azure.com:443/ COSMOS_KEYyour-primary-key其中COSMOS_ENDPOINT是 Cosmos DB 账户的 URIAzure 门户中Keys页可见COSMOS_KEY为主读写密钥。生产环境应配合密钥管理服务如 Azure Key Vault使用。客户端构建与认证方式基于密钥的同步认证import com.azure.cosmos.CosmosClient; import com.azure.cosmos.CosmosClientBuilder; CosmosClient client new CosmosClientBuilder() .endpoint(System.getenv(COSMOS_ENDPOINT)) .key(System.getenv(COSMOS_KEY)) .buildClient();异步客户端import com.azure.cosmos.CosmosAsyncClient; CosmosAsyncClient asyncClient new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .buildAsyncClient();异步客户端基于 ReactorProject Reactor实现响应式流返回Mono/Flux类型适合高并发与背压场景是技能描述中 reactive patterns 的落地载体。带自定义配置的客户端import com.azure.cosmos.ConsistencyLevel; import java.util.Arrays; CosmosClient client new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .directMode(directConnectionConfig, gatewayConnectionConfig) .consistencyLevel(ConsistencyLevel.SESSION) .connectionSharingAcrossClientsEnabled(true) .contentResponseOnWriteEnabled(true) .userAgentSuffix(my-application) .preferredRegions(Arrays.asList(West US, East US)) .buildClient();各配置项的作用配置项作用directMode(...)启用 Direct 连接模式绕过网关直连后端副本生产环境延迟最低consistencyLevel(ConsistencyLevel.SESSION)设置客户端默认一致性级别connectionSharingAcrossClientsEnabled(true)多个客户端实例共享连接降低连接开销contentResponseOnWriteEnabled(true)写入后响应中直接返回写入内容便于立即读取userAgentSuffix(my-application)附加自定义 UA 后缀便于在服务端遥测中识别请求来源preferredRegions(Arrays.asList(...))配置首选区域列表实现就近读取与多区域容灾客户端对象层级SDK 采用三级对象层次对应不同粒度的操作ClassPurposeCosmosClient/CosmosAsyncClientAccount-level operations账户级枚举/创建数据库等CosmosDatabase/CosmosAsyncDatabaseDatabase operations数据库级创建/管理容器CosmosContainer/CosmosAsyncContainerContainer/item operations容器级数据 CRUD 与查询理解这一层级是正确使用 SDK 的前提客户端是重量级对象应复用数据库与容器对象均由客户端派生client.getDatabase(...)/database.getContainer(...)不要手动 new。核心工作流从数据库到容器创建数据库若不存在// Sync client.createDatabaseIfNotExists(myDatabase) .map(response - client.getDatabase(response.getProperties().getId())); // Async with chaining asyncClient.createDatabaseIfNotExists(myDatabase) .map(response - asyncClient.getDatabase(response.getProperties().getId())) .subscribe(database - System.out.println(Created: database.getId()));createDatabaseIfNotExists是幂等操作已存在时不报错适合应用启动时的初始化阶段。创建容器若不存在asyncClient.createDatabaseIfNotExists(myDatabase) .flatMap(dbResponse - { String databaseId dbResponse.getProperties().getId(); return asyncClient.getDatabase(databaseId) .createContainerIfNotExists(myContainer, /partitionKey) .map(containerResponse - asyncClient.getDatabase(databaseId) .getContainer(containerResponse.getProperties().getId())); }) .subscribe(container - System.out.println(Container: container.getId()));注意容器创建时第二个参数/partitionKey即分区键路径它一旦设定便不可更改需要重新建容器因此创建前务必做好分区键设计见下文分区键一节。CRUD 操作异步链式示例import com.azure.cosmos.models.PartitionKey; CosmosAsyncContainer container asyncClient .getDatabase(myDatabase) .getContainer(myContainer); // Create container.createItem(new User(1, John Doe, johnexample.com)) .flatMap(response - { System.out.println(Created: response.getItem()); // Read return container.readItem( response.getItem().getId(), new PartitionKey(response.getItem().getId()), User.class); }) .flatMap(response - { System.out.println(Read: response.getItem()); // Update User user response.getItem(); user.setEmail(john.doeexample.com); return container.replaceItem( user, user.getId(), new PartitionKey(user.getId())); }) .flatMap(response - { // Delete return container.deleteItem( response.getItem().getId(), new PartitionKey(response.getItem().getId())); }) .block();要点拆解分区键必须显式提供所有点操作readItem、replaceItem、deleteItem都要求传入PartitionKey这是路由到正确物理分区的依据replaceItem是全量替换User对象需携带完整数据若只想改部分字段应使用PatchItem系列 API链式风格flatMap将创建→读取→更新→删除串成一个响应式管道最后block()阻塞等待完成仅限演示/同步上下文使用Web 应用中应避免阻塞。SQL 查询文档import com.azure.cosmos.models.CosmosQueryRequestOptions; import com.azure.cosmos.util.CosmosPagedIterable; CosmosContainer container client.getDatabase(myDatabase).getContainer(myContainer); String query SELECT * FROM c WHERE c.status status; CosmosQueryRequestOptions options new CosmosQueryRequestOptions(); CosmosPagedIterableUser results container.queryItems( query, options, User.class ); results.forEach(user - System.out.println(User: user.getName()));查询使用 Cosmos DB 的类 SQL 语法status为参数化占位符可避免注入并提升计划缓存命中率。同步客户端返回CosmosPagedIterable可惰性分页迭代异步客户端对应CosmosPagedFlux。查询会跨越容器内所有分区执行吞吐消耗与查询范围相关应尽量让查询条件包含分区键以缩小扫描范围。关键概念决定性能与成本的三要素分区键Partition Key分区键是 Cosmos DB 数据分布与水平扩展的基础技能文档给出的选择准则高基数High cardinality拥有大量不同的取值避免数据倾斜数据与请求分布均匀Even distribution各分区负载均衡防止单分区热点查询中频繁使用Frequently used in queries让查询能直接定位分区降低 RU 消耗。常见反例使用常量字段如status只有两三个取值或单调递增的 ID 作为分区键都会造成分区热点或跨分区查询。一致性级别Consistency LevelsCosmos DB 提供五种可权衡的一致性模型技能文档整理如下LevelGuaranteeStrongLinearizability线性一致性读总能看到最新已提交写入Bounded StalenessConsistent prefix with bounded lag有界滞后的一致前缀SessionConsistent prefix within session会话内一致前缀默认级别Consistent PrefixReads never see out-of-order writes读永不看到乱序写入EventualNo ordering guarantee最终一致无顺序保证从 Strong 到 Eventual一致性要求逐步放松读写延迟与可用性逐步提升。生产环境如无强一致性需求默认的 Session 级别通常是最佳性价比选择。请求单元Request Units, RU所有操作读、写、查询都按请求单元计费。通过响应头获取实际消耗CosmosItemResponseUser response container.createItem(user); System.out.println(RU charge: response.getRequestCharge());RU 是容量规划与成本控制的核心指标吞吐按 RU/s 预配或使用无服务器模式按量计费监控getRequestCharge()可定位高消耗操作并针对性优化如调整查询、缩小扫描范围、优化索引策略。错误处理与重试import com.azure.cosmos.CosmosException; try { container.createItem(item); } catch (CosmosException e) { System.err.println(Status: e.getStatusCode()); System.err.println(Message: e.getMessage()); System.err.println(Request charge: e.getRequestCharge()); if (e.getStatusCode() 409) { System.err.println(Item already exists); } else if (e.getStatusCode() 429) { System.err.println(Rate limited, retry after: e.getRetryAfterDuration()); } }常见状态码处理策略409 Conflict文档 ID 冲突已存在通常的业务处理是读取后合并或忽略429 Too Many Requests超出预配 RU/s被限流。SDK 内置了默认重试策略技能文档 Best Practices 中明确built-in by default应用层可结合getRetryAfterDuration()决定是否降级或增加预配吞吐449并发写入冲突通常可重试。对于长耗时的高吞吐应用还应配置ThrottlingRetryOptions的重试次数与退避参数避免在限流风暴下无限重试。最佳实践清单技能文档给出了七条实战准则逐条展开复用 CosmosClient— 客户端创建一次、全应用共享它是重量级对象内部维护连接池反复创建会耗尽连接并拖慢启动高吞吐场景使用异步客户端—CosmosAsyncClient Reactor 流能充分利用非阻塞 IO支撑更高并发谨慎选择分区键— 直接影响性能与可扩展性且创建后不可修改是数据建模阶段最重要的决策开启写入内容响应—contentResponseOnWriteEnabled(true)让写操作直接返回完整文档省去一次读请求为多区域应用配置首选区域—preferredRegions(...)实现就近读取与故障转移处理 429 错误— 依赖 SDK 内置重试策略并结合业务重试与容量告警生产环境使用 Direct 模式— 直连后端副本延迟最低Gateway 模式更适合防火墙受限或调试场景。技能使用边界与注意事项按照该技能risk: critical级别自身的约束说明适用时机仅当任务与上述工作流/操作范围明确匹配时使用本技能不替代专业验证技能输出不能替代针对具体环境的验证、测试或专家评审如容量评估、安全审查仍需人工完成及时澄清当所需输入、权限、安全边界或成功标准缺失时应停止并请求澄清而不是盲目执行破坏性操作例如删除容器、批量替换数据前必须先确认目标环境。延伸阅读本技能原文plugins/agentic-awesome-skills-claude/skills/azure-cosmos-java/SKILL.md技能索引条目data/skills_index.jsonid: azure-cosmos-java目录与触发词定义data/catalog.jsoncanonical_id: azure-cosmos-java同系列多语言变体azure-cosmos-py、azure-cosmos-db-py、azure-cosmos-rust、azure-cosmos-ts等技能同样收录于 skills 目录 中可对照学习其他语言的 SDK 用法。以上就是基于 agentic-awesome-skills 中azure-cosmos-java技能的完整实战指南从依赖接入、客户端构建、CRUD 与查询到分区键、一致性与 RU 三大核心概念的权衡再到错误处理与生产最佳实践覆盖了 Java 开发者使用 Azure Cosmos DB NoSQL API 的全链路要点。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Azure Cosmos DB Java SDK 实战指南：基于 agentic-awesome-skills 技能的全局分布式 NoSQL 开发
Azure Cosmos DB Java SDK 实战指南基于 agentic-awesome-skills 技能的全局分布式 NoSQL 开发【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills本文以 agentic-awesome-skills 仓库中收录的azure-cosmos-java技能SKILL.md为核心系统讲解 Azure Cosmos DB NoSQL API 在 Java 生态中的接入、认证、数据操作与调优实践。读完本文你将掌握 Maven 依赖配置、同步/异步客户端构建、数据库与容器创建、CRUD 与 SQL 查询、分区键设计、一致性级别选择、请求单元RU监控以及异常处理等完整开发链路可直接用于构建具备全球分布能力的高吞吐 Java 应用。技能背景它在 agentic-awesome-skills 中的定位在 agentic-awesome-skills 的 技能索引第 6829 行起与 目录文件第 8134 行起中azure-cosmos-java被登记为IDazure-cosmos-java路径指向skills/azure-cosmos-java分类cloud风险等级critical涉及生产数据库操作需谨慎使用来源community标签与触发词azure、cosmos、java、db、sdk、nosql、database、operations、global、distribution、multi、model该技能在插件层面同时支持 Codex 与 Claude 两类 Agent 目标见索引中的plugin.targets字段且无需额外 setupsetup.type为none。仓库中还收录了同系列的azure-cosmos-py、azure-cosmos-db-py、azure-cosmos-rust、azure-cosmos-ts等变体技能说明这是一个覆盖多语言的 Azure Cosmos DB 技能家族本文聚焦 Java SDKcom.azure:azure-cosmos这一主线。技能描述的定位是Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.——即全局分布、多模型支持与响应式Reactive编程模式是本文展开的三大技术主线。Maven 依赖安装使用 Java SDK v4com.azure:azure-cosmos在pom.xml中声明依赖dependency groupIdcom.azure/groupId artifactIdazure-cosmos/artifactId versionLATEST/version /dependency注意LATEST仅为文档占位写法生产项目请替换为经过验证的具体版本号避免依赖解析不稳定。推荐使用 Azure SDK BOM 统一版本为避免各 Azure SDK 组件版本互相冲突更推荐引入 Azure SDK BOMBill of Materials进行版本管理dependencyManagement dependencies dependency groupIdcom.azure/groupId artifactIdazure-sdk-bom/artifactId version{bom_version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdcom.azure/groupId artifactIdazure-cosmos/artifactId /dependency /dependenciesBOM 模式下无需为azure-cosmos显式指定版本由 BOM 统一锁定显著降低多依赖项目的版本维护成本。环境变量配置SDK 通过环境变量获取账号连接信息推荐按以下方式设置切勿硬编码密钥COSMOS_ENDPOINThttps://account.documents.azure.com:443/ COSMOS_KEYyour-primary-key其中COSMOS_ENDPOINT是 Cosmos DB 账户的 URIAzure 门户中Keys页可见COSMOS_KEY为主读写密钥。生产环境应配合密钥管理服务如 Azure Key Vault使用。客户端构建与认证方式基于密钥的同步认证import com.azure.cosmos.CosmosClient; import com.azure.cosmos.CosmosClientBuilder; CosmosClient client new CosmosClientBuilder() .endpoint(System.getenv(COSMOS_ENDPOINT)) .key(System.getenv(COSMOS_KEY)) .buildClient();异步客户端import com.azure.cosmos.CosmosAsyncClient; CosmosAsyncClient asyncClient new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .buildAsyncClient();异步客户端基于 ReactorProject Reactor实现响应式流返回Mono/Flux类型适合高并发与背压场景是技能描述中 reactive patterns 的落地载体。带自定义配置的客户端import com.azure.cosmos.ConsistencyLevel; import java.util.Arrays; CosmosClient client new CosmosClientBuilder() .endpoint(serviceEndpoint) .key(key) .directMode(directConnectionConfig, gatewayConnectionConfig) .consistencyLevel(ConsistencyLevel.SESSION) .connectionSharingAcrossClientsEnabled(true) .contentResponseOnWriteEnabled(true) .userAgentSuffix(my-application) .preferredRegions(Arrays.asList(West US, East US)) .buildClient();各配置项的作用配置项作用directMode(...)启用 Direct 连接模式绕过网关直连后端副本生产环境延迟最低consistencyLevel(ConsistencyLevel.SESSION)设置客户端默认一致性级别connectionSharingAcrossClientsEnabled(true)多个客户端实例共享连接降低连接开销contentResponseOnWriteEnabled(true)写入后响应中直接返回写入内容便于立即读取userAgentSuffix(my-application)附加自定义 UA 后缀便于在服务端遥测中识别请求来源preferredRegions(Arrays.asList(...))配置首选区域列表实现就近读取与多区域容灾客户端对象层级SDK 采用三级对象层次对应不同粒度的操作ClassPurposeCosmosClient/CosmosAsyncClientAccount-level operations账户级枚举/创建数据库等CosmosDatabase/CosmosAsyncDatabaseDatabase operations数据库级创建/管理容器CosmosContainer/CosmosAsyncContainerContainer/item operations容器级数据 CRUD 与查询理解这一层级是正确使用 SDK 的前提客户端是重量级对象应复用数据库与容器对象均由客户端派生client.getDatabase(...)/database.getContainer(...)不要手动 new。核心工作流从数据库到容器创建数据库若不存在// Sync client.createDatabaseIfNotExists(myDatabase) .map(response - client.getDatabase(response.getProperties().getId())); // Async with chaining asyncClient.createDatabaseIfNotExists(myDatabase) .map(response - asyncClient.getDatabase(response.getProperties().getId())) .subscribe(database - System.out.println(Created: database.getId()));createDatabaseIfNotExists是幂等操作已存在时不报错适合应用启动时的初始化阶段。创建容器若不存在asyncClient.createDatabaseIfNotExists(myDatabase) .flatMap(dbResponse - { String databaseId dbResponse.getProperties().getId(); return asyncClient.getDatabase(databaseId) .createContainerIfNotExists(myContainer, /partitionKey) .map(containerResponse - asyncClient.getDatabase(databaseId) .getContainer(containerResponse.getProperties().getId())); }) .subscribe(container - System.out.println(Container: container.getId()));注意容器创建时第二个参数/partitionKey即分区键路径它一旦设定便不可更改需要重新建容器因此创建前务必做好分区键设计见下文分区键一节。CRUD 操作异步链式示例import com.azure.cosmos.models.PartitionKey; CosmosAsyncContainer container asyncClient .getDatabase(myDatabase) .getContainer(myContainer); // Create container.createItem(new User(1, John Doe, johnexample.com)) .flatMap(response - { System.out.println(Created: response.getItem()); // Read return container.readItem( response.getItem().getId(), new PartitionKey(response.getItem().getId()), User.class); }) .flatMap(response - { System.out.println(Read: response.getItem()); // Update User user response.getItem(); user.setEmail(john.doeexample.com); return container.replaceItem( user, user.getId(), new PartitionKey(user.getId())); }) .flatMap(response - { // Delete return container.deleteItem( response.getItem().getId(), new PartitionKey(response.getItem().getId())); }) .block();要点拆解分区键必须显式提供所有点操作readItem、replaceItem、deleteItem都要求传入PartitionKey这是路由到正确物理分区的依据replaceItem是全量替换User对象需携带完整数据若只想改部分字段应使用PatchItem系列 API链式风格flatMap将创建→读取→更新→删除串成一个响应式管道最后block()阻塞等待完成仅限演示/同步上下文使用Web 应用中应避免阻塞。SQL 查询文档import com.azure.cosmos.models.CosmosQueryRequestOptions; import com.azure.cosmos.util.CosmosPagedIterable; CosmosContainer container client.getDatabase(myDatabase).getContainer(myContainer); String query SELECT * FROM c WHERE c.status status; CosmosQueryRequestOptions options new CosmosQueryRequestOptions(); CosmosPagedIterableUser results container.queryItems( query, options, User.class ); results.forEach(user - System.out.println(User: user.getName()));查询使用 Cosmos DB 的类 SQL 语法status为参数化占位符可避免注入并提升计划缓存命中率。同步客户端返回CosmosPagedIterable可惰性分页迭代异步客户端对应CosmosPagedFlux。查询会跨越容器内所有分区执行吞吐消耗与查询范围相关应尽量让查询条件包含分区键以缩小扫描范围。关键概念决定性能与成本的三要素分区键Partition Key分区键是 Cosmos DB 数据分布与水平扩展的基础技能文档给出的选择准则高基数High cardinality拥有大量不同的取值避免数据倾斜数据与请求分布均匀Even distribution各分区负载均衡防止单分区热点查询中频繁使用Frequently used in queries让查询能直接定位分区降低 RU 消耗。常见反例使用常量字段如status只有两三个取值或单调递增的 ID 作为分区键都会造成分区热点或跨分区查询。一致性级别Consistency LevelsCosmos DB 提供五种可权衡的一致性模型技能文档整理如下LevelGuaranteeStrongLinearizability线性一致性读总能看到最新已提交写入Bounded StalenessConsistent prefix with bounded lag有界滞后的一致前缀SessionConsistent prefix within session会话内一致前缀默认级别Consistent PrefixReads never see out-of-order writes读永不看到乱序写入EventualNo ordering guarantee最终一致无顺序保证从 Strong 到 Eventual一致性要求逐步放松读写延迟与可用性逐步提升。生产环境如无强一致性需求默认的 Session 级别通常是最佳性价比选择。请求单元Request Units, RU所有操作读、写、查询都按请求单元计费。通过响应头获取实际消耗CosmosItemResponseUser response container.createItem(user); System.out.println(RU charge: response.getRequestCharge());RU 是容量规划与成本控制的核心指标吞吐按 RU/s 预配或使用无服务器模式按量计费监控getRequestCharge()可定位高消耗操作并针对性优化如调整查询、缩小扫描范围、优化索引策略。错误处理与重试import com.azure.cosmos.CosmosException; try { container.createItem(item); } catch (CosmosException e) { System.err.println(Status: e.getStatusCode()); System.err.println(Message: e.getMessage()); System.err.println(Request charge: e.getRequestCharge()); if (e.getStatusCode() 409) { System.err.println(Item already exists); } else if (e.getStatusCode() 429) { System.err.println(Rate limited, retry after: e.getRetryAfterDuration()); } }常见状态码处理策略409 Conflict文档 ID 冲突已存在通常的业务处理是读取后合并或忽略429 Too Many Requests超出预配 RU/s被限流。SDK 内置了默认重试策略技能文档 Best Practices 中明确built-in by default应用层可结合getRetryAfterDuration()决定是否降级或增加预配吞吐449并发写入冲突通常可重试。对于长耗时的高吞吐应用还应配置ThrottlingRetryOptions的重试次数与退避参数避免在限流风暴下无限重试。最佳实践清单技能文档给出了七条实战准则逐条展开复用 CosmosClient— 客户端创建一次、全应用共享它是重量级对象内部维护连接池反复创建会耗尽连接并拖慢启动高吞吐场景使用异步客户端—CosmosAsyncClient Reactor 流能充分利用非阻塞 IO支撑更高并发谨慎选择分区键— 直接影响性能与可扩展性且创建后不可修改是数据建模阶段最重要的决策开启写入内容响应—contentResponseOnWriteEnabled(true)让写操作直接返回完整文档省去一次读请求为多区域应用配置首选区域—preferredRegions(...)实现就近读取与故障转移处理 429 错误— 依赖 SDK 内置重试策略并结合业务重试与容量告警生产环境使用 Direct 模式— 直连后端副本延迟最低Gateway 模式更适合防火墙受限或调试场景。技能使用边界与注意事项按照该技能risk: critical级别自身的约束说明适用时机仅当任务与上述工作流/操作范围明确匹配时使用本技能不替代专业验证技能输出不能替代针对具体环境的验证、测试或专家评审如容量评估、安全审查仍需人工完成及时澄清当所需输入、权限、安全边界或成功标准缺失时应停止并请求澄清而不是盲目执行破坏性操作例如删除容器、批量替换数据前必须先确认目标环境。延伸阅读本技能原文plugins/agentic-awesome-skills-claude/skills/azure-cosmos-java/SKILL.md技能索引条目data/skills_index.jsonid: azure-cosmos-java目录与触发词定义data/catalog.jsoncanonical_id: azure-cosmos-java同系列多语言变体azure-cosmos-py、azure-cosmos-db-py、azure-cosmos-rust、azure-cosmos-ts等技能同样收录于 skills 目录 中可对照学习其他语言的 SDK 用法。以上就是基于 agentic-awesome-skills 中azure-cosmos-java技能的完整实战指南从依赖接入、客户端构建、CRUD 与查询到分区键、一致性与 RU 三大核心概念的权衡再到错误处理与生产最佳实践覆盖了 Java 开发者使用 Azure Cosmos DB NoSQL API 的全链路要点。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考