Azure Cosmos DB 开发人员指南

  • 项目

适用于 Azure Cosmos DB 的 Azure Spring Data 为 Azure Cosmos DB for NoSQL 提供 Spring Data 支持。 Azure Cosmos DB 是一种全球分布式数据库服务，允许开发人员使用各种标准 API（例如 SQL、MongoDB、Cassandra、Graph 和表）处理数据。

本指南将指导你了解 Azure Spring Data Azure Cosmos DB SDK、支持的功能、故障排除和已知问题的概念。 有关以下概念和代码示例的详细信息，请参阅 适用于 Azure Cosmos DB SDK 的 Spring Data 自述文件。

版本支持策略

Spring Boot 版本支持

此项目支持多个 Spring Boot 版本。 有关详细信息，请参阅 Spring Boot 支持策略。 Maven 用户可从 spring-boot-starter-parent 项目继承来获取依赖项管理部分，使 Spring 能够管理依赖项的版本。 有关详细信息，请参阅 Spring Boot 版本支持。

Spring Data 版本支持

此项目支持不同的 spring-data-commons 版本。 有关详细信息，请参阅 Spring Data 版本支持。

要使用的 Azure Spring Data Azure Cosmos DB 版本

Azure Spring Data Azure Cosmos DB 库支持多个版本的 Spring Boot / Spring Cloud。 有关要与 Spring Boot/Spring Cloud 版本一起使用的 Azure Spring Data Azure Cosmos DB 版本的详细信息，请参阅我应使用哪个版本的 Azure Cosmos DB 的 Azure Spring Data？

开始使用

添加包

如果使用 Maven，请添加以下依赖项。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

先决条件

仅当计划使用日志记录时，才需要 SLF4J。另请下载 SLF4J 绑定，该绑定可将 SLF4J API 与你选择的记录实现链接在一起。 有关详细信息，请参阅 SLF4J 用户手册。

设置和自定义配置类

若要设置配置类，需要扩展 AbstractCosmosConfiguration。 有关详细信息，请参阅 安装程序配置类。

可以通过提供或同时提供DirectConnectionConfig或GatewayConnectionConfig同时提供它们来CosmosClientBuilder自定义 Azure Spring Data Azure Cosmos DB SDK 使用的基础CosmosAsyncClient。 有关完整示例，请访问 自定义配置部分。

实体设置

可以将简单实体定义为 Azure Cosmos DB 中的项。 可以通过添加 @Container 批注并指定与容器相关的属性来定义实体。 有关详细信息，请参阅 “定义实体”。

容器注释支持指定容器名称、 请求单位 （RU）、生存时间、 创建具有自动缩放吞吐量的容器、 嵌套分区键支持和其他容器属性。

存储库设置

Azure Spring Data Azure Cosmos DB 支持 ReactiveCrudRepository （异步 API）和 CrudRepository （同步 API），提供以下基本 CRUD 功能：

  • 保存
  • findAll
  • findOne by ID
  • deleteAll
  • delete by ID
  • delete entity

可以扩展 CosmosRepository （用于同步 API 支持）或 ReactiveCosmosRepository （对于异步 API 支持），为应用程序设置 Spring Data 存储库。 有关详细信息，请参阅 “创建存储库”。

Azure Spring Data Azure Cosmos DB 支持使用 @Query 在存储库中指定带批注的查询。 有关详细信息，请参阅 QueryAnnotation：在存储库中使用带批注的查询。

Spring Data 注释

Spring Data @Id 注释

可通过多种方式将域类中的字段映射到 id。 有关详细信息，请参阅 Spring 数据 ID 注释代码部分。

ID 自动生成

Azure Spring Data Azure Cosmos DB 支持使用 @GeneratedValue 批注自动生成 ID。 有关详细信息，请参阅 ID 自动生成部分。

SpEL 表达式和自定义容器名称

默认情况下，容器名称将是用户域类的类名。 若要自定义，请将 @Container(containerName="myCustomContainerName") 批注添加到域类。 有关详细信息，请参阅 SpEL 表达式和自定义容器名称部分。

自定义 IndexingPolicy

默认情况下， IndexingPolicy Azure 服务将设置。 若要自定义，请将批注 @CosmosIndexingPolicy 添加到域类。 有关详细信息，请参阅 索引策略部分。

唯一密钥策略

Azure Spring Data Azure Cosmos DB 支持通过将批注@CosmosUniqueKeyPolicy添加到域类来设置UniqueKeyPolicy容器。 有关详细信息，请参阅 唯一密钥策略部分。

Azure Cosmos DB 分区

Azure-spring-data-cosmos 支持 Azure Cosmos DB 分区。

若要将域类的字段指定为分区键字段，只需为其 @PartitionKey添加批注。

执行 CRUD 操作时，指定分区值。

有关详细信息，请参阅 此处的测试部分。

乐观锁定

Azure-spring-data-cosmos 支持特定容器的乐观锁定，这意味着项目向上插入/删除将失败，以防同时由另一个进程修改该项时失败。 有关详细信息，请参阅 乐观锁定部分。

Spring Data 自定义查询，可分页和排序

Azure-spring-data-cosmos 支持 Spring Data 自定义查询，例如查找操作，例如 findByAFieldAndBField。 它还支持 Spring Data Pageable、Slice 和 Sort。 有关详细信息，请参阅 查询、可分页和排序部分。

通过 Spring Data Cosmos 使用 Azure Cosmos DB Java SDK

Azure-spring-data-cosmos 支持使用 Azure Cosmos DB Java SDK。 用户可以获取CosmosClient或运行 ApplicationContext Azure Cosmos DB Java SDK 支持的任何操作。CosmosAsyncClient 有关详细信息，请参阅 通过 Spring Data Cosmos 节使用 Azure Cosmos 客户端。

Spring Data REST

Azure-spring-data-cosmos 支持 Spring Data REST。 有关详细信息，请参阅 Azure Spring Data Azure Cosmos DB REST API 部分。

审核

Azure-spring-data-cosmos 支持使用标准 spring-data 批注对数据库实体的审核字段。 有关详细信息，请参阅 Spring Data Azure Cosmos DB 审核部分。

多数据库配置

Azure-spring-data-cosmos 支持多数据库配置，包括“多个数据库帐户”和“具有多个数据库的单个帐户”。 有关完整的代码片段，请参阅 多数据库配置部分。

疑难解答

常规

如果遇到任何 bug，请在此处提出问题。

若要建议新功能或可以进行的更改，请以与提交 bug 相同的方式提交问题。

启用客户端日志记录

Azure-spring-data-cosmos 使用 SLF4j 作为日志记录外观，支持登录到常用的日志记录框架，例如 log4j 和 logback。 有关详细信息，请参阅 “启用客户端日志记录”部分。

示例

有关完整的示例项目，请参阅 示例项目。

多数据库帐户

有关完整的示例项目，请参阅 多数据库示例项目。

具有多个数据库的单个帐户

有关完整的示例项目，请参阅 包含多数据库示例项目的单个帐户。

后续步骤

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人会自动确定是否需要提供 CLA 并适当修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 在所有存储库中执行此操作一次。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，如有任何其他问题或评论，请联系 opencode@microsoft.com。

Impressions