R2DBC（“反应式关系数据库连接”）是一个社区驱动的 规范工作，以使用反应模式标准化对 SQL 数据库的访问。spring-doc.cn

包层次结构

Spring 框架的 R2DBC 抽象框架由两个不同的包组成：spring-doc.cn

使用 R2DBC 核心类控制基本的 R2DBC 处理和错误处理

本节介绍如何使用 R2DBC 核心类来控制基本的 R2DBC 处理。 包括错误处理。它包括以下主题：spring-doc.cn

用DatabaseClient

DatabaseClient是 R2DBC 核心包中的中心类。它处理 创建和释放资源，这有助于避免常见错误，例如 忘记关闭连接。它执行内核 R2DBC 的基本任务 工作流（例如语句创建和执行），让应用程序代码提供 SQL 并提取结果。类：DatabaseClientspring-doc.cn

客户端有一个功能齐全的 Fluent API，使用反应式类型进行声明式组合。spring-doc.cn

当你将 the 用于你的代码时，你只需要实现接口，为它们提供一个明确定义的协定。 给定类提供的 a，回调会创建一个 .对于映射函数也是如此，这些函数 提取结果。DatabaseClientjava.util.functionConnectionDatabaseClientFunctionPublisherRowspring-doc.cn

您可以通过直接实例化在 DAO 实现中使用 替换为引用，或者您可以在 Spring IoC 容器中配置它 并将其作为 bean 引用提供给 DAO。DatabaseClientConnectionFactoryspring-doc.cn

创建对象的最简单方法是通过静态工厂方法，如下所示：DatabaseClientspring-doc.cn

DatabaseClient client = DatabaseClient.create(connectionFactory);
val client = DatabaseClient.create(connectionFactory)
应该始终在 Spring IoC 中配置为 bean 容器。ConnectionFactory

上述方法使用默认设置创建一个。DatabaseClientspring-doc.cn

您还可以从 获取实例。 您可以通过以下方法自定义客户端：BuilderDatabaseClient.builder()spring-doc.cn

  • ….bindMarkers(…)：提供特定的 to configure named 参数绑定到数据库绑定标记翻译。BindMarkersFactoryspring-doc.cn

  • ….executeFunction(…)：设置对象获取 跑。ExecuteFunctionStatementspring-doc.cn

  • ….namedParameters(false)：禁用命名参数扩展。默认启用。spring-doc.cn

方言由 BindMarkersFactoryResolver 从 中解析，通常是通过检查 .
你可以让 Spring 通过注册一个 通过 . 发现 Bind Marker Provider 实现 使用 Spring 的 .ConnectionFactoryConnectionFactoryMetadataBindMarkersFactoryorg.springframework.r2dbc.core.binding.BindMarkersFactoryResolver$BindMarkerFactoryProviderMETA-INF/spring.factoriesBindMarkersFactoryResolverSpringFactoriesLoader

当前支持的数据库包括：spring-doc.cn

此类发出的所有 SQL 都记录在类别 对应于 Client 端实例的完全限定类名（通常为 ）。此外，每次执行都会在 reactive 序列来帮助调试。DEBUGDefaultDatabaseClientspring-doc.cn

以下部分提供了一些用法示例。这些例子 并不是 . 有关此内容，请参阅随附的 javadoc。DatabaseClientDatabaseClientspring-doc.cn

执行语句

DatabaseClient提供运行语句的基本功能。 以下示例显示了您需要包含的最小但功能齐全的内容 创建新表的代码：spring-doc.cn

Mono<Void> completion = client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);")
        .then();
client.sql("CREATE TABLE person (id VARCHAR(255) PRIMARY KEY, name VARCHAR(255), age INTEGER);")
        .await()

DatabaseClient旨在方便、流畅地使用。 它在 执行规范。上面的示例用于返回一个完成，该完成在查询（或 queries，如果 SQL 查询包含 multiple statements） 完成。then()Publisherspring-doc.cn

execute(…)接受 SQL 查询字符串或查询，以将实际的查询创建推迟到执行。Supplier<String>

查询 （SELECT)

SQL 查询可以通过对象或受影响的行数返回值。 可以返回更新的行数或行本身， 取决于发出的查询。RowDatabaseClientspring-doc.cn

以下查询从表中获取 and 列：idnamespring-doc.cn

Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person")
        .fetch().first();
val first = client.sql("SELECT id, name FROM person")
        .fetch().awaitSingle()

