Spring Data 支持

2024-12-22
适用于: ✅ Version 4.20.0, ✅ Version 5.22.0

本文介绍如何结合使用 Spring Cloud Azure 和 Spring Data。

Spring Data Azure Cosmos DB 支持

Azure Cosmos DB 是一种全球分布式数据库服务，开发人员可以使用各种标准 API（例如 SQL、MongoDB、Graph 和 Azure 表存储）处理数据。

依赖项设置

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>

配置

注意

如果使用安全主体通过 Microsoft Entra ID 进行身份验证和授权来访问 Azure 资源，请确保安全主体已获得足够的权限来访问 Azure 资源。有关详细信息，请参阅使用 Microsoft Entra ID授权访问。

下表列出了 spring-cloud-azure-starter-data-cosmos的可配置属性：

财产	描述
spring.cloud.azure.cosmos.enabled	一个值，该值指示是否启用了 Azure Cosmos DB 服务。默认值为 `true`。
spring.cloud.azure.cosmos.database	Azure Cosmos DB 数据库 ID。
spring.cloud.azure.cosmos.endpoint	用于连接 Azure Cosmos DB 的 URI。
spring.cloud.azure.cosmos.key	用于连接 Azure Cosmos DB 的 PrivateKey。
spring.cloud.azure.cosmos.credential.client-certificate-password	证书文件的密码。
spring.cloud.azure.cosmos.credential.client-certificate-path	使用 Azure 执行服务主体身份验证时要使用的 PEM 证书文件的路径。
spring.cloud.azure.cosmos.credential.client-id	使用 Azure 执行服务主体身份验证时要使用的客户端 ID。
spring.cloud.azure.cosmos.credential.client-secret	使用 Azure 执行服务主体身份验证时要使用的客户端密码。
spring.cloud.azure.cosmos.credential.managed-identity-enabled	是否启用托管标识。默认值为 `false`。
spring.cloud.azure.cosmos.credential.password	在 Azure 中执行用户名/密码身份验证时要使用的密码。
spring.cloud.azure.cosmos.credential.username	在 Azure 中执行用户名/密码身份验证时要使用的用户名。
spring.cloud.azure.cosmos.populate-query-metrics	一个值，该值指示是否填充诊断字符串和查询指标。默认值为 `false`。
spring.cloud.azure.cosmos.consistency-level	Azure Cosmos DB 的一致性级别。

关键概念

以下列表显示了 Spring Data 支持的关键概念：

Spring Data CrudRepository 和 ReactiveCrudRepository，提供以下基本 CRUD 功能：
- 救
- findAll
- findOne 按 ID
- deleteAll
- 按 ID 删除
- 删除实体
Spring Data @Id 批注。可通过两种方法将域类中的字段映射到 Azure Cosmos DB 文档的 id：
- 使用 @Id批注域类中的字段。此字段将映射到 Azure Cosmos DB 中的文档 id。
- 将此字段的名称设置为 id。此字段将映射到 Azure Cosmos DB 中的文档 id。
注意

如果应用这两种方式，则 @Id 批注的优先级更高。
自定义集合名称。默认情况下，集合名称将是用户域类的类名。若要对其进行自定义，请将批注 @Document(collection="myCustomCollectionName") 添加到域类，即全部。
支持 Azure Cosmos DB 分区。若要将域类的字段指定为分区键字段，请使用 @PartitionKey对其进行批注。执行 CRUD 操作时，请指定分区值。有关更多示例，请参阅 GitHub 上的 AddressRepositoryIT.java。
支持 Spring Data 自定义查询查找操作。
支持 spring-boot-starter-data-rest。
支持域类中的列表和嵌套类型。

基本用法

使用私钥访问 Azure Cosmos DB

使用 spring-cloud-azure-starter-data-cosmos 连接 Azure Cosmos DB 的最简单方法是使用主键。添加以下属性：

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${AZURE_COSMOS_DATABASE}

定义实体

将实体定义为 Azure Cosmos DB 中的文档，如以下示例所示：

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {
    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

id 字段将用作 Azure Cosmos DB 中的文档 id。或者，可以使用 @Id 批注任何字段，将其映射到文档 id。

批注 @Container(containerName = "mycollection") 用于在 Azure Cosmos DB 中指定文档的集合名称。

创建存储库

若要创建存储库，请扩展 ReactiveCosmosRepository 接口，该接口提供 Spring Data 存储库支持。

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

目前，ReactiveCosmosRepository 接口提供基本的保存、删除和查找操作。稍后将支持更多操作。

创建应用程序类

以下示例创建包含所有组件的应用程序类：

@SpringBootApplication
public class CosmosSampleApplication implements CommandLineRunner {

private static final Logger LOGGER = LoggerFactory.getLogger(CosmosSampleApplication.class);

    @Autowired
    private UserRepository repository;

    @Autowired
    private CosmosProperties properties;

    public static void main(String[] args) {
        SpringApplication.run(CosmosSampleApplication.class, args);
    }

    public void run(String... var1) {
        final User testUser = new User("testId", "testFirstName",
                "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()),
                "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()),
                "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()),
                "query result lastName doesn't match!");
        LOGGER.info("findOne in User collection get result: {}", result.toString());

    }

    @PostConstruct
    public void setup() {
        // For this example, remove all of the existing records.
        this.repository.deleteAll().block();
    }
}

此示例包含自动连接 UserRepository 接口，以支持保存、删除和查找操作。

样品

请参阅 GitHub 上的 azure-spring-boot-samples。

除了使用 spring-cloud-azure-starter-data-cosmos 库外，还可以直接将 azure-spring-data-cosmos 库用于更复杂的方案。有关详细信息，请参阅 Azure Cosmos DB 客户端库的 Spring Data。