Getting Started

启动工作环境的简单方法是在 Spring Tools 中或从 Spring Initializr 中创建一个基于 Spring 的项目。

An easy way to bootstrap setting up a working environment is to create a Spring-based project in Spring Tools or from Spring Initializr.

首先，你需要设置一个正在运行的数据库服务器。有关如何配置数据库以进行 R2DBC 访问，请参阅供应商文档。

First, you need to set up a running database server. Refer to your vendor documentation on how to configure your database for R2DBC access.

Requirements

Spring Data R2DBC 需要 Spring Framework {springVersion} 及更高版本。

Spring Data R2DBC requires Spring Framework {springVersion} and above.

在数据库方面，Spring Data R2DBC 需要一个 [驱动程序，r2dbc.drivers] 来对特定于供应商的功能与通用 SQL 功能进行抽象。Spring Data R2DBC 包括对以下数据库的直接支持：

In terms of databases, Spring Data R2DBC requires a r2dbc.drivers to abstract common SQL functionality over vendor-specific flavours. Spring Data R2DBC includes direct support for the following databases:

如果您使用其他数据库，那么应用程序将无法启动。[方言，r2dbc.dialects] 部分包含有关在这种情况下如何继续进行的更多详细信息。

If you use a different database then your application won’t start up. The r2dbc.dialects section contains further detail on how to proceed in such case.

Hello World

如何在 STS 中创建 Spring 项目：

To create a Spring project in STS:

  1. Go to File → New → Spring Template Project → Simple Spring Utility Project, and press Yes when prompted. Then enter a project and a package name, such as org.spring.r2dbc.example.

  2. Add the following to the pom.xml files dependencies element:

  3. Add the following to the pom.xml files dependencies element:[source, xml]

<dependencies>

  <!-- other dependency elements omitted -->

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

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

</dependencies>

  1. Change the version of Spring in the pom.xml to be[source, xml]

<spring.version>{springVersion}</spring-framework.version>

  1. Add the following location of the Spring Milestone repository for Maven to your pom.xml such that it is at the same level as your <dependencies/> element:[source, xml]

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

存储库也是 browseable here。

The repository is also browseable here.

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

You may also want to set the logging level to DEBUG to see some additional information. To do so, edit the application.properties file to have the following content:

logging.level.org.springframework.r2dbc=DEBUG

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

Then you can, for example, create a Person class to persist, as follows:

Unresolved include directive in modules/ROOT/pages/r2dbc/getting-started.adoc - include::example$r2dbc/Person.java[]

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

Next, you need to create a table structure in your database, as follows:

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

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

You also need a main application to run, as follows:

Unresolved include directive in modules/ROOT/pages/r2dbc/getting-started.adoc - include::example$r2dbc/R2dbcApp.java[]

当您运行主程序时，前面的示例将产生类似于以下内容的输出：

When you run the main program, the preceding examples produce output similar to the following:

2018-11-28 10:47:03,893 DEBUG amework.core.r2dbc.DefaultDatabaseClient: 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 amework.core.r2dbc.DefaultDatabaseClient: 908 - Executing SQL statement [INSERT INTO person (id, name, age) VALUES($1, $2, $3)]
2018-11-28 10:47:04,092 DEBUG amework.core.r2dbc.DefaultDatabaseClient: 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]

即便在这个简单的示例中，也有一些需要注意的地方：

Even in this simple example, there are few things to notice:

  • You can create an instance of the central helper class in Spring Data R2DBC (R2dbcEntityTemplate) by using a standard io.r2dbc.spi.ConnectionFactory object.

  • The mapper works against standard POJO objects without the need for any additional metadata (though you can, optionally, provide that information — see here.).

  • Mapping conventions can use field access.Notice that the Person class has only getters.

  • If the constructor argument names match the column names of the stored row, they are used to instantiate the object.

Examples Repository

有一个 GitHub repository with several examples 供您下载和使用，以便了解该库的工作原理。

There is a GitHub repository with several examples that you can download and play around with to get a feel for how the library works.

Connecting to a Relational Database with Spring

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

