25.4 响应式数据访问：Spring Data R2DBC

在响应式编程体系中，传统基于 JDBC 的阻塞式数据访问会成为整个响应式链路的性能瓶颈 —— 线程会因等待数据库响应而被阻塞，违背了非阻塞的核心原则。R2DBC（Reactive Relational Database Connectivity） 正是为此而生，它以全异步、非阻塞的方式操作关系型数据库，是 Spring 生态中构建真正端到端响应式应用的数据库访问标准。

Spring Data R2DBC 将熟悉的 Spring Data 编程模型与 R2DBC 深度整合，让开发者可以用与 JPA 相似的方式编写响应式数据访问层，但需要明确：它并非 JPA 的响应式翻版，而是一个更贴近 SQL 的轻量级数据映射框架。

25.4.1 核心组件与基本配置

要使用 Spring Data R2DBC，首先引入对应数据库的驱动和 Spring Boot Starter：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
<dependency>
    <!-- 以 PostgreSQL 为例 -->
    <groupId>org.postgresql</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
</dependency>

Spring Boot 会自动探测 ConnectionFactory，你只需在配置文件中提供连接信息：

spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/orders
    username: app
    password: secret
    pool:
      initial-size: 5
      max-size: 20

如果需要显式定制，可使用 @Configuration 类创建 ConnectionFactory，例如配置连接池（r2dbc-pool）：

@Configuration
public class R2dbcConfig {
    @Bean
    public ConnectionFactory connectionFactory() {
        return ConnectionFactories.get(
            ConnectionFactoryOptions.builder()
                .option(DRIVER, "postgresql")
                .option(HOST, "localhost")
                .option(PORT, 5432)
                .option(USER, "app")
                .option(PASSWORD, "secret")
                .option(DATABASE, "orders")
                .build()
        );
    }
}

25.4.2 实体定义与 Repository

实体类使用 Spring Data 的通用注解来标记，无需 JPA 那样的 @Entity。最常用的是 @Table 和 @Id：

@Table("orders")
public class Order {
    @Id
    private Long id;
    private String customerName;
    private LocalDateTime createdAt;
    private BigDecimal amount;

    // 省略 getter/setter 和构造器
}

注意，R2DBC 不支持 JPA 的关联映射（如 @OneToMany），实体之间是独立的，需要手工处理关联查询。

定义 Repository 时，继承 ReactiveCrudRepository 或其变体：

public interface OrderRepository extends ReactiveCrudRepository<Order, Long> {
    Flux<Order> findByCustomerName(String customerName);         // 方法命名查询
    Mono<Order> findByCustomerNameAndAmount(String name, BigDecimal amount);

    @Query("SELECT * FROM orders WHERE amount > :minAmount")
    Flux<Order> findHighValueOrders(@Param("minAmount") BigDecimal minAmount);
}

ReactiveCrudRepository 内置了 save、findById、findAll、delete 等基础操作，返回 Mono 或 Flux。
方法命名查询 自动根据方法名生成 SQL，支持 findBy、existsBy、countBy 等前缀。
@Query 注解 可以直接编写原生 SQL，支持参数绑定和简单的 SpEL 表达式。

25.4.3 使用 DatabaseClient 进行灵活查询

当 Repository 的抽象不够用时，可以直接注入 DatabaseClient 来编写动态 SQL：

@Service
public class OrderService {
    private final DatabaseClient databaseClient;

    public OrderService(DatabaseClient databaseClient) {
        this.databaseClient = databaseClient;
    }

    public Flux<Order> searchOrders(String customerName, BigDecimal minAmount) {
        String sql = "SELECT * FROM orders WHERE customer_name = :name AND amount > :amount";
        return databaseClient.sql(sql)
                .bind("name", customerName)
                .bind("amount", minAmount)
                .map(row -> {
                    Order order = new Order();
                    order.setId(row.get("id", Long.class));
                    order.setCustomerName(row.get("customer_name", String.class));
                    order.setAmount(row.get("amount", BigDecimal.class));
                    order.setCreatedAt(row.get("created_at", LocalDateTime.class));
                    return order;
                })
                .all();    // 返回 Flux<Order>
    }
}

DatabaseClient 提供链式 API，支持命名参数或索引参数，结果可通过 map 进行行映射，或者使用 fetch() 获取单行或多行的 Mono/Flux。这是 R2DBC 在日常开发中最贴近 SQL 的实用工具。

25.4.4 事务管理

R2DBC 的事务也是完全非阻塞的，Spring 提供了 ReactiveTransactionManager 的实现。在方法上使用 @Transactional 即可声明事务边界：

@Service
public class OrderProcessingService {
    private final OrderRepository orderRepository;
    private final InventoryRepository inventoryRepository;

    public OrderProcessingService(OrderRepository orderRepository,
                                  InventoryRepository inventoryRepository) {
        this.orderRepository = orderRepository;
        this.inventoryRepository = inventoryRepository;
    }

    @Transactional
    public Mono<Void> placeOrder(Order order) {
        return orderRepository.save(order)
                .then(inventoryRepository.reduceStock(order.getProductId(), order.getQuantity()))
                .then();
    }
}

这里的关键是：@Transactional 必须配合返回 Mono 或 Flux 的操作，事务的提交与回滚会自动在响应式流结束时执行。如果流中任何一步发出错误信号，事务将自动回滚。

25.4.5 实战注意事项

实体映射无自动化：与 JPA 不同，R2DBC 不会自动生成表结构，字段映射默认按驼峰转下划线规则。如果列名与属性名不完全吻合，需使用 @Column 注解显式指定。
关联查询手工处理：实体之间一对一、一对多关系需要自己在仓库方法中编写多条 SQL 并组合 Mono.zip 或 flatMap 来组装结果，没有懒加载或级联操作。
主键生成策略受限：@Id 仅标记主键字段，生成策略依赖数据库特性（如 PostgreSQL 的 SERIAL、MySQL 的 AUTO_INCREMENT），或使用 UUID.randomUUID() 在应用层生成。
数据库兼容性：R2DBC 驱动目前支持 PostgreSQL、MySQL、Microsoft SQL Server、H2 等，生产环境优先选择 PostgreSQL，其驱动成熟度和性能均较好。
连接池选择：r2dbc-pool 是官方提供的连接池实现，参数可在 application.yml 中统一调整。注意连接泄漏排查一般通过日志和指标实现，工具链不如 JDBC 成熟。

25.4.6 完整实战片段

以下展示一个典型的响应式服务从 Controller 到 Repository 的全链路：

@RestController
@RequestMapping("/orders")
public class OrderController {
    private final OrderRepository orderRepository;

    public OrderController(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @GetMapping
    public Flux<Order> listOrders() {
        return orderRepository.findAll();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<Order> createOrder(@RequestBody Order order) {
        return orderRepository.save(order);
    }
}

在此链路中，数据库访问完全非阻塞，可与 WebFlux 无缝集成，在高并发场景下显著降低线程使用数量，提升吞吐量。

Spring Data R2DBC 虽然不是功能丰满的 ORM，但它保留了 SQL 的透明性与响应式模型的高效性，适合对 SQL 有精细控制需求、追求全栈响应式的项目。掌握好 ReactiveCrudRepository、DatabaseClient 和 @Transactional 三大利器，就能有效应对大多数关系型数据库的响应式访问需求。