Azure Cosmos DB 开发指南

Azure Spring Data for Azure Cosmos DB 为 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 Spring Data for Azure Cosmos DB？

开始

添加包

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

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

先决条件

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

设置和自定义配置类

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

您可以通过提供 GatewayConnectionConfig、CosmosClientBuilder 或同时提供两者，并将其传递给 CosmosAsyncClient，来自定义 Azure Spring Data Azure Cosmos DB SDK 使用的底层 DirectConnectionConfig。 有关完整示例，请访问 自定义配置部分。

实体设置

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

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

存储库设置

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

  • 保存
  • findAll (查找所有)
  • findOne 按 ID
  • 删除全部
  • 按 ID 删除
  • 删除实体

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

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

Spring数据注解

Spring Data @Id 注释

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

身份证号自动生成.

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

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

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

自定义索引策略

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

唯一键策略

Azure Spring Data Azure Cosmos DB 支持通过在域类上添加 UniqueKeyPolicy 注解来设置容器上的 @CosmosUniqueKeyPolicy。 有关详细信息，请参阅唯一键策略部分。

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. 可以通过 ApplicationContext 获取 CosmosClient 或 CosmosAsyncClient bean，并执行 Azure Cosmos DB Java SDK 支持的任何操作。 有关详细信息，请参阅通过 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。

  • Last updated on