以下查询使用 bind 变量：spring-doc.cn

Mono<Map<String, Object>> first = client.sql("SELECT id, name FROM person WHERE first_name = :fn")
        .bind("fn", "Joe")
        .fetch().first();
val first = client.sql("SELECT id, name FROM person WHERE first_name = :fn")
        .bind("fn", "Joe")
        .fetch().awaitSingle()

您可能已经注意到了上面示例中的 of 用法。 是一个 continuation 运算符，用于指定要使用的数据量。fetch()fetch()spring-doc.cn

调用 返回结果中的第一行并丢弃其余行。 您可以使用以下运算符来使用数据：first()spring-doc.cn

  • first()返回整个结果的第一行。其 Kotlin 协程变体 针对不可为 null 的返回值命名，并且该值是可选的。awaitSingle()awaitSingleOrNull()spring-doc.cn

  • one()只返回一个结果，如果结果包含更多行，则失败。 使用 Kotlin 协程，对于一个值，或者该值可能是 .awaitOne()awaitOneOrNull()nullspring-doc.cn

  • all()返回结果的所有行。使用 Kotlin 协程时，请使用 .flow()spring-doc.cn

  • rowsUpdated()返回受影响的行数 （// count）。其 Kotlin 协程变体名为 。INSERTUPDATEDELETEawaitRowsUpdated()spring-doc.cn

在不指定进一步的映射详细信息的情况下，查询将返回表格结果 as 的键是映射到其列值的不区分大小写的列名。Mapspring-doc.cn

您可以通过提供一个 get 调用 for each 以便它可以返回任意值（奇异值、 集合和映射以及对象）。Function<Row, T>Rowspring-doc.cn

以下示例提取列并发出其值：namespring-doc.cn

Flux<String> names = client.sql("SELECT name FROM person")
        .map(row -> row.get("name", String.class))
        .all();
val names = client.sql("SELECT name FROM person")
        .map{ row: Row -> row.get("name", String.class) }
        .flow()

或者，有一个用于映射到单个值的快捷方式：spring-doc.cn

	Flux<String> names = client.sql("SELECT name FROM person")
			.mapValue(String.class)
			.all();

或者你可以映射到具有 bean 属性或记录组件的结果对象：spring-doc.cn

	// assuming a name property on Person
	Flux<Person> persons = client.sql("SELECT name FROM person")
			.mapProperties(Person.class)
			.all();
怎么样？null

关系数据库结果可以包含值。 Reactive Streams 规范禁止发出值。 该要求要求在提取器功能中正确处理。 虽然可以从 获取值，但不得发出值。您必须将任何值包装在对象中（例如，对于单个值），以确保永远不会直接返回值 通过提取器函数。nullnullnullnullRownullnullOptionalnullspring-doc.cn

更新 （， ， 和 ）INSERTUPDATEDELETEDatabaseClient

修改语句的唯一区别是这些语句通常 不返回表格数据，以便您用于使用结果。rowsUpdated()spring-doc.cn

以下示例显示了一个返回数字 的更新行数：UPDATEspring-doc.cn

Mono<Integer> affectedRows = client.sql("UPDATE person SET first_name = :fn")
        .bind("fn", "Joe")
        .fetch().rowsUpdated();
val affectedRows = client.sql("UPDATE person SET first_name = :fn")
        .bind("fn", "Joe")
        .fetch().awaitRowsUpdated()

将值绑定到查询

典型的应用程序需要参数化的 SQL 语句来 select 或 根据一些输入更新 Rows。这些通常是语句 受子句约束的 OR AND 语句接受 input 参数。如果满足以下条件，参数化语句会有 SQL 注入的风险 参数没有正确转义。 利用 R2DBC 的 API 来消除查询参数的 SQL 注入风险。 您可以使用运算符 并将参数绑定到实际的 .然后，您的 R2DBC 驱动程序运行 使用准备好的语句和参数替换的语句。SELECTWHEREINSERTUPDATEDatabaseClientbindexecute(…)Statementspring-doc.cn

参数绑定支持两种绑定策略：spring-doc.cn

以下示例显示了查询的参数绑定：spring-doc.cn

    db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
	    	.bind("id", "joe")
	    	.bind("name", "Joe")
			.bind("age", 34);

