跳到主要内容

入门

Doubao 中英对照 Getting Started

初始化工作环境的一个简单方法，是在 Spring Tools 中或通过 Spring Initializr 创建一个基于 Spring 的项目。

首先，您需要设置一个正在运行的数据库服务器。关于如何配置数据库以支持 R2DBC 访问，请参阅您厂商的文档。

要求​

Spring Data R2DBC 需要 Spring Framework 7.0.9 或更高版本。

在数据库方面，Spring Data R2DBC 需要一个驱动程序，在各厂商特有的风味之上抽象出通用的 SQL 功能。Spring Data R2DBC 直接支持以下数据库：

如果您使用其他数据库，那么您的应用程序将无法启动。方言 一节包含关于这种情况下如何处理的更多细节。

Hello World​

要在 STS 中创建一个 Spring 项目：

  1. 前往 File → New → Spring Template Project → Simple Spring Utility Project，并在出现提示时按下 Yes。然后输入项目名和包名，例如 org.spring.r2dbc.example.

  2. 将以下内容添加到 pom.xml 文件的 dependencies 元素中：

    <dependencies>

        <!-- other dependency elements omitted -->

        <dependency>
            <groupId>org.springframework.data</groupId>
            <artifactId>spring-data-r2dbc</artifactId>
            <version>4.1.1</version>
        </dependency>

        <!-- a R2DBC driver -->
        <dependency>
            <groupId>io.r2dbc</groupId>
            <artifactId>r2dbc-h2</artifactId>
            <version>x.y.z</version>
        </dependency>

    </dependencies>
    xml

  3. 将 pom.xml 中 Spring 的版本更改为

    <spring.version>7.0.9</spring.version>
    xml

  4. 将以下供 Maven 使用的 Spring 里程碑仓库位置添加到您的 pom.xml 中，使其与 <dependencies/> 元素处于同一层级：

    <repositories>
        <repository>
            <id>spring-milestone</id>
            <name>Spring Maven MILESTONE Repository</name>
            <url>https://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    xml

该仓库也可在此浏览。

您可能还想将日志级别设置为 DEBUG 以查看更多信息。为此，请编辑 application.properties 文件，使其包含以下内容：

logging.level.org.springframework.r2dbc=DEBUG
none

然后，例如，您可以创建一个要持久化的 Person 类，如下所示：

public class Person {

	private final String id;
	private final String name;
	private final int age;

	public Person(String id, String name, int age) {
		this.id = id;
		this.name = name;
		this.age = age;
	}

	public String getId() {
		return id;
	}

	public String getName() {
		return name;
	}

	public int getAge() {
		return age;
	}

	@Override
	public String toString() {
		return "Person [id=" + id + ", name=" + name + ", age=" + age + "]";
	}
}
java

接下来，您需要在数据库中创建一个表结构，如下所示：

CREATE TABLE person(
    id VARCHAR(255) PRIMARY KEY,
    name VARCHAR(255),
    age INT
);
sql

您还需要一个要运行的主应用程序，如下所示：

import io.r2dbc.spi.ConnectionFactories;
import io.r2dbc.spi.ConnectionFactory;
import reactor.test.StepVerifier;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.springframework.data.r2dbc.core.R2dbcEntityTemplate;

public class R2dbcApp {

  private static final Log log = LogFactory.getLog(R2dbcApp.class);

  public static void main(String[] args) {

    ConnectionFactory connectionFactory = ConnectionFactories.get("r2dbc:h2:mem:///test?options=DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE");

    R2dbcEntityTemplate template = new R2dbcEntityTemplate(connectionFactory);

    template.getDatabaseClient().sql("CREATE TABLE person" +
        "(id VARCHAR(255) PRIMARY KEY," +
        "name VARCHAR(255)," +
        "age INT)")
      .fetch()
      .rowsUpdated()
      .as(StepVerifier::create)
      .expectNextCount(1)
      .verifyComplete();

    template.insert(Person.class)
      .using(new Person("joe", "Joe", 34))
      .as(StepVerifier::create)
      .expectNextCount(1)
      .verifyComplete();

    template.select(Person.class)
      .first()
      .doOnNext(it -> log.info(it))
      .as(StepVerifier::create)
      .expectNextCount(1)
      .verifyComplete();
  }
}
java

