跳到主要内容

1. 介绍

dbVisitor 是基于 JDBC 标准构建的统一数据访问基座,核心理念是 One Access,愿景是 “One APIs Access Any DataBase”。 它面向结构化、半结构化和非结构化数据的存储与检索场景,让 Java 应用以统一 API 或一致的编程风格访问关系型、文档、键值、搜索和向量数据库。

例如,一个应用可以用 MySQL 保存业务记录、MongoDB 保存文档、Redis 保存缓存、Elasticsearch 检索内容、Milvus 检索向量,同时复用参数绑定、结果映射、Mapper 和连接访问方式。One Access 的目标是降低接入不同类别数据源的学习与维护成本,让新增数据源能够接入已有的数据访问方式。

双层适配器架构​

层次职责实现方式
应用适配层:统一“怎么操作”统一业务代码中的访问 API,管理查询语法与数据映射差异LambdaTemplate 和 BaseMapper 按方言生成 SQL 或目标命令;Mapper 注解与 XML 组织 SQL/DSL;JdbcTemplate 执行驱动支持的 SQL、DSL 或原生命令
协议适配层:统一“怎么接入”将数据源协议接入 JDBC 的连接、语句、参数与结果接口关系型数据库使用厂商 JDBC 驱动;jdbc-mongo、jdbc-elastic、jdbc-redis、jdbc-milvus 将对应数据库的 SDK/协议适配为 JDBC 驱动

两层通过 JDBC 衔接:业务代码使用应用层 API,应用层通过 JDBC 调用驱动,驱动访问目标数据源。应用层的多种 API 共享底层机制;驱动层也可独立供其他 JDBC 工具使用。这样既能统一完整的数据访问层,也能在现有项目中单独接入某个驱动适配器。

接入新数据源时,可基于 dbvisitor-driver 实现自定义 JDBC 适配器,继续复用上层访问方式;需要构造器能力时,再提供对应的数据库方言。

数据模型与访问场景​

数据模型或场景代表数据源接入方式与能力入口
结构化记录与关系查询MySQL、PostgreSQL、Oracle 等厂商 JDBC 驱动;按数据源查看能力
文档与半结构化数据MongoDBjdbc-mongo;文档操作与映射
键值、缓存与数据结构Redisjdbc-redis;命令访问与结果映射
内容搜索与非结构化文本检索Elasticsearchjdbc-elastic;搜索、Query DSL 与索引操作
向量与相似性检索Milvusjdbc-milvus;集合、标量过滤与向量操作

One Access 遵循“承认差异、管理差异”的原则:统一调用方式、参数绑定和结果接收,并保留数据源的原生能力。具体命令、构造器、事务、批处理和分页能力以数据源差异为准。例如,Redis 使用 JdbcTemplate 或 Mapper 执行命令,当前没有构造器方言。

按需求选择 API​

需求入口继续阅读
已有 SQL、DSL 或原生命令,需要绑定参数并读取结果或更新数据JdbcTemplate;查询用 queryForList、queryForObject,修改用 executeUpdate编程式 API
希望在支持的不同数据源上复用条件构造与 CRUD 写法LambdaTemplate 或 BaseMapper;由对应方言生成 SQL 或目标命令构造器 API
希望用 Java 接口组织 DAO,集中管理 SQL/DSLSession.createMapper(...);方法注解、BaseMapper 通用 CRUD、XML 可组合Mapper API
数据载体使用 Map区分复用实体映射的 Map 模式与直接使用表名、列名的 Freedom 模式Map 查询
需要向量相似性查询根据数据源方言选择支持的 KNN 排序或范围过滤向量查询

Configuration 创建 Session,由 Session 创建 Mapper 接口实例。模板、Mapper 和构造器可在同一应用中组合使用;选择统一构造器或原生命令时,根据目标数据源的能力决定。

选择依赖和运行环境​

使用完整双层架构时,引入 net.hasor:dbvisitor 和目标 JDBC 驱动:关系型数据库选择厂商驱动,NoSQL 或向量数据库选择对应的 jdbc-* 适配器。需要保留现有 Spring JDBC、MyBatis 等访问方式时,也可单独使用驱动适配器,按该驱动支持的命令与 JDBC 能力接入。

dbVisitor 可直接嵌入普通 Java 应用,也提供框架集成:Spring Boot 用 dbvisitor-spring-starter,普通 Spring 用 dbvisitor-spring,Hasor 用 dbvisitor-hasor,Solon 用 dbvisitor-solon-plugin,Guice 用 dbvisitor-guice;这些发布模块的 groupId 均为 net.hasor。