或者，您可以传入名称和值的映射：spring-doc.cn

	Map<String, Object> params = new LinkedHashMap<>();
	params.put("id", "joe");
	params.put("name", "Joe");
	params.put("age", 34);
	db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
			.bindValues(params);

或者你可以传入一个带有 bean 属性或记录组件的参数对象：spring-doc.cn

	// assuming id, name, age properties on Person
	db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
			.bindProperties(new Person("joe", "Joe", 34);
R2DBC 原生绑定标记

R2DBC 使用依赖于实际数据库供应商的数据库原生绑定标记。 例如，Postgres 使用索引标记，例如 、 、 。 另一个示例是 SQL Server，它使用前缀为 .$1$2$n@spring-doc.cn

这与 JDBC 不同，JDBC 需要作为绑定标记。 在 JDBC 中，实际的驱动程序将绑定标记转换为数据库原生 标记作为其语句执行的一部分。??spring-doc.cn

Spring Framework 的 R2DBC 支持允许您使用本机绑定标记或命名绑定 标记。:namespring-doc.cn

命名参数支持利用实例来扩展命名 parameters 添加到本机绑定标记中，从而为您提供 在各种数据库供应商之间具有一定程度的查询可移植性。BindMarkersFactoryspring-doc.cn

query-preprocessor 将命名参数展开到一系列 bind 中 标记，无需根据参数数量创建动态查询。 嵌套对象数组已扩展以允许使用（例如）选择列表。Collectionspring-doc.cn

请考虑以下查询：spring-doc.cn

SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50))

上述查询可以参数化并按如下方式运行：spring-doc.cn

List<Object[]> tuples = new ArrayList<>();
tuples.add(new Object[] {"John", 35});
tuples.add(new Object[] {"Ann",  50});

client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)")
	    .bind("tuples", tuples);
val tuples: MutableList<Array<Any>> = ArrayList()
tuples.add(arrayOf("John", 35))
tuples.add(arrayOf("Ann", 50))

client.sql("SELECT id, name, state FROM table WHERE (name, age) IN (:tuples)")
	    .bind("tuples", tuples)
选择列表的使用取决于供应商。

以下示例显示了使用谓词的更简单的变体：INspring-doc.cn

client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)")
	    .bind("ages", Arrays.asList(35, 50));
client.sql("SELECT id, name, state FROM table WHERE age IN (:ages)")
	    .bind("ages", arrayOf(35, 50))
R2DBC 本身不支持类似 Collection 的值。不过 在上面的例子中展开 given 适用于命名参数 在 Spring 的 R2DBC 支持中，例如用于上面所示的子句中。 但是，插入或更新数组类型的列（例如在 Postgres 中） 需要底层 R2DBC 驱动程序支持的数组类型： 通常是一个 Java 数组，例如 以更新列。 不要将 or 等作为数组参数传递。ListINString[]text[]Collection<String>

语句筛选器

有时，您需要在实际运行之前微调选项。为此，请注册一个过滤器 （） 替换为 to intercept 和 modify 语句的执行情况，如下例所示：StatementStatementStatementFilterFunctionDatabaseClientspring-doc.cn

client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
	    .filter((s, next) -> next.execute(s.returnGeneratedValues("id")))
	    .bind("name", …)
	    .bind("state", …);
client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
		.filter { s: Statement, next: ExecuteFunction -> next.execute(s.returnGeneratedValues("id")) }
		.bind("name", …)
		.bind("state", …)

DatabaseClient还公开了一个简化的重载，该重载接受 一个：filter(…)Function<Statement, Statement>spring-doc.cn

client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
	    .filter(statement -> s.returnGeneratedValues("id"));

client.sql("SELECT id, name, state FROM table")
	    .filter(statement -> s.fetchSize(25));
client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
	    .filter { statement -> s.returnGeneratedValues("id") }

client.sql("SELECT id, name, state FROM table")
	    .filter { statement -> s.fetchSize(25) }

StatementFilterFunctionimplementations 允许过滤 the 和 filter of objects。StatementResultspring-doc.cn

DatabaseClient最佳实践

类的实例一旦配置，就是线程安全的。这是 重要，因为这意味着您可以配置单个实例，然后将此共享引用安全地注入多个 DAO（或存储库）。 它是有状态的，因为它维护对 ， 但此状态不是对话状态。DatabaseClientDatabaseClientDatabaseClientConnectionFactoryspring-doc.cn