运行主程序时，前述示例会产生类似如下的输出：

2018-11-28 10:47:03,893 DEBUG ework.core.DatabaseClient: 310 - Executing SQL statement [CREATE TABLE person(
     id VARCHAR(255) PRIMARY KEY,
     name VARCHAR(255),
     age INT
 )]
2018-11-28 10:47:04,074 DEBUG ework.core.DatabaseClient: 908 - Executing SQL statement [INSERT INTO person (id, name, age) VALUES($1, $2, $3)]
2018-11-28 10:47:04,092 DEBUG ework.core.DatabaseClient: 575 - Executing SQL statement [SELECT id, name, age FROM person]
2018-11-28 10:47:04,436  INFO        org.spring.r2dbc.example.R2dbcApp:  43 - Person [id='joe', name='Joe', age=34]
none

即使在这个简单示例中，也有几点值得注意：

  • 您可以使用标准的 io.r2dbc.spi.ConnectionFactory 对象来创建 Spring Data R2DBC 中核心辅助类（R2dbcEntityTemplate）的实例。

  • 映射器可直接处理标准 POJO 对象，无需任何额外元数据（不过您也可以选择性地提供这些信息——请参阅此处。）。

  • 映射约定可以使用字段访问。请注意，Person 类只有 getter。

  • 如果构造函数参数名与所存储行的列名匹配，则会使用它们来实例化对象。

示例仓库​

有一个包含多个示例的 GitHub 仓库，您可以下载并动手试用，从而感受该库的工作方式。

使用 Spring 连接关系型数据库​

使用关系型数据库和 Spring 时，首要任务之一是使用 IoC 容器创建一个 io.r2dbc.spi.ConnectionFactory 对象。请务必使用受支持的数据库和驱动程序。

使用 Java 配置注册 ConnectionFactory 实例​

以下示例展示了使用基于 Java 的 bean 元数据来注册 io.r2dbc.spi.ConnectionFactory 实例的例子：

@Configuration
public class ApplicationConfiguration extends AbstractR2dbcConfiguration {

    @Override
    @Bean
    public ConnectionFactory connectionFactory() {
        return …
    }
}
java

这种方法让您可以使用标准的 io.r2dbc.spi.ConnectionFactory 实例，容器则使用 Spring 的 AbstractR2dbcConfiguration。与直接注册 ConnectionFactory 实例相比，配置支持的额外优势在于：它还为容器提供了一个 ExceptionTranslator 实现，可将 R2DBC 异常转换为 Spring 可移植的 DataAccessException 体系中的异常，供标注了 @Repository 注解的数据访问类使用。该体系以及 @Repository 的用法在 Spring 的 DAO 支持特性 中有描述。

AbstractR2dbcConfiguration 还会注册 DatabaseClient，它是数据库交互和仓库实现所必需的。

方言​

Spring Data R2DBC 使用 R2dbcDialect 来封装特定于某个数据库或其驱动程序的行为。Spring Data R2DBC 通过检查 ConnectionFactory 来应对数据库的具体情况，并据此选择合适的数据库方言。如果您使用的数据库没有可用的方言，那么您的应用程序将无法启动。在这种情况下，您需要请厂商提供一个 R2dbcDialect 实现。或者，您也可以实现自己的 R2dbcDialect。

提示

方言由 DialectResolver 从 ConnectionFactory 解析，通常是通过检查 ConnectionFactoryMetadata.
您可以通过 META-INF/spring.factories 注册一个实现了 org.springframework.data.r2dbc.dialect.DialectResolver$R2dbcDialectProvider 的类，让 Spring 自动发现您的 R2dbcDialect。DialectResolver 使用 Spring 的 SpringFactoriesLoader 从 classpath 发现方言提供器实现。为此：

  1. 实现您自己的 Dialect。

  2. 实现一个返回该 Dialect 的 R2dbcDialectProvider。

  3. 通过在 META-INF 下创建一个 spring.factories 资源来注册该提供器，并通过添加一行
    org.springframework.data.r2dbc.dialect.DialectResolver$R2dbcDialectProvider=<您的 R2dbcDialectProvider 的全限定名>