将 Spanner 与 Spring Data 集成

Spring Data Spanner 模块可帮助您在任何 Java 中使用 Spanner 使用 Spring 框架。

与所有 Spring Data 模块一样， Spring Data Spanner 提供了一个基于 Spring 的编程模型， 保留了 Spanner 的一致性保证和可伸缩性。其 功能类似于 Spring Data JPA， Hibernate ORM，其中包含专为 Spanner。如需详细了解如何将 Spring Data JPA 与 Spanner 搭配使用，请参阅将 Spanner 与 Spring Data JPA（GoogleSQL 方言）集成。

如果您已熟悉 Spring，那么 Spring Data Spanner 可让您更轻松地在应用中使用 Spanner， 减少需要编写的代码量。

本页介绍了如何将 Spring Data Spanner 添加到 Java 应用。如需详细了解该模块，请参阅 Spring Data Spanner 参考文档。

安装模块

如果您使用 Maven，请将 Spring Cloud GCP 物料清单 (BOM) 和 Spring Data Spanner 添加到您的 pom.xml 文件。这些依赖项为 Spring ApplicationContext 提供了 Spring Data Spanner 组件：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>spring-cloud-gcp-dependencies</artifactId>
      <version>3.7.7</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>${spring.boot.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-data-spanner</artifactId>
  </dependency>
</dependencies>

您还必须创建服务账号并使用服务账号密钥向 Google Cloud 进行身份验证。

如需了解详情，请参阅有关设置 Java 开发环境的说明。您无需安装适用于 Java 的 Google Cloud 客户端库；Spring Boot 入门版会自动安装该客户端库。

配置模块

本部分介绍了一些最常用的配置设置， Spring Data Spanner。如需查看设置的完整列表，请参阅参考文档。

指定实例和数据库

如需指定默认实例和数据库，请为您的应用设置以下配置属性：

属性 说明
spring.cloud.gcp.spanner.project-id 可选。Google Cloud 项目 ID。替换 spring.cloud.gcp.config.project-id 的值。
spring.cloud.gcp.spanner.instance-id Spanner 实例 ID。
spring.cloud.gcp.spanner.database 要连接的数据库。

为 Spanner 数据建模

借助 Spring Data Spanner，您可以使用普通的旧 Java 对象 (POJO) 来 为存储在 Spanner 表中的数据建模。

对于数据库中的每个表，请声明表示该表中记录的实体。请使用注释将实体及其属性映射到表及其列。

您可以使用以下注释为实体与表之间的简单关系建模：

实体注释
@Column(name = "columnName")

可选。将属性映射到 Spanner 表中的特定列，从而替换自动映射名称的命名策略。

如果您省略此属性，则 Spring Data Spanner 映射 Java camelCase 属性 转换为 PascalCase 列名称。例如，属性 singerId 会映射到列名称 SingerId。
@Embedded

表示属性是可以容纳主键组成部分的嵌入式对象。如果属性实际会用在主键中，您还必须添加 @PrimaryKey 注释。

@Interleaved

@Interleaved(lazy = true)

表示属性包含与当前行交错的行的列表。

默认情况下，Spring Data Spanner 提取交错行 创建 Deployment如需延迟提取行，请在访问属性时使用 @Interleaved(lazy = true)。

示例：如果 Singer 实体可以将交错的 Album 条目作为子级，请将 List<Album> 属性添加到 Singer 实体。此外，请将 @Interleaved 注释添加到该属性。
@NotMapped

表示属性未存储在数据库中，应忽略。

@PrimaryKey

@PrimaryKey(keyOrder = N)

表示属性是主键的组成部分，并且标识属性在主键中的位置（从 1 开始）。keyOrder 的默认值为 1。

示例：@PrimaryKey(keyOrder = 3)

@Table(name = "TABLE_NAME")

实体为其建模的表。该实体的每个实例都代表该表中的一条记录。请将 TABLE_NAME 替换为您的表名称。

示例：@Table(name = "Singers")

如果您需要为更复杂的关系建模，请参阅 Spring Data Spanner 参考文档 详细了解该模块支持的其他注解。

以下示例演示了为 Spring Data Spanner 的 Singers 和 Albums 表建模的一种方法：

  • 对于 Singer 实体，该示例包含 albums 属性和 @Interleaved 注释。此属性包含与 Singer 实体交错的相册列表。Spring Data Spanner 进行填充 属性。
  • 对于 Album 实体，该示例包含一个 relatedAlbums 属性， 未存储在 Spanner 中。
import com.google.cloud.spring.data.spanner.core.mapping.Interleaved;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;
import java.util.Date;
import java.util.List;


/**
 * An entity and table holding singers.
 */
@Table(name = "Singers")
public class Singer {
  @PrimaryKey
  long singerId;

  String firstName;

  String lastName;

  Date birthDate;

  @Interleaved
  List<Album> albums;
}
 
import com.google.cloud.spring.data.spanner.core.mapping.NotMapped;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;
import java.util.List;

/**
 * An entity class representing an Album.
 */
@Table(name = "Albums")
public class Album {

  @PrimaryKey
  long singerId;

  @PrimaryKey(keyOrder = 2)
  long albumId;

  String albumTitle;

  long marketingBudget;

  @NotMapped
  List<Album> relatedAlbums;

  public Album(long singerId, long albumId, String albumTitle, long marketingBudget) {
    this.singerId = singerId;
    this.albumId = albumId;
    this.albumTitle = albumTitle;
    this.marketingBudget = marketingBudget;
  }
}

查询和修改数据

如需使用 Spring Data Spanner 查询和修改数据，您可以获取实现 SpannerOperations 的 SpannerTemplate Bean。SpannerTemplate 提供了一些使用数据操纵语言 (DML) 语句执行 SQL 查询和修改数据的方法。您还可以使用 通过此 Bean 访问读取 API 和变更 Spanner API。

此外，您还可以扩展 SpannerRepository 接口以封装在 Spanner 中查询和修改数据的所有应用逻辑。

以下几个部分介绍了如何使用 SpannerTemplate 和 SpannerRepository。

获取模板 Bean

使用 @Autowired 注释可以自动获取 SpannerTemplate Bean。然后，您可以在自己的类中使用 SpannerTemplate。

以下示例演示了获取和使用该 Bean 的类：

import com.google.cloud.spanner.KeySet;
import com.google.cloud.spanner.Statement;
import com.google.cloud.spring.data.spanner.core.SpannerQueryOptions;
import com.google.cloud.spring.data.spanner.core.SpannerTemplate;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * A quick start code for Spring Data Cloud Spanner. It demonstrates how to use SpannerTemplate to
 * execute DML and SQL queries, save POJOs, and read entities.
 */
@Component
public class SpannerTemplateSample {

  @Autowired
  SpannerTemplate spannerTemplate;

  public void runTemplateExample(Singer singer) {
    // Delete all of the rows in the Singer table.
    this.spannerTemplate.delete(Singer.class, KeySet.all());

    // Insert a singer into the Singers table.
    this.spannerTemplate.insert(singer);

    // Read all of the singers in the Singers table.
    List<Singer> allSingers = this.spannerTemplate
        .query(Singer.class, Statement.of("SELECT * FROM Singers"),
                new SpannerQueryOptions().setAllowPartialRead(true));
  }

}

您可以使用 SpannerTemplate Bean 执行只读事务和读写事务。此外，您还可以使用 @Transactional 注释创建声明式事务。

获取代码库 Bean

如果您使用 SpannerRepository，则可以使用 @Autowired 注释获取实现代码库接口的 Bean。代码库包含一些方法，用于将 Java 函数作为只读事务和读写事务来运行。对于较低级别的操作，您可以获取代码库使用的模板 Bean。

以下几个示例演示了代码库的接口以及获取和使用该 Bean 的类：

import com.google.cloud.spanner.Key;
import com.google.cloud.spring.data.spanner.repository.SpannerRepository;
import com.google.cloud.spring.data.spanner.repository.query.Query;
import java.util.List;
import org.springframework.data.repository.query.Param;


/**
 * An interface of various Query Methods. The behavior of the queries is defined only by
 * their names, arguments, or annotated SQL strings. The implementation of these functions
 * is generated by Spring Data Cloud Spanner.
 */
public interface SingerRepository extends SpannerRepository<Singer, Key> {
  List<Singer> findByLastName(String lastName);

  int countByFirstName(String firstName);

  int deleteByLastName(String lastName);

  List<Singer> findTop3DistinctByFirstNameAndSingerIdIgnoreCaseOrLastNameOrderByLastNameDesc(
      String firstName, String lastName, long singerId);

  @Query("SELECT * FROM Singers WHERE firstName LIKE '%@fragment';")
  List<Singer> getByQuery(@Param("fragment") String firstNameFragment);
}
 
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * A quick start code for Spring Data Cloud Spanner.
 * It demonstrates how to use a SpannerRepository to execute read-write queries
 * generated from interface definitions.
 *
 */
@Component
public class SpannerRepositorySample {

  @Autowired
  SingerRepository singerRepository;

  public void runRepositoryExample() {
    List<Singer> lastNameSingers = this.singerRepository.findByLastName("a last name");

    int fistNameCount = this.singerRepository.countByFirstName("a first name");

    int deletedLastNameCount = this.singerRepository.deleteByLastName("a last name");
  }

}

管理 Spanner

如需获取有关 Spanner 数据库的信息、使用数据定义语言 (DDL) 语句更新架构，或者完成其他管理任务，您可以获取 SpannerDatabaseAdminTemplate Bean。

使用 @Autowired 注释可以自动获取该 Bean。然后，您可以在自己的类中使用 SpannerDatabaseAdminTemplate。

以下示例演示了获取和使用该 Bean 的类：

import com.google.cloud.spring.data.spanner.core.admin.SpannerDatabaseAdminTemplate;
import com.google.cloud.spring.data.spanner.core.admin.SpannerSchemaUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

/**
 * This sample demonstrates how to generate schemas for interleaved tables from POJOs and how to
 * execute DDL.
 */
@Component
public class SpannerSchemaToolsSample {

  @Autowired
  SpannerDatabaseAdminTemplate spannerDatabaseAdminTemplate;

  @Autowired
  SpannerSchemaUtils spannerSchemaUtils;

  /**
   * Creates the Singers table. Also creates the Albums table, because Albums is interleaved with
   * Singers.
   */
  public void createTableIfNotExists() {
    if (!this.spannerDatabaseAdminTemplate.tableExists("Singers")) {
      this.spannerDatabaseAdminTemplate.executeDdlStrings(
          this.spannerSchemaUtils
              .getCreateTableDdlStringsForInterleavedHierarchy(Singer.class),
          true);
    }
  }

  /**
   * Drops both the Singers and Albums tables using just a reference to the Singer entity type ,
   * because they are interleaved.
   */
  public void dropTables() {
    if (this.spannerDatabaseAdminTemplate.tableExists("Singers")) {
      this.spannerDatabaseAdminTemplate.executeDdlStrings(
          this.spannerSchemaUtils.getDropTableDdlStringsForInterleavedHierarchy(Singer.class),
          false);
    }
  }
}

后续步骤