使用该类时的常见做法是在 Spring 配置文件中配置 a，然后 dependency-inject 将 bean 共享到您的 DAO 类中。在 .这导致了类似于以下内容的 DAO：DatabaseClientConnectionFactoryConnectionFactoryDatabaseClientConnectionFactoryspring-doc.cn

public class R2dbcCorporateEventDao implements CorporateEventDao {

	private DatabaseClient databaseClient;

	public void setConnectionFactory(ConnectionFactory connectionFactory) {
		this.databaseClient = DatabaseClient.create(connectionFactory);
	}

	// R2DBC-backed implementations of the methods on the CorporateEventDao follow...
}
class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao {

	private val databaseClient = DatabaseClient.create(connectionFactory)

	// R2DBC-backed implementations of the methods on the CorporateEventDao follow...
}

显式配置的替代方法是使用组件扫描和注释 支持依赖项注入。在这种情况下，你可以用 （这使它成为组件扫描的候选者） 来注释类，并 注释 setter 方法与 .以下示例显示了如何执行此操作：@ComponentConnectionFactory@Autowiredspring-doc.cn

@Component (1)
public class R2dbcCorporateEventDao implements CorporateEventDao {

	private DatabaseClient databaseClient;

	@Autowired (2)
	public void setConnectionFactory(ConnectionFactory connectionFactory) {
		this.databaseClient = DatabaseClient.create(connectionFactory); (3)
	}

	// R2DBC-backed implementations of the methods on the CorporateEventDao follow...
}
1 用 .@Component
2 使用 .ConnectionFactory@Autowired
3 使用 创建新的 .DatabaseClientConnectionFactory 
@Component (1)
class R2dbcCorporateEventDao(connectionFactory: ConnectionFactory) : CorporateEventDao { (2)

	private val databaseClient = DatabaseClient(connectionFactory) (3)

	// R2DBC-backed implementations of the methods on the CorporateEventDao follow...
}
1 用 .@Component
2 构造函数注入 .ConnectionFactory
3 使用 创建新的 .DatabaseClientConnectionFactory

无论您选择使用上述哪种模板初始化样式（或 not），则很少需要为每个 运行时间。配置后，实例是线程安全的。 如果您的应用程序访问多个 databases 中，您可能需要多个实例，这需要多个实例，然后需要多个不同配置的实例。DatabaseClientDatabaseClientDatabaseClientConnectionFactoryDatabaseClientspring-doc.cn

应该始终在 Spring IoC 中配置为 bean 容器。ConnectionFactory
方言由 BindMarkersFactoryResolver 从 中解析，通常是通过检查 .
你可以让 Spring 通过注册一个 通过 . 发现 Bind Marker Provider 实现 使用 Spring 的 .ConnectionFactoryConnectionFactoryMetadataBindMarkersFactoryorg.springframework.r2dbc.core.binding.BindMarkersFactoryResolver$BindMarkerFactoryProviderMETA-INF/spring.factoriesBindMarkersFactoryResolverSpringFactoriesLoader
execute(…)接受 SQL 查询字符串或查询，以将实际的查询创建推迟到执行。Supplier<String>
选择列表的使用取决于供应商。
R2DBC 本身不支持类似 Collection 的值。不过 在上面的例子中展开 given 适用于命名参数 在 Spring 的 R2DBC 支持中，例如用于上面所示的子句中。 但是，插入或更新数组类型的列（例如在 Postgres 中） 需要底层 R2DBC 驱动程序支持的数组类型： 通常是一个 Java 数组，例如 以更新列。 不要将 or 等作为数组参数传递。ListINString[]text[]Collection<String>
1 用 .@Component
2 使用 .ConnectionFactory@Autowired
3 使用 创建新的 .DatabaseClientConnectionFactory
1 用 .@Component
2 构造函数注入 .ConnectionFactory
3 使用 创建新的 .DatabaseClientConnectionFactory

检索自动生成的密钥

INSERT语句可能会在表中插入行时生成键 定义 auto-increment 或 identity 列。要完全控制 要生成的列名，只需注册一个 请求为所需列生成的键。StatementFilterFunctionspring-doc.cn

Mono<Integer> generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
		.filter(statement -> s.returnGeneratedValues("id"))
		.map(row -> row.get("id", Integer.class))
		.first();

// generatedId emits the generated key once the INSERT statement has finished
val generatedId = client.sql("INSERT INTO table (name, state) VALUES(:name, :state)")
		.filter { statement -> s.returnGeneratedValues("id") }
		.map { row -> row.get("id", Integer.class) }
		.awaitOne()