完成第一次调用​

  1. 确定数据模型与目标数据源,选择驱动和运行环境依赖,准备 DataSource 或 Connection,以及表、集合、索引等目标资源。
  2. 在方言支持时,通过 new LambdaTemplate(dataSource) 复用条件构造写法;已有 SQL/DSL 或命令时使用 new JdbcTemplate(dataSource)。需要 Mapper 时,通过 new Configuration().newSession(dataSource) 获取 Session。
  3. 根据单行、多行、标量或 Map 结果选择重载,使用参数绑定传入值,并处理返回值和异常。
  4. 明确连接与事务由谁管理。独立应用负责资源关闭;框架应用使用集成提供的对象和事务方式,避免另外创建一套连接环境。

起步代码见 普通 Java 项目;框架项目继续阅读 Spring、Hasor、Solon 或 Guice。

为什么使用它?​

过去关系型数据库占主导时,数据访问手段已趋多样并且涌现了大量基于 JDBC 的成熟工具;但随着 NoSQL 数据库兴起,数据存储形式更加多元访问 API 也变得更加复杂。 开发者需要在不同的 API 之间切换,增加了学习成本和使用难度。

而已有的数据访问技术如 Hibernate、MyBatis、Spring JDBC 等主要针对关系型数据库,在面对日益多样的非关系型存储时显现出局限性。

dbVisitor 的核心突破在于访问模式的无缝集成:开发者可以在同一项目中混合使用多种访问范式,并在关系型与非关系型存储之间获得统一体验。

在 API 设计上,dbVisitor 提供了与 Spring JdbcTemplate、MyBatis 近似风格的 API,这种设计可以让开发者避免接受大量新的概念和知识,从而减少学习成本和使用难度。

使用 dbVisitor​

  • dbVisitor 使用商业友好的 Apache 2.0 许可协议。
  • dbVisitor 核心模块只有 Cobble 一个依赖(cobble 是一个类似 Apache Commons 或 Guava 的工具包)
  • 已发布模块可通过 Maven Central 获取。

入门​

  • dbVisitor 支持通过 编程式 API 执行目标驱动支持的 SQL、DSL 或原生命令。
  • dbVisitor 支持在接口上通过注解标记以 声明式 API 方式来访问数据库。
  • dbVisitor 支持通过 构造器 用同一种 API 访问具备相应方言能力的数据源。
  • dbVisitor 支持使用 Map 查询模式 处理 Map 数据,可选择复用对象映射或直接使用表名、列名。
  • dbVisitor 支持使用 向量查询 进行 KNN 排序和向量范围过滤。
  • dbVisitor 支持通过 Mapper API 用 Java 接口组织 DAO(含注解、BaseMapper 通用 CRUD、Mapper 文件)。
  • dbVisitor 支持使用 使用 Mapper XML 文件配置统一管理 SQL 语句。
  • dbVisitor 提供多种方式处理 参数传递,相信在各种特殊场景中总能找到一个适合的方式处理它们。
  • dbVisitor 提供了一种更加灵活和高效的 规则 机制,通过规则可以更加简洁的维护应用程序 SQL。
  • dbVisitor 内置多种 类型处理器,可以方便的处理绝大多数数据库类型。
  • dbVisitor 支持在多个不同方法调用之间使用 数据库事务。
  • dbVisitor 使用统一的 API 或一致编程风格访问 Redis、MongoDB、Elasticsearch 和 Milvus。

框架整合​

  • dbvisitor-spring,支持最低使用 Spring 4.x 及 Spring Boot 2、Spring Boot 3 中自动配置和注入 dbVisitor 配置的 Mapper 和实例。
  • dbvisitor-solon,支持在使用了 Solon 作为应用程序开发框架的程序中自动配置和注入 dbVisitor 配置的 Mapper 和实例。
  • dbvisitor-hasor,支持在使用了 Hasor 作为应用程序开发框架的程序中自动配置和注入 dbVisitor 配置的 Mapper 和实例。
  • dbvisitor-guice,支持在使用了 Google Guice 依赖注入的应用程序中自动配置和注入 dbVisitor 配置的 Mapper 和实例。
  • jdbc-redis 是 Redis 的 JDBC 驱动适配器,它允许开发者使用标准的 JDBC 接口和 Redis 命令的方式来操作数据库。
  • jdbc-mongo 是 MongoDB 的 JDBC 驱动适配器,它允许开发者使用标准的 JDBC 接口和 MongoDB 命令的方式来操作数据库。
  • jdbc-elastic 是 ElasticSearch 的 JDBC 驱动适配器,它允许开发者使用标准的 JDBC 接口和 ElasticSearch QueryDSL 方式来操作数据。

版本事件​

  • 最新正式版:v6.8.2
  • 当前使用指南对应:6.8.2。
  • 6.x 版本 是一次全新的升级,在继承了 5.x 的功能,并针对不同风格 API 的实现做了较大改进使其在各个方面的用法和行为保持统一。
  • 5.x 版本 dbVisitor 正式从 Hasor 框架中分离出来并提供 编程式 API、声明式 API、构造器 三种不同风格的 API 来访问数据库。
  • 4.x 及以前版本中没有自己独立的版本,其发布跟随 Hasor 框架发布。

联系作者​