|
此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Framework 6.2.7! |
使用 R2DBC 进行数据访问
R2DBC(“响应式关系数据库连接”)是一个社区驱动的 规范工作,以使用反应模式标准化对 SQL 数据库的访问。
包层次结构
Spring 框架的 R2DBC 抽象框架由两个不同的包组成:
-
core:这org.springframework.r2dbc.corepackage 包含DatabaseClientclass 以及各种相关类。请参阅使用 R2DBC 核心类控制基本的 R2DBC 处理和错误处理。 -
connection:这org.springframework.r2dbc.connectionpackage 包含一个 Utility 类 为了方便ConnectionFactory访问和各种简单ConnectionFactory实现 可用于测试和运行未修改的 R2DBC。请参阅控制数据库连接。
使用 R2DBC 核心类控制基本的 R2DBC 处理和错误处理
本节介绍如何使用 R2DBC 核心类来控制基本的 R2DBC 处理。 包括错误处理。它包括以下主题:
用DatabaseClient
DatabaseClient是 R2DBC 核心包中的中心类。它处理
创建和释放资源,这有助于避免常见错误,例如
忘记关闭连接。它执行内核 R2DBC 的基本任务
工作流(例如语句创建和执行),让应用程序代码提供
SQL 并提取结果。这DatabaseClient类:
-
运行 SQL 查询
-
更新语句和存储过程调用
-
执行迭代
Result实例 -
捕获 R2DBC 异常并将它们转换为通用的、信息量更大的 异常层次结构在
org.springframework.dao包。 (请参阅一致的异常层次结构。
客户端有一个功能齐全的 Fluent API,使用响应式类型进行声明式组合。
当您使用DatabaseClient对于您的代码,您只需实现java.util.function接口,为它们提供明确定义的 Contract。
给定一个Connection由DatabaseClient类、Functioncallback 创建一个Publisher.对于映射函数也是如此,这些函数
提取 ARow结果。
您可以使用DatabaseClient在 DAO 实现中通过直接实例化
替换为ConnectionFactory引用,或者你可以在 Spring IoC 容器中配置它
并将其作为 bean 引用提供给 DAO。
创建DatabaseClientobject 通过静态工厂方法,如下所示:
-
Java
-
Kotlin
DatabaseClient client = DatabaseClient.create(connectionFactory);
val client = DatabaseClient.create(connectionFactory)
这ConnectionFactory应该始终配置为 Spring IoC 中的 bean
容器。 |
上述方法创建了一个DatabaseClient使用默认设置。
您还可以获取Builderinstance fromDatabaseClient.builder().
您可以通过以下方法自定义客户端:
-
….bindMarkers(…):供应特定的BindMarkersFactory配置命名 参数绑定到数据库绑定标记翻译。 -
….executeFunction(…):将ExecuteFunction如何Statement对象 get 跑。 -
….namedParameters(false):禁用命名参数扩展。默认启用。
方言的解析方式为BindMarkersFactoryResolver从ConnectionFactory,通常通过检查ConnectionFactoryMetadata.您可以让 Spring 自动发现您的 BindMarkersFactory通过注册
实现org.springframework.r2dbc.core.binding.BindMarkersFactoryResolver$BindMarkerFactoryProvider通过META-INF/spring.factories.BindMarkersFactoryResolver发现 Bind Marker Provider 实现
使用 Spring 的SpringFactoriesLoader. |
当前支持的数据库包括:
-
H2 系列
-
MariaDB的
-
Microsoft SQL 服务器
-
MySQL (MySQL的
-
Postgres
此类发出的所有 SQL 都记录在DEBUG类别下的级别
对应于客户端实例的完全限定类名(通常为DefaultDatabaseClient).此外,每次执行都会在
reactive 序列来帮助调试。
以下部分提供了一些示例DatabaseClient用法。这些例子
并不是DatabaseClient.
有关此内容,请参阅随附的 javadoc。
执行语句
DatabaseClient提供运行语句的基本功能。
以下示例显示了您需要包含的最小但功能齐全的内容
创建新表的代码:
-
Java
-
Kotlin
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旨在方便、流畅地使用。
它在
执行规范。前面的示例使用了then()返回 completionPublisher)在 query(或 queries,如果 SQL 查询包含
multiple statements) 完成。
execute(…)接受 SQL 查询字符串或查询Supplier<String>将实际的查询创建推迟到执行。 |
查询 (SELECT)
SQL 查询可以通过以下方式返回值Rowobjects 或受影响的行数。DatabaseClient可以返回更新的行数或行本身,
取决于发出的查询。
以下查询获取id和namecolumns 中的命令:
-
Java
-
Kotlin
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 变量:
-
Java
-
Kotlin
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()
您可能已经注意到了fetch()在上面的示例中。fetch()是一个
continuation 运算符,用于指定要使用的数据量。
叫first()返回结果中的第一行并丢弃其余行。
您可以使用以下运算符来使用数据:
-
first()返回整个结果的第一行。其 Kotlin 协程变体 被命名为awaitSingle()对于不可为 null 的返回值和awaitSingleOrNull()如果值为可选。 -
one()只返回一个结果,如果结果包含更多行,则失败。 使用 Kotlin 协程,awaitOne()对于恰好一个值或awaitOneOrNull()如果值可能是null. -
all()返回结果的所有行。使用 Kotlin 协程时,请使用flow(). -
rowsUpdated()返回受影响的行数 (INSERT/UPDATE/DELETEcount) 的 Count) 中其 Kotlin 协程变体名为awaitRowsUpdated().
在不指定进一步的映射详细信息的情况下,查询将返回表格结果
如Map其键是不区分大小写的列名,映射到其列值。
您可以通过提供Function<Row, T>这样就可以得到
为每个Row因此它可以返回任意值(奇异值、
集合和映射以及对象)。
以下示例提取namecolumn 并发出其值:
-
Java
-
Kotlin
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()
或者,有一个用于映射到单个值的快捷方式:
Flux<String> names = client.sql("SELECT name FROM person")
.mapValue(String.class)
.all();
或者你可以映射到具有 bean 属性或记录组件的结果对象:
// assuming a name property on Person
Flux<Person> persons = client.sql("SELECT name FROM person")
.mapProperties(Person.class)
.all();
更新 (INSERT,UPDATE和DELETE) 替换为DatabaseClient
修改语句的唯一区别是这些语句通常
不返回表格数据,因此您使用rowsUpdated()以使用结果。
以下示例显示了UPDATE返回 Number 的语句
的更新行数:
-
Java
-
Kotlin
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。这些通常是SELECT语句
受WHERE子句或INSERT和UPDATE接受
input 参数。如果满足以下条件,参数化语句会有 SQL 注入的风险
参数没有正确转义。DatabaseClient利用 R2DBC 的bindAPI 以消除查询参数的 SQL 注入风险。
您可以使用execute(…)算子
并将参数绑定到实际的Statement.然后,您的 R2DBC 驱动程序运行
使用准备好的语句和参数替换的语句。
参数绑定支持两种绑定策略:
-
By Index,使用从 0 开始的参数索引。
-
By Name (按名称) 使用占位符名称。
以下示例显示了查询的参数绑定:
db.sql("INSERT INTO person (id, name, age) VALUES(:id, :name, :age)")
.bind("id", "joe")
.bind("name", "Joe")
.bind("age", 34);
或者,您可以传入名称和值的映射:
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 属性或记录组件的参数对象:
// 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);
名为Collectionparameters 的 Bind
标记,无需根据参数数量创建动态查询。
嵌套对象数组已扩展以允许使用(例如)选择列表。
请考虑以下查询:
SELECT id, name, state FROM table WHERE (name, age) IN (('John', 35), ('Ann', 50))
上述查询可以参数化并按如下方式运行:
-
Java
-
Kotlin
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)
| 选择列表的使用取决于提供商。 |
以下示例显示了一个使用IN谓词:
-
Java
-
Kotlin
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 的值。不过
扩展给定的List在上面的示例中,适用于 named parameters
在 Spring 的 R2DBC 支持中,例如用于IN子句,如上所示。
但是,插入或更新数组类型的列(例如在 Postgres 中)
需要底层 R2DBC 驱动程序支持的数组类型:
通常是一个 Java 数组,例如String[]要更新text[]列。
不通过Collection<String>或类似的数组参数。 |
语句筛选器
有时您需要对实际Statement在它运行之前。为此,请注册一个StatementFilter
(StatementFilterFunction) 替换为DatabaseClient以拦截
modify 语句的执行情况,如下例所示:
-
Java
-
Kotlin
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>:
-
Java
-
Kotlin
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) }
StatementFilterFunction实现允许过滤Statement并过滤Result对象。
DatabaseClient最佳实践
的实例DatabaseClient类是线程安全的,一旦配置。这是
重要,因为这意味着您可以配置DatabaseClient然后安全地将此共享引用注入多个 DAO(或存储库)。
这DatabaseClient是有状态的,因为它维护了对ConnectionFactory,
但此状态不是对话状态。
使用DatabaseClientclass 来配置ConnectionFactory在 Spring 配置文件中,然后 dependency-inject
那个分享了ConnectionFactorybean 添加到您的 DAO 类中。这DatabaseClient在
的 setterConnectionFactory.这导致了类似于以下内容的 DAO:
-
Java
-
Kotlin
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...
}
显式配置的替代方法是使用组件扫描和注释
支持依赖项注入。在这种情况下,您可以使用@Component(这使它成为组件扫描的候选者)并注释ConnectionFactorysetter
method 替换为@Autowired.以下示例显示了如何执行此作:
-
Java
-
Kotlin
@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 | 注释ConnectionFactorysetter 方法替换为@Autowired. |
| 3 | 新建DatabaseClient使用ConnectionFactory. |
@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 | 新建DatabaseClient使用ConnectionFactory. |
无论您选择使用上述哪种模板初始化样式(或
not),则很少需要创建DatabaseClient每个类
运行时间。配置后,DatabaseClient实例是线程安全的。
如果您的应用程序访问多个
databases 中,您可能需要多个DatabaseClient实例,这需要多个ConnectionFactory随后,多个不同配置的DatabaseClient实例。
检索自动生成的密钥
INSERT语句可能会在表中插入行时生成键
定义 auto-increment 或 identity 列。要完全控制
要生成的列名,只需注册一个StatementFilterFunction那
请求为所需列生成的键。
-
Java
-
Kotlin
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
控制数据库连接
本节涵盖:
用ConnectionFactory
Spring 通过ConnectionFactory.
一个ConnectionFactory是 R2DBC 规范的一部分,是一个常见的入口点
对于Drivers。它允许容器或框架隐藏连接池
以及应用程序代码中的事务管理问题。作为开发人员,
您无需了解有关如何连接到数据库的详细信息。那就是
设置ConnectionFactory.你
在开发和测试代码时,很可能会同时担任这两个角色,但您不会
必须知道生产数据源的配置方式。
当您使用 Spring 的 R2DBC 层时,您可以使用
连接池实现由第三方提供。一个流行的
implementation 是 R2DBC 池 (r2dbc-pool).Spring 中的实现
distribution 仅用于测试目的,不提供池化。
要配置ConnectionFactory:
-
获取与
ConnectionFactory因为您通常会获得 R2DBCConnectionFactory. -
提供 R2DBC URL (有关正确的值,请参阅驱动程序的文档)。
以下示例显示如何配置ConnectionFactory:
-
Java
-
Kotlin
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
这ConnectionFactoryUtilsclass 是一个方便而强大的辅助类
提供static从中获取连接的方法ConnectionFactory并关闭连接(如有必要)。
它支持订阅者Context-bound 连接,例如R2dbcTransactionManager.
用SingleConnectionFactory
这SingleConnectionFactoryclass 是DelegatingConnectionFactory接口,该接口将单个Connection每次使用后都不会关闭。
如果任何客户端代码调用close假设使用池连接(如使用
持久化工具),您应该将suppressCloseproperty 设置为true.此设置
返回包装物理连接的关闭抑制代理。请注意,您可以
不再将此 Cast this 转换为本机Connection或类似对象。
SingleConnectionFactory主要是一个测试类,可用于特定要求
例如 pipelining (如果您的 R2DBC 驱动程序允许此类使用)。
与池化ConnectionFactory,它会一直重用相同的连接,避免
过度创建物理连接。
用TransactionAwareConnectionFactoryProxy
TransactionAwareConnectionFactoryProxy是目标的代理ConnectionFactory.
代理将该目标ConnectionFactory以增加对 Spring 管理的事务的感知。
如果您使用未以其他方式集成的 R2DBC 客户端,则需要使用此类
具有 Spring 的 R2DBC 支持。在这种情况下,您仍然可以使用此客户端,并且
同时,让这个 Client 端参与 Spring 管理的事务。它通常是
最好将 R2DBC 客户端与适当的ConnectionFactoryUtils用于资源管理。 |
请参阅TransactionAwareConnectionFactoryProxyjavadoc 了解更多详情。
用R2dbcTransactionManager
这R2dbcTransactionManagerclass 是一个ReactiveTransactionManagerimplementation for
单个 R2DBCConnectionFactory.它绑定了一个 R2DBCConnection从指定的ConnectionFactory对订阅者Context,可能允许一个订阅者Connection对于每个ConnectionFactory.
需要应用程序代码来检索 R2DBCConnection通过ConnectionFactoryUtils.getConnection(ConnectionFactory),而不是 R2DBC 的标准ConnectionFactory.create().所有框架类(例如DatabaseClient) 使用这个
策略。如果不与事务管理器一起使用,则查找策略的行为为
完全一样ConnectionFactory.create()因此,在任何情况下都可以使用。