// generatedId emits the generated key once the INSERT statement has finished

控制数据库连接

本节涵盖：spring-doc.cn

用ConnectionFactory

Spring 通过 . A 是 R2DBC 规范的一部分，是一个常见的入口点 对于Drivers。它允许容器或框架隐藏连接池 以及应用程序代码中的事务管理问题。作为开发人员， 您无需了解有关如何连接到数据库的详细信息。那就是 设置 的管理员的责任。你 在开发和测试代码时，很可能会同时担任这两个角色，但您不会 必须知道生产数据源的配置方式。ConnectionFactoryConnectionFactoryConnectionFactoryspring-doc.cn

当您使用 Spring 的 R2DBC 层时，您可以使用 连接池实现由第三方提供。一个流行的 implementation 是 R2DBC Pool （）。Spring 中的实现 distribution 仅用于测试目的，不提供池化。r2dbc-poolspring-doc.cn

要配置 ：ConnectionFactoryspring-doc.cn

  1. 获取连接，就像通常获取 R2DBC 一样。ConnectionFactoryConnectionFactoryspring-doc.cn

  2. 提供 R2DBC URL （有关正确的值，请参阅驱动程序的文档）。spring-doc.cn

以下示例显示如何配置 ：ConnectionFactoryspring-doc.cn

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

用ConnectionFactoryUtils

该类是一个方便而强大的辅助类 ，它提供了从连接获取和关闭连接的方法（如有必要）。ConnectionFactoryUtilsstaticConnectionFactoryspring-doc.cn

它支持订阅者绑定连接，例如 .ContextR2dbcTransactionManagerspring-doc.cn

用SingleConnectionFactory

该类是 interface 的实现，它包装了一个在每次使用后都不会关闭的 single。SingleConnectionFactoryDelegatingConnectionFactoryConnectionspring-doc.cn

如果任何客户端代码在假设池连接的情况下调用（如使用 持久性工具），则应将该属性设置为 。此设置 返回包装物理连接的关闭抑制代理。请注意，您可以 不再将此对象强制转换为本机或类似对象。closesuppressClosetrueConnectionspring-doc.cn

SingleConnectionFactory主要是一个测试类，可用于特定要求 例如 pipelining （如果您的 R2DBC 驱动程序允许此类使用）。 与 pooled 相比，它始终重用相同的连接，从而避免 过度创建物理连接。ConnectionFactoryspring-doc.cn

用TransactionAwareConnectionFactoryProxy

TransactionAwareConnectionFactoryProxy是目标 的代理。 代理包装该目标以增加对 Spring 管理的事务的感知。ConnectionFactoryConnectionFactoryspring-doc.cn

如果您使用未以其他方式集成的 R2DBC 客户端，则需要使用此类 具有 Spring 的 R2DBC 支持。在这种情况下，您仍然可以使用此客户端，并且 同时，让这个 Client 端参与 Spring 管理的事务。它通常是 最好将 R2DBC 客户端与适当的访问权限集成以进行资源管理。ConnectionFactoryUtils

有关更多详细信息，请参见 TransactionAwareConnectionFactoryProxy javadoc。spring-doc.cn

用R2dbcTransactionManager

该类是 单个 R2DBC 。它将 R2DBC 从指定绑定到 subscriber ，可能允许每个 有一个 subscriber 。R2dbcTransactionManagerReactiveTransactionManagerConnectionFactoryConnectionConnectionFactoryContextConnectionConnectionFactoryspring-doc.cn

需要应用程序代码才能通过 检索 R2DBC，而不是 R2DBC 的标准 .所有框架类（例如 ）都使用 this 策略。如果不与事务管理器一起使用，则查找策略的行为为 完全一样，因此可以在任何情况下使用。ConnectionConnectionFactoryUtils.getConnection(ConnectionFactory)ConnectionFactory.create()DatabaseClientConnectionFactory.create()spring-doc.cn

如果您使用未以其他方式集成的 R2DBC 客户端，则需要使用此类 具有 Spring 的 R2DBC 支持。在这种情况下，您仍然可以使用此客户端，并且 同时，让这个 Client 端参与 Spring 管理的事务。它通常是 最好将 R2DBC 客户端与适当的访问权限集成以进行资源管理。ConnectionFactoryUtils