WCDK-R2DBC 导读：从 R2DBC 规范到响应式数据访问

WCDK R2DBC：面向 Spring WebFlux 的响应式数据库访问框架推荐

在 Spring WebFlux 微服务开发中，如果继续使用传统 JDBC，容易在响应式链路中引入阻塞操作。WCDK R2DBC 是一个基于 Spring Boot、Spring Data R2DBC 和 Project Reactor 的响应式数据库访问框架，适合构建高并发、非阻塞的 WebFlux 应用。

项目地址：

GitHub – WCDK/wcdk-r2dbc · GitHubContribute to WCDK/wcdk-r2dbc development by creating an account on GitHub.https://github.com/WCDK/wcdk-r2dbc

wcdk-r2dbc – AtomGithttps://gitcode.com/wc936248/wcdk-r2dbc

一、项目简介

WCDK R2DBC 面向 Spring Boot 3.5+，提供了更加完整、易用的响应式数据访问能力，主要特性包括：

• Repository 动态代理
• 响应式 CRUD
• 派生查询方法
• QueryWrapper 和 Lambda Wrapper
• 响应式事务
• 多数据源路由
• 逻辑删除
• XML SQL
• SQL 生命周期拦截与观测
• MySQL、PostgreSQL、Oracle、达梦数据库方言支持
• 基于 r2dbc-pool 的连接池管理

Repository、Service 和 Controller 可以保持完整的 Mono / Flux 链路，避免传统阻塞式数据库访问带来的性能问题。

二、为什么推荐 WCDK R2DBC？

1. 保持全链路响应式

框架的查询和更新接口统一使用 Mono、Flux 返回值，能够自然适配 Spring WebFlux。

public Mono<User> findById(Long id) {
return userRepository.selectById(id);
}

public Flux<User> findEnabledUsers() {
return userRepository.findByStatus(1);
}

使用过程中应避免调用 block()，也不要在业务代码中手动调用 subscribe()。

2. 减少样板代码

只需要定义实体和 Repository 接口，即可获得常用的增删改查能力：

@Repository
public interface UserRepository extends BaseRepository<User> {

Flux<User> findByStatus(Integer status);
}

框架支持 findBy、countBy、existsBy、deleteBy、update…By… 等派生查询方法。

3. 查询能力灵活

简单查询可以直接使用方法名派生查询，复杂查询则可以使用 QueryWrapper：

QueryWrapper<User> wrapper = new QueryWrapper<>();

wrapper.eq("status", 1)
.like("email", "%@example.com")
.orderByDesc("id")
.limit(20)
.offset(0);

Flux<User> users = userRepository.selectList(wrapper);

同时支持范围查询、模糊查询、集合查询、嵌套 AND / OR、排序和分页等功能。

4. 更适合企业级场景

WCDK R2DBC 不仅提供基础 CRUD，还支持：

• 响应式事务
• 多数据源切换
• 逻辑删除
• XML 动态 SQL
• SQL 审计与性能统计
• Micrometer 观测
• 多种数据库方言
• 自定义类型转换

因此，它不仅适合简单项目，也适合企业级微服务和数据访问层建设。

三、快速开始

1. 添加 Maven 依赖

<dependency>
<groupId>com.wcdk.r2dbc</groupId>
<artifactId>wcdk-r2dbc</artifactId>
<version>3.5.16</version>
</dependency>

然后根据实际数据库添加对应的 R2DBC 驱动，例如 PostgreSQL：

<dependency>
<groupId>org.postgresql</groupId>
<artifactId>r2dbc-postgresql</artifactId>
<version>1.0.7.RELEASE</version>
<scope>runtime</scope>
</dependency>

2. 配置数据库

spring:
r2dbc:
url: r2dbc:postgresql://localhost:5432/demo
username: postgres
password: postgres

wcdk:
r2dbc:
enabled: true
sql-log-enabled: true

3. 启用 Repository 扫描

@EnableWcdkR2dbcRepositories(
basePackages = "com.example.repository"
)
@SpringBootApplication
public class Application {

public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}

4. 定义实体和 Repository

@Table("sys_user")
public record User(
@Id Long id,
@Column("user_name") String userName,
String email,
Integer status
) {
}
@Repository
public interface UserRepository extends BaseRepository<User> {

Flux<User> findByStatus(Integer status);
}

四、响应式事务

WCDK R2DBC 支持 TransactionalOperator：

public Mono<User> create(User user) {
return transactionalOperator.transactional(
userRepository.insert(user)
);
}

也可以结合 Spring 标准的 @Transactional 使用，适合多个数据库操作需要保证原子性的业务场景。

五、适用场景

WCDK R2DBC 特别适合以下项目：

• Spring WebFlux 微服务
• 高并发 API 服务
• 响应式后台管理系统
• 物联网和实时数据服务
• 多数据源业务系统
• 需要统一 Repository 规范的企业项目
• 希望从 JDBC 逐步迁移到 R2DBC 的应用

六、总结

如果你的项目已经采用 Spring WebFlux，并且希望构建真正的非阻塞数据访问链路，WCDK R2DBC 是一个值得关注的开源项目。

它在 Spring Data R2DBC 的基础上补充了 Repository 动态代理、派生查询、Wrapper、事务、多数据源、逻辑删除、XML SQL 和 SQL 观测等企业级能力，能够有效减少数据访问层的重复代码，同时保留较好的扩展性和控制力。

推荐关注并试用：

GitHub – WCDK/wcdk-r2dbc · GitHub

wcdk-r2dbc – AtomGit

项目具体功能和配置以仓库 README 为准。查看 WCDK R2DBC 官方仓库