One of the first tasks when using relational databases and Spring is to create a io.r2dbc.spi.ConnectionFactory object by using the IoC container. Make sure to use a requirements.

Registering a ConnectionFactory Instance using Java Configuration

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

The following example shows an example of using Java-based bean metadata to register an instance of io.r2dbc.spi.ConnectionFactory:

Registering a io.r2dbc.spi.ConnectionFactory object using Java Configuration
@Configuration
public class ApplicationConfiguration extends AbstractR2dbcConfiguration {

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

这种方法让您可以使用标准 io.r2dbc.spi.ConnectionFactory 实例，容器使用 Spring 的 AbstractR2dbcConfiguration。与直接注册 ConnectionFactory 实例相比，该配置支持具有提供容器 ExceptionTranslator 实现的附加优势，该实现将 R2DBC 异常转换为 Spring 中带有 @Repository 注释的数据访问类中的 DataAccessException 等级结构中的异常。Spring 的 DAO 支持功能中描述了此层次结构和 @Repository 的使用。

This approach lets you use the standard io.r2dbc.spi.ConnectionFactory instance, with the container using Spring’s AbstractR2dbcConfiguration.As compared to registering a ConnectionFactory instance directly, the configuration support has the added advantage of also providing the container with an ExceptionTranslator implementation that translates R2DBC exceptions to exceptions in Spring’s portable DataAccessException hierarchy for data access classes annotated with the @Repository annotation.This hierarchy and the use of @Repository is described in {spring-framework-docs}/data-access.html[Spring’s DAO support features].

AbstractR2dbcConfiguration 还会注册 DatabaseClient，这对于数据库交互和 Repository 实现而言是必需的。

AbstractR2dbcConfiguration also registers DatabaseClient, which is required for database interaction and for Repository implementation.

Dialects

Spring Data R2DBC 使用 Dialect 封装特定于数据库或其驱动程序的行为。通过检查 ConnectionFactory，Spring Data R2DBC 响应数据库细节，并相应选择合适的数据库方言。如果您使用的是没有方言的数据库，那么您的应用程序将无法启动。在那种情况下，您将必须要求您的供应商提供 Dialect 实现。或者，您可以实现自己的 Dialect。

Spring Data R2DBC uses a Dialect to encapsulate behavior that is specific to a database or its driver. Spring Data R2DBC reacts to database specifics by inspecting the ConnectionFactory and selects the appropriate database dialect accordingly. If you use a database for which no dialect is available, then your application won’t start up. In that case, you’ll have to ask your vendor to provide a Dialect implementation. Alternatively, you can implement your own Dialect.

方言由 {spring-data-r2dbc-javadoc}/org/springframework/data/r2dbc/dialect/DialectResolver.html[DialectResolver] 根据 ConnectionFactory`解析，通常是通过检查 `ConnectionFactoryMetadata。+ 你可以通过通过 META-INF/spring.factories`注册实现 `org.springframework.data.r2dbc.dialect.DialectResolver$R2dbcDialectProvider`的类来让 Spring 自动发现你的 `R2dbcDialect。`DialectResolver`使用 Spring 的 `SpringFactoriesLoader`从类路径发现方言提供程序实现。为此：

Dialects are resolved by {spring-data-r2dbc-javadoc}/org/springframework/data/r2dbc/dialect/DialectResolver.html[DialectResolver] from a ConnectionFactory, typically by inspecting ConnectionFactoryMetadata. + You can let Spring auto-discover your R2dbcDialect by registering a class that implements org.springframework.data.r2dbc.dialect.DialectResolver$R2dbcDialectProvider through META-INF/spring.factories. DialectResolver discovers dialect provider implementations from the class path using Spring’s SpringFactoriesLoader. To do so:

  1. Implement your own Dialect.

  2. Implement a R2dbcDialectProvider returning the Dialect.

  3. Register the provider by creating a spring.factories resource under META-INF and perform the registration by adding a line org.springframework.data.r2dbc.dialect.DialectResolver$R2dbcDialectProvider=<fully qualified name of your R2dbcDialectProvider>